System.IO.BinaryWriter Class

Summary

Writes primitive types in binary to a stream and supports writing strings in a specific encoding.

C# Syntax:

[Serializable] public class BinaryWriter : IDisposable

A derived class can override the methods of this class to give unique character encodings.

System.IO Namespace | Encoding

System.IO.BinaryWriter Member List:

Public Constructors

ctor #2	Overloaded: .ctor(Stream output) Initializes a new instance of the BinaryWriter class based on the supplied stream and using UTF-8 as the encoding for strings.
ctor #3	Overloaded: .ctor(Stream output, Encoding encoding) Initializes a new instance of the BinaryWriter class based on the supplied stream and a specific character encoding.

Public Fields

Null	A BinaryWriter with no backing store.

Public Properties

BaseStream

Read-only Gets the BinaryWriter 's underlying stream.

Public Methods

Close	Closes the current BinaryWriter 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.
Flush	Clears all buffers for the current writer and causes any buffered data to be written to the underlying device.
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.
Seek	Sets the position within the current stream.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
Write	Overloaded: Write(bool value) Writes a one-byte Boolean value to the current stream, with zero representing false and one representing true.
Write	Overloaded: Write(byte value) Writes an unsigned byte to the current stream and advances the stream position by one byte.
Write	Overloaded: Write(byte[] buffer) Writes a byte array to the underlying stream.
Write	Overloaded: Write(char ch) Writes a Unicode character to the current stream and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.
Write	Overloaded: Write(char[] chars) Writes a character array to the current stream and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.
Write	Overloaded: Write(decimal value) Writes a decimal value to the current stream and advances the stream position by eight bytes.
Write	Overloaded: Write(double value) Writes an eight-byte floating-point value to the current stream and advances the stream position by eight bytes.
Write	Overloaded: Write(short value) Writes a two-byte signed integer to the current stream and advances the stream position by two bytes.
Write	Overloaded: Write(int value) Writes a four-byte signed integer to the current stream and advances the stream position by four bytes.
Write	Overloaded: Write(long value) Writes an eight-byte signed integer to the current stream and advances the stream position by eight bytes.
Write	Overloaded: Write(sbyte value) Writes a signed byte to the current stream and advances the stream position by one byte.
Write	Overloaded: Write(float value) Writes a four-byte floating-point value to the current stream and advances the stream position by four bytes.
Write	Overloaded: Write(string value) Writes a length-prefixed string to this stream in the current Encoding of the BinaryWriter, and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.
Write	Overloaded: Write(ushort value) Writes a two-byte unsigned integer to the current stream and advances the stream position by two bytes.
Write	Overloaded: Write(uint value) Writes a four-byte unsigned integer to the current stream and advances the stream position by four bytes.
Write	Overloaded: Write(ulong value) Writes an eight-byte unsigned integer to the current stream and advances the stream position by eight bytes.
Write	Overloaded: Write(byte[] buffer, int index, int count) Writes a region of a byte array to the current stream.
Write	Overloaded: Write(char[] chars, int index, int count) Writes a section of a character array to the current stream, and advances the current position of the stream in accordance with the Encoding used and perhaps the specific characters being written to the stream.

Protected Constructors

ctor #1

Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the BinaryWriter class that writes to a stream.

Protected Fields

OutStream

Holds the underlying stream.

Protected Methods

Dispose	Releases the unmanaged resources used by the BinaryWriter and optionally releases the managed resources.
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.
Write7BitEncodedInt	Writes a 32-bit integer in a compressed format.

Hierarchy:

• System.Object
• System.IO.BinaryWriter

System.IO.BinaryWriter Member Details

Summary

Initializes a new instance of the BinaryWriter class that writes to a stream.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected BinaryWriter();

Return to top

Summary

Initializes a new instance of the BinaryWriter class based on the supplied stream and using UTF-8 as the encoding for strings.

C# Syntax:

public BinaryWriter(    Stream output );

output

The output stream.

Exceptions

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

Return to top

Summary

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

C# Syntax:

public BinaryWriter(    Stream output,    Encoding encoding );

output

The supplied stream.

encoding

The character encoding.

Exceptions

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

Return to top

Summary

A BinaryWriter with no backing store.

C# Syntax:

public static readonly BinaryWriter Null;

Return to top

Summary

Holds the underlying stream.

C# Syntax:

protected Stream OutStream;

Return to top

Summary

Gets the BinaryWriter 's underlying stream.

C# Syntax:

public virtual Stream BaseStream {get;}

Return to top

Summary

Closes the current BinaryWriter and the underlying stream.

C# Syntax:

public virtual void Close();

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

Flushing the stream will not flush its underlying encoder unless you explicitly call BinaryWriter.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 BinaryWriter 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.

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

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

C# Syntax:

~BinaryWriter();

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

Return to top

Summary

Clears all buffers for the current writer and causes any buffered data to be written to the underlying device.

