System.IO.MemoryStream Class

Summary

Creates a stream whose backing store is memory.

C# Syntax:

[Serializable] public class MemoryStream : Stream

The MemoryStream class creates streams that have memory as a backing store instead of a disk or a network connection.MemoryStream encapsulates data stored as an unsigned byte array that is initialized upon creation of a MemoryStream object, or the array can be created as empty. The encapsulated data is directly accessible in memory. Memory streams can reduce the need for temporary buffers and files in an application.

The current position of a stream is the position at which the next read or write operation could take place. The current position can be retrieved or set through the MemoryStream.Seek method. When a new instance of MemoryStream is created, the current position is set to zero.

Memory streams created with an unsigned byte array provide a non-resizable stream view of the data, and can only be written to. When using a byte array, you can neither append to nor shrink the stream, although you might be able to modify the existing contents depending on the parameters passed into the constructor. Empty memory streams are resizable, and can be written to and read from.

System.IO Namespace

System.IO.MemoryStream Member List:

Public 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 MemoryStream class with an expandable capacity initialized to zero.
ctor #2	Overloaded: .ctor(byte[] buffer) Initializes a new non-resizable instance of the MemoryStream class based on the specified byte array.
ctor #3	Overloaded: .ctor(int capacity) Initializes a new instance of the MemoryStream class with an expandable capacity initialized as specified.
ctor #4	Overloaded: .ctor(byte[] buffer, bool writable) Initializes a new non-resizable instance of the MemoryStream class based on the specified byte array with the MemoryStream.CanWrite property set as specified.
ctor #5	Overloaded: .ctor(byte[] buffer, int index, int count) Initializes a new non-resizable instance of the MemoryStream class based on the specified region (index) of a byte array.
ctor #6	Overloaded: .ctor(byte[] buffer, int index, int count, bool writable) Initializes a new non-resizable instance of the MemoryStream class based on the specified region of a byte array, with the MemoryStream.CanWrite property set as specified.
ctor #7	Overloaded: .ctor(byte[] buffer, int index, int count, bool writable, bool publiclyVisible) Initializes a new instance of the MemoryStream class based on the specified region of a byte array, with the MemoryStream.CanWrite property set as specified, and the ability to call MemoryStream.GetBuffer set as specified.

Public Properties

CanRead	Read-only Overridden: Gets a value indicating whether the current stream supports reading.
CanSeek	Read-only Overridden: Gets a value indicating whether the current stream supports seeking.
CanWrite	Read-only Overridden: Gets a value indicating whether the current stream supports writing.
Capacity	Read-write Gets or sets the number of bytes allocated for this stream.
Length	Read-only Overridden: Gets the length of the stream in bytes .
Position	Read-write Overridden: Gets or sets the current position within the stream.

Public Methods

BeginRead (inherited from System.IO.Stream)	See base class member description: System.IO.Stream.BeginRead Begins an asynchronous read operation.
BeginWrite (inherited from System.IO.Stream)	See base class member description: System.IO.Stream.BeginWrite Begins an asynchronous write operation.
Close	Overridden: Closes the stream for reading and writing.
CreateObjRef (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.CreateObjRef Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
EndRead (inherited from System.IO.Stream)	See base class member description: System.IO.Stream.EndRead Waits for the pending asynchronous read to complete.
EndWrite (inherited from System.IO.Stream)	See base class member description: System.IO.Stream.EndWrite Ends an asynchronous write operation.
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	Overridden: Overrides Stream.Flush so that no action is performed.
GetBuffer	Returns the array of unsigned bytes from which this stream was created.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.GetLifetimeService Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
InitializeLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.InitializeLifetimeService Obtains a lifetime service object to control the lifetime policy for this instance.
Read	Overridden: Reads a block of bytes from the current stream and writes the data to buffer.
ReadByte	Overridden: Reads a byte from the current stream.
Seek	Overridden: Sets the position within the current stream to the specified value.
SetLength	Overridden: Sets the length of the current stream to the specified value.
ToArray	Writes the entire stream contents to a byte array, regardless of the MemoryStream.Position property.
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	Overridden: Writes a block of bytes to the current stream using data read from buffer.
WriteByte	Overridden: Writes a byte to the current stream at the current position.
WriteTo	Writes the entire contents of this memory stream to another stream.

Protected Methods

CreateWaitHandle (inherited from System.IO.Stream)	See base class member description: System.IO.Stream.CreateWaitHandle Allocates a WaitHandle object.
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.

Hierarchy:

• System.Object
• System.MarshalByRefObject
• System.IO.Stream
• System.IO.MemoryStream

System.IO.MemoryStream Member Details

Summary

Initializes a new instance of the MemoryStream class with an expandable capacity initialized to zero.

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

C# Syntax:

public MemoryStream();

The MemoryStream.CanRead, MemoryStream.CanSeek, and MemoryStream.CanWrite properties are all set to true.

The capacity of the current stream automatically increases when you use the MemoryStream.SetLength method to set the length to a value larger than the capacity of the current stream.

This constructor exposes the underlying stream, which MemoryStream.GetBuffer returns.

Return to top

Summary

Initializes a new non-resizable instance of the MemoryStream class based on the specified byte array.

C# Syntax:

public MemoryStream(    byte[] buffer );

buffer

The array of unsigned bytes from which to create the current stream.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.

The MemoryStream.CanRead, MemoryStream.CanSeek, and MemoryStream.CanWrite properties are all set to true. MemoryStream.Capacity is set to the length of the specified byte array. The new stream can be written to, but is not resizable.

The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see MemoryStream.SetLength).

