System.IO.BinaryReader Class

Summary

Reads primitive data types as binary values in a specific encoding.

C# Syntax:

public class BinaryReader : IDisposable

System.IO Namespace

System.IO.BinaryReader Member List:

Public Constructors

ctor #1	Overloaded: .ctor(Stream input) Initializes a new instance of the BinaryReader class based on the supplied stream and using UTF8Encoding.
ctor #2	Overloaded: .ctor(Stream input, Encoding encoding) Initializes a new instance of the BinaryReader class based on the supplied stream and a specific character encoding.

Public Properties

BaseStream

Read-only Exposes access to the underlying stream of the BinaryReader.

Public Methods

Close	Closes the current reader and the underlying stream.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
PeekChar	Returns the next available character and does not advance the byte or character position.
Read	Overloaded: Read() Reads characters from the underlying stream and advances the current position of the stream in accordance with the Encoding used and the specific character being read from the stream.
Read	Overloaded: Read(byte[] buffer, int index, int count) Reads count bytes from the stream with index as the starting point in the byte array.
Read	Overloaded: Read(char[] buffer, int index, int count) Reads count characters from the stream with index as the starting point in the character array.
ReadBoolean	Reads a Boolean from the current stream and advances the current position of the stream by one byte.
ReadByte	Reads the next byte from the current stream and advances the current position of the stream by 1 byte.
ReadBytes	Reads count bytes from the current stream into a byte array and advances the current position by count bytes.
ReadChar	Reads the next character from the current stream and advances the current position of the stream in accordance with the Encoding used and the specific character being read from the stream.
ReadChars	Reads count characters from the current stream, returns the data in a character array, and advances the current position in accordance with the Encoding used and the specific character being read from the stream.
ReadDecimal	Reads a decimal value from the current stream and advances the current position of the stream by sixteen bytes.
ReadDouble	Reads an 8-byte floating point value from the current stream and advances the current position of the stream by eight bytes.
ReadInt16	Reads a 2-byte signed integer from the current stream and advances the current position of the stream by two bytes.
ReadInt32	Reads a 4-byte signed integer from the current stream and advances the current position of the stream by four bytes.
ReadInt64	Reads an 8-byte signed integer from the current stream and advances the current position of the stream by four bytes.
ReadSByte	Reads a signed byte from this stream and advances the current position of the stream by one byte.
ReadSingle	Reads a 4-byte floating point value from the current stream and advances the current position of the stream by four bytes.
ReadString	Reads a String from the current stream. The String is prefixed with the length, encoded as an integer 7 bits at a time.
ReadUInt16	Reads a 2-byte unsigned integer from the current stream using little endian encoding and advances the position of the stream by two bytes.
ReadUInt32	Reads a 4-byte unsigned integer from the current stream and advances the position of the stream by four bytes.
ReadUInt64	Reads an 8-byte unsigned integer from the current stream and advances the position of the stream by eight bytes.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Dispose	Releases the unmanaged resources used by the BinaryReader and optionally releases the managed resources.
FillBuffer	Fills the internal buffer with the specified number of bytes read from the stream.
Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.
Read7BitEncodedInt	Reads in a 32-bit integer in a compressed format.

Hierarchy:

• System.Object
• System.IO.BinaryReader

System.IO.BinaryReader Member Details

Summary

Initializes a new instance of the BinaryReader class based on the supplied stream and using UTF8Encoding.

C# Syntax:

public BinaryReader(    Stream input );

input

A stream.

Exceptions

Exception Type	Condition
ArgumentException	The stream does not support writing, or the stream is already closed.
ArgumentNullException	input is null.

Return to top

Summary

Initializes a new instance of the BinaryReader class based on the supplied stream and a specific character encoding.

C# Syntax:

public BinaryReader(    Stream input,    Encoding encoding );

input

The supplied stream.

encoding

The character encoding.

Exceptions

Exception Type	Condition
ArgumentException	The stream does not support reading.
ArgumentNullException	input or encoding is null.

Return to top

Summary

Exposes access to the underlying stream of the BinaryReader.

C# Syntax:

public virtual Stream BaseStream {get;}

Using the underlying stream while reading or while using the BinaryReader can cause data loss and corruption. For example, the same bytes might be read more than once, bytes might be skipped, or character reading might become unpredictable.

Return to top

Summary

Closes the current reader and the underlying stream.

C# Syntax:

public virtual void Close();

This implementation of Close calls the BinaryReader.Dispose method passing a true value.

Flushing the stream will not flush its underlying encoder unless you explicitly call Stream.Flush or Close. Setting StreamWriter.AutoFlush to true means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters.

Return to top

Summary

Releases the unmanaged resources used by the BinaryReader and optionally releases the managed resources.

C# Syntax:

protected virtual void Dispose(    bool disposing );

disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.

This method is called by the public Dispose() method and the Object.Finalize method.Dispose() invokes the protected Dispose(Boolean) method with the disposing parameter set to true. Object.Finalize invokes Dispose with disposing set to false.

When the disposing parameter is true, this method releases all resources held by any managed objects that this BinaryReader references. This method invokes the Dispose() method of each referenced object.

Notes to inheritors: Dispose can be called multiple times by other objects. When overriding Dispose(Boolean), be careful not to reference objects that have been previously disposed of in an earlier call to Dispose. For more information about how to implement Dispose(Boolean), see the conceptual topic at MSDN: implementingdisposemethod.