C# Syntax:

public virtual void Flush();

All derived classes should override Flush to ensure that all buffered data is sent to the stream.

Flushing the stream will not flush its underlying encoder unless you explicitly call Flush or BinaryWriter.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

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

Sets the position within the current stream.

C# Syntax:

public virtual long Seek(int offset, Seek(    int offset,    SeekOrigin origin );

offset

A byte offset relative to origin.

origin

A field of SeekOrigin indicating the reference point from which the new position is to be obtained.

Return Value:

The position with the current stream.

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

Summary

Writes a one-byte Boolean value to the current stream, with zero representing false and one representing true.

C# Syntax:

public virtual void Write(    bool value );

value

The Boolean value to write (zero or one).

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes an unsigned byte to the current stream and advances the stream position by one byte.

C# Syntax:

public virtual void Write(    byte value );

value

The unsigned byte to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a byte array to the underlying stream.

C# Syntax:

public virtual void Write(    byte[] buffer );

buffer

A byte array containing the data to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.
ArgumentNullException	buffer is null.

Return to top

Summary

Writes a Unicode character to the current stream and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.

C# Syntax:

public virtual void Write(    char ch );

ch

The character to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a character array to the current stream and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.

C# Syntax:

public virtual void Write(    char[] chars );

chars

A character array containing the data to write.

Exceptions

Exception Type	Condition
ArgumentNullException	chars is null.
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a decimal value to the current stream and advances the stream position by eight bytes.

C# Syntax:

public virtual void Write(    decimal value );

value

The decimal value to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs.

Return to top

Summary

Writes an eight-byte floating-point value to the current stream and advances the stream position by eight bytes.

C# Syntax:

public virtual void Write(    double value );

value

The eight-byte floating-point value to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a two-byte signed integer to the current stream and advances the stream position by two bytes.

C# Syntax:

public virtual void Write(    short value );

value

The two-byte signed integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a four-byte signed integer to the current stream and advances the stream position by four bytes.

C# Syntax:

public virtual void Write(    int value );

value

The four-byte signed integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes an eight-byte signed integer to the current stream and advances the stream position by eight bytes.

C# Syntax:

public virtual void Write(    long value );

value

The eight-byte signed integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a signed byte to the current stream and advances the stream position by one byte.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual void Write(    sbyte value );

value

The signed byte to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a four-byte floating-point value to the current stream and advances the stream position by four bytes.

C# Syntax:

public virtual void Write(    float value );

value

The four-byte floating-point value to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a length-prefixed string to this stream in the current Encoding of the BinaryWriter, and advances the current position of the stream in accordance with the Encoding used and the specific characters being written to the stream.

C# Syntax:

public virtual void Write(    string value );

value

The value to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.
ArgumentNullException	value is null.

A length-prefixed string represents the string length by prefixing to the string a single byte or word that contains the length of that string.

Return to top

Summary

Writes a two-byte unsigned integer to the current stream and advances the stream position by two bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual void Write(    ushort value );

value

The two-byte unsigned integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a four-byte unsigned integer to the current stream and advances the stream position by four bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual void Write(    uint value );

value

The four-byte unsigned integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes an eight-byte unsigned integer to the current stream and advances the stream position by eight bytes.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public virtual void Write(    ulong value );

value

The eight-byte unsigned integer to write.

Exceptions

Exception Type	Condition
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a region of a byte array to the current stream.

C# Syntax:

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

buffer

A byte array containing the data to write.

index

The starting point in buffer from which to begin reading.

count

The number of bytes to write.

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, such as the stream being closed.

Return to top

Summary

Writes a section of a character array to the current stream, and advances the current position of the stream in accordance with the Encoding used and perhaps the specific characters being written to the stream.

C# Syntax:

public virtual void Write(    char[] chars,    int index,    int count );

chars

A character array containing the data to write.

index

The starting point in buffer from which to begin reading.

count

The number of characters to write.

Exceptions

Exception Type	Condition
ArgumentException	The buffer length minus index is less than count.
ArgumentNullException	chars is null.
ArgumentOutOfRangeException	index or count is negative.
IOException	An I/O error occurs, such as the stream being closed.

Return to top

Summary

Writes a 32-bit integer in a compressed format.

C# Syntax:

protected void Write7BitEncodedInt(    int value );

value

The 32-bit integer to be written.

Exceptions

Exception Type	Condition
EndOfStreamException	The end of the stream is reached.
IOException	The stream is closed.

The integer of the value parameter is written out seven bits at a time, starting with the seven least-significant bits. The high bit of a byte indicates whether there are more bytes to be written after this one.

If value will fit in seven bits, it takes only one byte of space. If value will not fit in seven bits, the high bit is set on the first byte and written out.value is then shifted by seven bits and the next byte is written. This process is repeated until the entire integer has been written.

Return to top

Top of page