This constructor does not expose the underlying stream. MemoryStream.GetBuffer throws UnauthorizedAccessException.

Return to top

Summary

Initializes a new instance of the MemoryStream class with an expandable capacity initialized as specified.

C# Syntax:

public MemoryStream(    int capacity );

capacity

The initial size of the internal array in bytes.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	capacity is negative.

The MemoryStream.CanRead, MemoryStream.CanSeek, and MemoryStream.CanWrite properties are all set to true.

The capacity automatically increases when you use the MemoryStream.SetLength method to set the length to a value larger than the capacity of the current stream. Except for a MemoryStream constructed with a byte[] parameter, write operations at the end of a MemoryStream expand the MemoryStream.

This constructor exposes the underlying stream that MemoryStream.GetBuffer returns.

Return to top

Summary

Initializes a new non-resizable instance of the MemoryStream class based on the specified byte array with the MemoryStream.CanWrite property set as specified.

C# Syntax:

public MemoryStream(    byte[] buffer,    bool writable );

buffer

The array of unsigned bytes from which to create this stream.

writable

The setting of the MemoryStream.CanWrite property, which determines whether the stream supports writing.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.

The MemoryStream.CanRead and MemoryStream.CanSeek properties are both set to true. MemoryStream.Capacity is set to the length of the specified byte array.

The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see MemoryStream.SetLength).

This constructor does not expose the underlying stream. MemoryStream.GetBuffer throws UnauthorizedAccessException.

Return to top

Summary

Initializes a new non-resizable instance of the MemoryStream class based on the specified region (index) of a byte array.

C# Syntax:

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

buffer

The array of unsigned bytes from which to create this stream.

index

The index into buffer at which the stream begins.

count

The length of the stream in bytes.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	index or count is less than zero.
ArgumentException	The sum of index and count is greater than the length of buffer.

The MemoryStream.CanRead, MemoryStream.CanSeek, and MemoryStream.CanWrite properties are all set to true, but the capacity cannot be changed. MemoryStream.Capacity is set to count.

The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see MemoryStream.SetLength).

This constructor does not expose the underlying stream. MemoryStream.GetBuffer throws UnauthorizedAccessException. However, you can write to the stream.

Return to top

Summary

Initializes a new non-resizable instance of the MemoryStream class based on the specified region of a byte array, with the MemoryStream.CanWrite property set as specified.

C# Syntax:

public MemoryStream(    byte[] buffer,    int index,    int count,    bool writable );

buffer

The array of unsigned bytes from which to create this stream.

index

The index in buffer at which the stream begins.

count

The length of the stream in bytes.

writable

The setting of the MemoryStream.CanWrite property, which determines whether the stream supports writing.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	index or count are negative.
ArgumentException	The sum of index and count is greater than the length of buffer.