For more information about Dispose and Object.Finalize, see the conceptual topic at MSDN: cleaningupunmanagedresources and the conceptual topic at MSDN: overridingfinalizemethod.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Fills the internal buffer with the specified number of bytes read from the stream.

C# Syntax:

protected virtual void FillBuffer(    int numBytes );

numBytes

The number of bytes to be read.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached before numBytes could be read.
IOException	An I/O error occurs.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~BinaryReader();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the next available character and does not advance the byte or character position.

C# Syntax:

public virtual int PeekChar();

Return Value:

The next available character, or -1 if no more characters are available or the stream does not support seeking.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.

Return to top

Summary

Reads characters from the underlying stream and advances the current position of the stream in accordance with the Encoding used and the specific character being read from the stream.

C# Syntax:

public virtual int Read();

Return Value:

The next character from the input stream, or -1 if no characters are currently available.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.

Return to top

Summary

Reads count bytes from the stream with index as the starting point in the byte array.

C# Syntax:

public virtual int Read(    byte[] buffer,    int index,    int count );

buffer

The buffer to read data into.

index

The starting point in the buffer at which to begin reading into the buffer.

count

The number of characters to read.

Return Value:

The number of characters read into buffer. This might be less than the number of bytes requested if that many bytes are not available, or it might be zero if the end of the stream is reached.

Exceptions

Exception Type	Condition
ArgumentException	The buffer length minus index is less than count.
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	index or count is negative.
IOException	An I/O error occurs.

Return to top

Summary

Reads count characters from the stream with index as the starting point in the character array.

C# Syntax:

public virtual int Read(    char[] buffer,    int index,    int count );

buffer

The buffer to read data into.

index

The starting point in the buffer at which to begin reading into the buffer.

count

The number of characters to read.

Return Value:

The total number of characters read into the buffer. This might be less than the number of characters requested if that many characters are not currently available, or it might be zero if the end of the stream is reached.

Exceptions

Exception Type	Condition
ArgumentException	The buffer length minus index is less than count.
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	index or count is negative.
IOException	An I/O error occurs.

Return to top

Summary

Reads in a 32-bit integer in a compressed format.

C# Syntax:

protected int Read7BitEncodedInt();

Return Value:

A 32-bit integer in compressed format.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through BinaryWriter.Write7BitEncodedInt.

Return to top

Summary

Reads a Boolean from the current stream and advances the current position of the stream by one byte.

C# Syntax:

public virtual bool ReadBoolean();

Return Value:

true if the byte is non-zero; otherwise false.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads the next byte from the current stream and advances the current position of the stream by 1 byte.

C# Syntax:

public virtual byte ReadByte();

Return Value:

The next byte read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads count bytes from the current stream into a byte array and advances the current position by count bytes.

C# Syntax:

public virtual byte[] ReadBytes(    int count );

count

The number of bytes to read.

Return Value:

A byte array containing data read from the underlying stream. This might be less than the number of bytes requested if the end of the stream is reached.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.
ArgumentOutOfRangeException	count is negative.

Return to top

Summary

Reads the next character from the current stream and advances the current position of the stream in accordance with the Encoding used and the specific character being read from the stream.

C# Syntax:

public virtual char ReadChar();

Return Value:

A character read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads count characters from the current stream, returns the data in a character array, and advances the current position in accordance with the Encoding used and the specific character being read from the stream.

C# Syntax:

public virtual char[] ReadChars(    int count );

count

The number of characters to read.

Return Value:

A character array containing data read from the underlying stream. This might be less than the number of characters requested if the end of the stream is reached.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.
ArgumentOutOfRangeException	count is negative.

Return to top

Summary

Reads a decimal value from the current stream and advances the current position of the stream by sixteen bytes.

C# Syntax:

public virtual decimal ReadDecimal();

Return Value:

An decimal value read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads an 8-byte floating point value from the current stream and advances the current position of the stream by eight bytes.

C# Syntax:

public virtual double ReadDouble();

Return Value:

An 8-byte floating point value read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a 2-byte signed integer from the current stream and advances the current position of the stream by two bytes.

C# Syntax:

public virtual short ReadInt16();

Return Value:

A 2-byte signed integer read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a 4-byte signed integer from the current stream and advances the current position of the stream by four bytes.

C# Syntax:

public virtual int ReadInt32();

Return Value:

A 4-byte signed integer read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads an 8-byte signed integer from the current stream and advances the current position of the stream by four bytes.

C# Syntax:

public virtual long ReadInt64();

Return Value:

An 8-byte signed integer read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a signed byte from this stream and advances the current position of the stream by one byte.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual sbyte ReadSByte();

Return Value:

A signed byte read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a 4-byte floating point value from the current stream and advances the current position of the stream by four bytes.

C# Syntax:

public virtual float ReadSingle();

Return Value:

A 4-byte floating point value read from the current stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a String from the current stream. The String is prefixed with the length, encoded as an integer 7 bits at a time.

C# Syntax:

public virtual string ReadString();

Return Value:

The string being read.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a 2-byte unsigned integer from the current stream using little endian encoding and advances the position of the stream by two bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual ushort ReadUInt16();

Return Value:

A 2-byte unsigned integer read from this stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads a 4-byte unsigned integer from the current stream and advances the position of the stream by four bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual uint ReadUInt32();

Return Value:

A 4-byte unsigned integer read from this stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Summary

Reads an 8-byte unsigned integer from the current stream and advances the position of the stream by eight bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual ulong ReadUInt64();

Return Value:

An 8-byte unsigned integer read from this stream.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	An I/O error occurs.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page