Appendix R
Streams
The .NET Framework provides several classes that treat data as a stream—an ordered series of bytes. These classes are not difficult to use, but they are similar enough to be confusing. This appendix summarizes the stream classes and describes their properties and their methods. See Chapter 18, “Streams,” for more information on streams.
Stream Class Summary
The following table lists the .NET Framework stream classes.
| Class | Purpose |
BinaryReader, BinaryWriter | Read and write data from an underlying stream using routines that manage specific data types (such as ReadDouble and ReadUInt16). |
BufferedStream | Adds buffering to another stream type. This sometimes improves performance on relatively slow underlying devices. |
CryptoStream | Applies a cryptographic transformation to its data. |
FileStream | Represents a file as a stream. Usually, you can use a helper class such as BinaryReader or TextWriter to make working with a FileStream easier. |
MemoryStream | Lets you read and write stream data in memory. This is useful when you need a stream but don’t want to read or write a file. |
NetworkStream | Sends and receives data across a network connection. |
Stream | A generic stream class. This is an abstract class, so you cannot create one directly. Instead, you must instantiate one of its subclasses. |
StreamReader, StreamWriter | These classes inherit from TextReader and TextWriter. They provide methods for reading and writing text into an underlying stream, usually a FileStream. |
StringReader, StringWriter | These classes inherit from TextReader and TextWriter. They provide methods for reading and writing text into an underlying string. |
TextReader, TextWriter | These abstract classes define methods that make working with text on an underlying stream easier. |
The following sections describe stream classes in greater detail.
Stream
The following table describes the Stream class’s most useful properties.
| Property | Purpose |
CanRead | Returns true if the stream supports reading. |
CanSeek | Returns true if the stream supports seeking to a particular position in the stream. |
CanTimeout | Returns true if the stream supports timeouts. |
CanWrite | Returns true if the stream supports writing. |
Length | Returns the number of bytes in the stream. |
Position | Returns the stream’s current position in its bytes. For a stream that supports seeking, the program can set this value to move to a particular position. |
ReadTimeout | Determines the stream’s read timeout in milliseconds. |
WriteTimeout | Determines the stream’s write timeout in milliseconds. |
The following table describes the Stream class’s most useful methods.
| Method | Purpose |
BeginRead | Begins an asynchronous read. |
BeginWrite | Begins an asynchronous write. |
Close | Closes the stream and releases any resources it uses (such as file handles). |
EndRead | Waits for an asynchronous read to finish. |
EndWrite | Ends an asynchronous write. |
Flush | Flushes data from the stream’s buffers into the underlying storage medium (device, file, and so on). |
Read | Reads bytes from the stream and advances its position by that number of bytes. |
ReadByte | Reads a byte from the stream and advances its position by 1 byte. |
Seek | If the stream supports seeking, sets the stream’s position. |
SetLength | Sets the stream’s length. If the stream is currently longer than the new length, it is truncated. If the stream is shorter than the new length, it is enlarged. The stream must support both writing and seeking for this method to work. |
Write | Writes bytes into the stream and advances the current position by this number of bytes. |
WriteByte | Writes 1 byte into the stream and advances the current position by 1 byte. |
The FileStream and MemoryStream classes add only a few methods to those defined by the Stream class. The most important of those are new constructors specific to the type of stream. For example, the FileStream class provides constructors for opening files in various modes (append, new, and so forth).
BinaryReader and BinaryWriter
These are stream helper classes that make it easier to read and write data in specific formats onto an underlying stream. The following table describes the BinaryReader class’s most useful methods.
| Method | Purpose |
Close | Closes the BinaryReader and its underlying stream. |
PeekChar | Reads the reader’s next character but does not advance the reader’s position, so other methods can still read the character later. |
Read | Reads characters from the stream and advances the reader’s position. |
ReadBoolean | Reads a bool from the stream and advances the reader’s position by 1 byte. |
ReadByte | Reads a byte from the stream and advances the reader’s position by 1 byte. |
ReadBytes | Reads a number of bytes from the stream into a byte array and advances the reader’s position by that number of bytes. |
ReadChar | Reads a character from the stream and advances the reader’s position according to the stream’s encoding and the character. |
ReadChars | Reads a number of characters from the stream, returns the results in a char array, and advances the reader’s position according to the stream’s encoding and the number of characters. |
ReadDecimal | Reads a decimal value from the stream and advances the reader’s position by 16 bytes. |
ReadDouble | Reads a 64-bit double-precision floating-point value (double) from the stream and advances the reader’s position by 8 bytes. |
ReadInt16 | Reads a 16-bit signed integer (short) from the stream and advances the reader’s position by 2 bytes. |
ReadInt32 | Reads a 32-bit signed integer (int) from the stream and advances the reader’s position by 4 bytes. |
ReadInt64 | Reads a 64-bit signed integer (long) from the stream and advances the reader’s position by 8 bytes. |
ReadSByte | Reads a signed byte (sbyte) from the stream and advances the reader’s position by 1 byte. |
ReadSingle | Reads a 32-bit single-precision floating-point value (float) from the stream and advances the reader’s position by 4 bytes. |
ReadString | Reads a string from the stream and advances the reader’s position past it. The string begins with its length. |
ReadUInt16 | Reads a 16-bit unsigned integer (ushort) from the stream and advances the reader’s position by 2 bytes. |
ReadUInt32 | Reads a 32-bit unsigned integer (uint) from the stream and advances the reader’s position by 4 bytes. |
ReadUInt64 | Reads a 64-bit unsigned integer (ulong) from the stream and advances the reader’s position by 8 bytes. |
The following table describes the BinaryWriter class’s most useful methods.
| Method | Description |
Close | Closes the BinaryWriter and its underlying stream. |
Flush | Writes any buffered data into the underlying stream. |
Seek | Sets the position within the stream. |
Write | Writes a value into the stream. This method has many overloaded versions that write characters, arrays of characters, integers, strings, unsigned 64-bit integers, and so on. |
TextReader and TextWriter
These are stream helper classes that make it easier to read and write text data onto an underlying stream. The following table describes the TextReader class’s most useful methods.
| Method | Purpose |
Close | Closes the reader and releases any resources that it is using. |
Peek | Reads the next character from the text without changing the reader’s state so that other methods can read the character later. |
Read | Reads data from the input. Overloaded versions of this method read a single character, or an array of characters up to a specified length. |
ReadBlock | Reads data from the input into an array of characters. |
ReadLine | Reads a line of characters from the input and returns the data in a string. |
ReadToEnd | Reads any remaining characters in the input and returns them in a string. |
The following table describes the TextWriter class’s most useful properties.
| Property | Purpose |
Encoding | Specifies the data’s encoding (ASCII, UTF-8, Unicode, and so forth). |
FormatProvider | Returns an object that controls formatting. |
NewLine | Gets or sets the stream’s new-line sequence. |
The following table describes the TextWriter class’s most useful methods.
| Method | Purpose |
Close | Closes the writer and releases any resources it is using. |
Flush | Writes any buffered data into the underlying output. |
Write | Writes a value into the output. This method has many overloaded versions that write characters, arrays of characters, integers, strings, unsigned 64-bit integers, and so forth. |
WriteLine | Writes data into the output followed by the new-line sequence. |
StringReader and StringWriter
The StringReader and StringWriter classes let a program read and write text in a string. They implement the features defined by their parent classes TextReader and TextWriter. See the section “TextReader and TextWriter” earlier in this appendix for a list of those features.
StreamReader and StreamWriter
The StreamReader and StreamWriter classes let a program read and write data in an underlying stream, often a FileStream. They implement the features defined by their parent classes TextReader and TextWriter. See the section “TextReader and TextWriter” earlier in this appendix for a list of the features.
Text File Stream Methods
The System.IO.File class provides several handy methods for working with text files. The following table summarizes these methods.
| Method | Purpose |
AppendText | Creates a text file or opens it for appending if it already exists. Returns a StreamWriter for writing into the file. |
CreateText | Creates a text file, overwriting it if it already exists. Returns a StreamWriter for writing into the file. |
Exists | Returns true if a file exists. It is good practice (and much faster) to only try to open the file if Exists returns true, rather than just try to open the file and catch errors with a try-catch-finally block. |
OpenText | Opens an existing text file and returns a StreamReader to read from it. This method throws a FileNotFoundException if the file doesn’t exist. |