The MemoryStream.CanRead and MemoryStream.CanSeek properties are both set to true. MemoryStream.Capacity is set to count.

The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see MemoryStream.SetLength).

This constructor does not expose the underlying stream. MemoryStream.GetBuffer throws UnauthorizedAccessException. However, you can write to the stream.

Return to top

Summary

Initializes a new instance of the MemoryStream class based on the specified region of a byte array, with the MemoryStream.CanWrite property set as specified, and the ability to call MemoryStream.GetBuffer set as specified.

C# Syntax:

public MemoryStream(    byte[] buffer,    int index,    int count,    bool writable,    bool publiclyVisible );

buffer

The array of unsigned bytes from which to create this stream.

index

The index into buffer at which the stream begins.

count

The length of the stream in bytes.

writable

The setting of the MemoryStream.CanWrite property, which determines whether the stream supports writing.

publiclyVisible

true to enable MemoryStream.GetBuffer, which returns the unsigned byte array from which the stream was created; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	index or count is negative.
ArgumentException	The buffer length minus index is less than count.

The MemoryStream.CanRead and MemoryStream.CanSeek properties are both set to true. MemoryStream.Capacity is set to count.

The new stream instance can be written to, but the MemoryStream.Capacity of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see MemoryStream.SetLength).

Return to top

Summary

Gets a value indicating whether the current stream supports reading.

C# Syntax:

public override bool CanRead {get;}

If a class derived from Stream does not support reading, calls to the MemoryStream.Read and MemoryStream.ReadByte methods throw a NotSupportedException.

If the stream is closed, this property returns false.

Return to top

Summary

Gets a value indicating whether the current stream supports seeking.

C# Syntax:

public override bool CanSeek {get;}

If a class derived from Stream does not support seeking, calls to MemoryStream.Length, MemoryStream.SetLength, MemoryStream.Position, and MemoryStream.Seek throw a NotSupportedException.

If the stream is closed, this property returns false.

Return to top

Summary

Gets a value indicating whether the current stream supports writing.

C# Syntax:

public override bool CanWrite {get;}

If a class derived from Stream does not support writing, a call to Stream.SetLength, Stream.Write, or Stream.WriteByte throws a NotSupportedException.

If the stream is closed, this property returns false.

Return to top

Summary

Gets or sets the number of bytes allocated for this stream.

C# Syntax:

public virtual int Capacity {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	A capacity is set that is negative or less than the current length of the stream.
NotSupportedException	set is invoked on a stream that is closed or whose capacity cannot be modified.

Capacity is the buffer length for system-provided byte arrays.Capacity cannot be set to a value less than the current length of the stream.

Return to top

Summary

Gets the length of the stream in bytes .

C# Syntax:

public override long Length {get;}

Exceptions

Exception Type	Condition
IOException	The stream is closed.
ObjectDisposedException	Methods were called after the stream was closed.

Return to top

Summary

Gets or sets the current position within the stream.

C# Syntax:

public override long Position {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The position is set to a negative value.
IOException	The stream is closed.
ObjectDisposedException	Methods were called after the stream was closed.

The position must not be more than one byte beyond the end of the stream.

Return to top

Inherited
See base class member description: System.IO.Stream.BeginRead

Summary

Begins an asynchronous read operation.

C# Syntax:

public virtual IAsyncResult BeginRead(    byte[] buffer,    int offset,    int count,    AsyncCallback callback,    object state );

buffer

The buffer to read the data into.

offset

The byte offset in buffer at which to begin writing data read from the stream.

count

The maximum number of bytes to read.

callback

An optional asynchronous callback, to be called when the read is complete.

state

A user-provided object that distinguishes this particular asynchronous read request from other requests.

Return Value:

An IAsyncResult that represents the asynchronous read, which could still be pending.

Exceptions

Exception Type	Condition
IOException	Attempted an asynchronous read past the end of the file, or a disk error occurs.
ArgumentException	One or more or the arguments is invalid.
ObjectDisposedException	Methods were called after the stream was closed.
NotSupportedException	The current Stream implementation does not support the read operation.

Pass the IAsyncResult return value to the Stream.EndRead method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called BeginRead or in a callback passed to BeginRead.

The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes.

Multiple simultaneous asynchronous requests render the request completion order uncertain.

Use the Stream.CanRead property to determine whether the current instance supports reading.

If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from BeginRead. Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the threadpool thread and become visible upon a call to EndRead. Exceptions thrown by the threadpool thread will not be visible when calling Stream.EndWrite.

Return to top

Inherited
See base class member description: System.IO.Stream.BeginWrite

Summary

Begins an asynchronous write operation.

C# Syntax:

public virtual IAsyncResult BeginWrite(    byte[] buffer,    int offset,    int count,    AsyncCallback callback,    object state );

buffer

The buffer to write data to. This should generally be greater than 64 kilobytes.

offset

The byte offset in buffer at which to begin writing.

count

The maximum number of bytes to write.

callback

An optional asynchronous callback, to be called when the write is complete.

state

A user-provided object that distinguishes this particular asynchronous write request from other requests.

Return Value:

An IAsyncResult that represents the asynchronous write, which could still be pending.

Exceptions

Exception Type	Condition
IOException	Attempted an asynchronous write past the end of the file, or a disk error occurs.
ArgumentException	One or more or the arguments is invalid.
ObjectDisposedException	Methods were called after the stream was closed.
NotSupportedException	The current Stream implementation does not support the write operation.

Pass the IAsyncResult returned by the current method to Stream.EndWrite to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called BeginWrite or in a callback passed to BeginWrite. If an error occurs during an asynchronous write, an exception will not be thrown until EndWrite is called with the IAsyncResult returned by this method.

If a stream is writable, writing at the end of the stream expands the stream.

The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain.

Use the Stream.CanWrite property to determine whether the current instance supports writing.

If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from BeginWrite. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the threadpool thread and become visible upon a call to EndWrite. Exceptions thrown by the threadpool thread will not be visible when calling EndWrite.

Return to top

Summary

Closes the stream for reading and writing.

C# Syntax:

public override void Close();

This method overrides Stream.Close.

The buffer is still available on a MemoryStream once the stream has been closed.

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

Attempting to manipulate a stream after it has been closed might throw an ObjectDisposedException.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.CreateObjRef

Summary

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

C# Syntax:

public virtual ObjRef CreateObjRef(    Type requestedType );

requestedType

The Type of the object that the new ObjRef will reference.

Return Value:

Information required to generate a proxy.

Exceptions

Exception Type	Condition
RemotingException	This instance is not a valid remoting object.

Return to top

Inherited
See base class member description: System.IO.Stream.CreateWaitHandle

Summary

Allocates a WaitHandle object.

C# Syntax:

protected virtual WaitHandle CreateWaitHandle();

Return Value:

A reference to the allocated WaitHandle.

When called for the first time, the current method creates a WaitHandle object and returns it. On subsequent calls, the CreateWaitHandle returns a reference to the same wait handle.

Use this method if you implement the asynchronous methods and require a way of blocking in Stream.EndRead or Stream.EndWrite until the asynchronous operation is complete.

Return to top

Inherited
See base class member description: System.IO.Stream.EndRead

Summary

Waits for the pending asynchronous read to complete.

C# Syntax:

public virtual int EndRead(    IAsyncResult asyncResult );

asyncResult

The reference to the pending asynchronous request to finish.

Return Value:

The number of bytes read from the stream, between zero (0) and the number of bytes you requested. Streams only return zero (0) at the end of the stream, otherwise, they should block until at least one byte is available.

Exceptions

Exception Type	Condition
ArgumentNullException	asyncResult is null.
ArgumentException	asyncResult did not originate from a Stream.BeginRead method on the current stream.

Call EndRead to determine how many bytes were read from the stream.

EndRead can be called once on every IAsyncResult from Stream.BeginRead.

This method blocks until the I/O operation has completed.

Return to top

Inherited
See base class member description: System.IO.Stream.EndWrite

Summary

Ends an asynchronous write operation.

C# Syntax:

public virtual void EndWrite(    IAsyncResult asyncResult );

asyncResult

A reference to the outstanding asynchronous I/O request.

Exceptions

Exception Type	Condition
ArgumentNullException	asyncResult is null.
ArgumentException	asyncResult did not originate from a Stream.BeginWrite method on the current stream.

EndWrite must be called exactly once on every IAsyncResult from Stream.BeginWrite.

This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the threadpool thread and become visible upon a call to EndWrite. Exceptions thrown by the threadpool thread will not be visible when calling EndWrite.

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:

~MemoryStream();

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

Return to top

Summary

Overrides Stream.Flush so that no action is performed.

C# Syntax:

public override void Flush();

This method overrides Stream.Flush.

Since any data written to a MemoryStream is written into RAM, this method is redundant.

Return to top

Summary

Returns the array of unsigned bytes from which this stream was created.

C# Syntax:

public virtual byte[] GetBuffer();

Return Value:

The byte array from which this stream was created, or the underlying array if a byte array was not provided to the MemoryStream constructor during construction of the current instance.

Exceptions

Exception Type	Condition
UnauthorizedAccessException	The MemoryStream instance was not created with publicallyVisible set to true in its constructor.

To create a System.IO.MemoryStream instance with a publicly visible buffer use the default constructor, or (System.Byte [], System.Int32, System.Int32, System.Boolean, System.Boolean) or (System.Int32)constructor. If the current stream is resizable, two calls to this method do not return the same array if the underlying byte array is resized between calls. For additional information, see MemoryStream.Capacity.

Note This method works when the MemoryStream is closed.

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.MarshalByRefObject.GetLifetimeService

Summary

Retrieves the current lifetime service object that controls the lifetime policy for this instance.

C# Syntax:

public object GetLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance.

For more information about lifetime services, see the LifetimeServices class.

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.MarshalByRefObject.InitializeLifetimeService

Summary

Obtains a lifetime service object to control the lifetime policy for this instance.

C# Syntax:

public virtual object InitializeLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the LifetimeServices.LeaseManagerPollTime property.

For more information about lifetime services, see the LifetimeServices class.

The following code example demonstrates creating a lease.

 public class MyClass : MarshalByRefObject
 {
   public override Object InitializeLifetimeService()
   {
     ILease lease = (ILease)base.InitializeLifetimeService();
     if (lease.CurrentState == LeaseState.Initial)
     {
          lease.InitialLeaseTime = TimeSpan.FromMinutes(1);
          lease.SponsorshipTimeout = TimeSpan.FromMinutes(2);
           lease.RenewOnCallTime = TimeSpan.FromSeconds(2);
     }
       return lease;
   }
 }

    

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

Reads a block of bytes from the current stream and writes the data to buffer.

C# Syntax:

public override int Read(    in byte[] buffer,    int offset,    int count );

buffer

When this method returns, contains the specified byte array with the values between offset and(offset + count - 1) replaced by the characters read from the current stream.

offset

The byte offset in buffer at which to begin writing.

count

The maximum number of bytes to read.

Return Value:

The total number of bytes read into the buffer. This may be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached before any bytes are read.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
ArgumentOutOfRangeException	offset or count is negative.
ArgumentException	offset subtracted from the buffer length is less than count.
ObjectDisposedException	The current stream instance is closed.

This method overrides Stream.Read.

The offset parameter gives the offset of the first byte in buffer to which data from the current stream is written. The count parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached.

If the read operation is successful, the current position within the stream advances by the number of bytes read. If an exception occurs, the current position within the stream remains unchanged.

The Read method will return zero only if the end of the stream is reached. In all other cases, Read always reads at least one byte from the stream before returning. By definition, if no data is available from the stream upon a call to Read, the Read method returns zero (the end of the stream is reached automatically). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

Use BinaryReader for reading primitive data types.

If the byte array specified in the buffer parameter is the underlying buffer returned by the MemoryStream.GetBuffer method, the array contents are overwritten, and no exception is thrown.

Return to top

Summary

Reads a byte from the current stream.

C# Syntax:

public override int ReadByte();

Return Value:

The byte cast to a Int32, or -1 if the end of the stream has been reached.

Exceptions

Exception Type	Condition
ObjectDisposedException	The current stream instance is closed.

This method overrides Stream.ReadByte.

If the read operation is successful, the current position within the stream is advanced by one byte. If an exception occurs, the current position within the stream is unchanged.

Notes to implementors: The default implementation on Stream creates a new single-byte array and then calls Stream.Read. While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call.ReplaceThisText

Return to top

Summary

Sets the position within the current stream to the specified value.

C# Syntax:

public override long Seek(long offset, Seek(    long offset,    SeekOrigin loc );

offset

The new position within the stream. This is relative to the loc parameter, and may be positive or negative.

loc

A value of type SeekOrigin, which acts as the seek reference point.

Return Value:

The new position within the stream, calculated by combining the initial reference point and the offset.

Exceptions

Exception Type	Condition
IOException	Seeking is attempted before the beginning.
ArgumentOutOfRangeException	offset is greater than the maximum length of the MemoryStream.
ArgumentException	There is an invalid SeekOrigin.
ObjectDisposedException	The current stream instance is closed.

This method overrides Stream.Seek.

Seeking to any location beyond the length of the stream is supported.

Return to top

Summary

Sets the length of the current stream to the specified value.

C# Syntax:

public override void SetLength(    long value );

value

The value at which to set the length.

Exceptions

Exception Type	Condition
NotSupportedException	The current stream is not resizable and value is larger than the current capacity. -or- The current stream does not support writing.
ArgumentOutOfRangeException	value is negative or is greater than the maximum length of the MemoryStream, where the maximum length is( Int32.MaxValue - origin), and origin is the index into the underlying buffer at which the stream starts.

This method overrides Stream.SetLength.

If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the MemoryStream.ReadByte method returns -1, the MemoryStream.Read method reads zero bytes into the provided byte array, and MemoryStream.Write and MemoryStream.WriteByte methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros.

Note A MemoryStream instance must support writing for this method to work. Use the MemoryStream.CanWrite property to determine whether the current instance supports writing. For additional information, see Stream.CanWrite.

Return to top

Summary

Writes the entire stream contents to a byte array, regardless of the MemoryStream.Position property.

C# Syntax:

public virtual byte[] ToArray();

Return Value:

A new byte array.

This method returns a copy of the contents of the MemoryStream as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned(see (Byte [], Int32, Int32)for details).

Note This method works when the MemoryStream is closed.

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 block of bytes to the current stream using data read from buffer.

C# Syntax:

public override void Write(    byte[] buffer,    int offset,    int count );

buffer

The buffer to write data to.

offset

The byte offset in buffer at which to begin writing.

count

The maximum number of bytes to write.

Return Value:

The number of bytes written.

Exceptions

Exception Type	Condition
ArgumentNullException	buffer is null.
NotSupportedException	The stream does not support writing. For additional information see Stream.CanWrite. -or- The current position is closer than count bytes to the end of the stream, and the capacity cannot be modified.
ArgumentException	offset subtracted from the buffer length is less than count.
ArgumentOutOfRangeException	offset or count are negative.
IOException	An I/O error occurs.
ObjectDisposedException	The current stream instance is closed.

This method overrides Stream.Write.

The offset parameter gives the offset of the first byte in buffer to write from, and the count parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged.

Except for a MemoryStream constructed with a byte[] parameter, write operations at the end of a MemoryStream expand the MemoryStream.

Return to top

Summary

Writes a byte to the current stream at the current position.

C# Syntax:

public override void WriteByte(    byte value );

value

The byte to write.

Exceptions

Exception Type	Condition
NotSupportedException	The stream does not support writing. For additional information see Stream.CanWrite. -or- The current position is closer than count bytes to the end of the stream, and the capacity cannot be modified.
ObjectDisposedException	The current stream is closed.

This method overrides Stream.WriteByte.

Except for a MemoryStream constructed with a byte[] parameter, write operations at the end of a MemoryStream expand the MemoryStream.

Notes to implementors: The default implementation on Stream creates a new single-byte array and then calls Stream.Write. While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call.

Return to top

Summary

Writes the entire contents of this memory stream to another stream.

C# Syntax:

public virtual void WriteTo(    Stream stream );

stream

The stream to write this memory stream to.

Exceptions

Exception Type	Condition
ArgumentNullException	stream is null.
ObjectDisposedException	The current or target stream is closed.

When the current stream is open, this method is equivalent to calling Stream.Write on the underlying buffer of this stream.

Return to top

Top of page