IN THIS CHAPTER

Reading and writing data files

Using the Stream classes

Using the using statement

Dealing with input/output errors

Catching fish in a stream can prove to be quite a thrill to those who engage in fishing. Anglers often boast of the difficulty of getting that one special fish out of the stream and into a basket. Fishing the “file stream” with C# isn't quite so thrilling, but it’s one of those indispensable programming skills.

File access refers to the storage and retrieval of data on the disk. This chapter covers basic text-file input/output. Reading and writing data from databases are covered in Chapter 2 of this minibook, and reading and writing information to the Internet are covered in Chapter 4.

You don’t have to type the source code for this chapter manually. In fact, using the downloadable source is a lot easier. You can find the source for this chapter in the CSAIO4D2EBK03CH03 folder of the downloadable source. See the Introduction for details on how to find these source files.

Going Where the Fish Are: The File Stream

The console application programs in this book mostly take their input from, and send their output to, the console. Programs outside this chapter have better — or at least different — things to bore you with than file manipulation. It’s important not to confuse their message with the extra baggage of involved input/output (I/O). However, console applications that don’t perform file I/O aren’t very common.

The I/O classes are defined in the System.IO namespace. The basic file I/O class is FileStream. In days past, the programmer would open a file. The open command would prepare the file and return a handle. Usually, this handle was nothing more than a number, like the one they give you when you place an order at a Burger Shop. Every time you wanted to read from or write to the file, you presented this ID.

StreamWriting for Old Walter

In the movie On Golden Pond, Henry Fonda spent his retirement years trying to catch a monster trout that he named Old Walter. You aren't out to drag in the big fish, but you should at least cast a line into the stream. This section covers writing to files. Programs generate two kinds of output:

• Binary: Some programs write blocks of data as bytes in pure binary format. This type of output is useful for storing objects in an efficient way — for example, a file of Student objects that you need to persist (keep on disk in a permanent file). See the later section “More Readers and Writers” for the BinaryReader and BinaryWriter classes.

  A sophisticated example of binary I/O is the persistence of groups of objects that refer to each other (using the HAS_A relationship). Writing an object to disk involves writing identifying information (so its type can be reconstructed when you read the object back in), and then each of its data members, some of which may be references to connected objects, each with its own identifying information and data members. Persisting objects this way is called serialization.

• Text: Most programs read and write human-readable text: you know, letters, numbers, and punctuation, like Notepad. The human-friendly StreamWriter and StreamReader classes are the most flexible ways to work with the stream classes. For some details, see the earlier section “Readers and writers.”

  Human-readable data was formerly known as American Standard Code for Information Interchange (ASCII) text or, slightly later, American National Standards Institute (ANSI) text. These two monikers refer to the standards organization that defined them. However, ANSI encoding doesn't provide the alphabets east of Austria and west of Hawaii; it can handle only Roman letters, like those used in English. It has no characters for Russian, Hebrew, Arabic, Hindi, or any other language using a non-Roman alphabet, including Asian languages such as Chinese, Japanese, and Korean. The modern, more flexible Unicode character format is “backward-compatible” — including the familiar ANSI characters at the beginning of its character set, but still provides a large number of other alphabets, including everything you need for all the languages just listed. Unicode comes in several variations, called encodings; however, Unicode Transformation Format (8-Bit) (UTF8) is the default encoding for C#. You can read more about Unicode encodings at https://unicodebook.readthedocs.io/unicode_encodings.html. Other popular encodings are: UTF7, UTF16, and UTF32, where the number after UTF specifies the number of bits used in the encoding.

Pulling Them Out of the Stream: Using StreamReader

Writing to a file is cool, but it’s sort of worthless if you can’t read the file later. The following FileRead program puts the input back into the phrase file I/O. This program reads a text file like the ones created by FileWrite or by Notepad — it's sort of FileWrite in reverse:

static void Main(string[] args)
{
// Get the name of a file to process. If the user doesn't
// provide one, exit with an error code of -1.
Console.Write("Enter the name of a text file to read: ");
String filename = Console.ReadLine();
if (filename.Length == 0)
{
Console.WriteLine("No filename provided, exiting.");
Environment.Exit(-1);
}

// Verify that the file actually exists. If not, then exit
// with a -2 error code.
if (!File.Exists(filename))
{
Console.WriteLine("The File doesn't exit!");
Console.ReadLine();
Environment.Exit(-2);
}

// Open the file for processing by creaing a FileStream and
// a StreamReader with a using statement.
using (StreamReader sr = new StreamReader(filename))
{
Console.WriteLine(" Contents of File:");

// Proces the file one line at a time.
while (!sr.EndOfStream)
{
String input = sr.ReadLine();
Console.WriteLine(input);
}
}

Console.ReadLine();
}

The first thing you should notice about this example is just how much shorter it is than the FileWrite example. That's not because FileWrite bears all the burden and FileRead is on a luxury cruise. The FileWrite example is important because it demonstrates modularization techniques that you can employ for complex file situations. The FileRead example is important because it demonstrates the latest techniques in handling less complex file-handling situations. You could easily re-code FileWrite using this style and it would perform just as well.

This example also provides you with a different view of error trapping and handling. Rather than rely on exceptions (the error has aleady happened), it relies on built-in functions to determine whether an error is about to occur. Yes, that's right: This example has precognition! It also adds the use of external error codes. You can use these error codes in a batch file to perform tasks in batches without actually having to watch them complete one by one, slowly dropping off to sleep as you do and then banging your head on the keyboard. Rather, you use the error codes to create log entries that tell you when things don’t work properly. Checking for things that could go wrong is generally faster than handling an exception and considered better programming practice.

Notice that this example also relies on a form of the using statement so that you can see it in action. Instead of creating a separate FileStream, this example relies on a special StreamReader constructor that accepts a filename as input. The FileStream is still created — you just don't have to mess with it.

During the file reading process, the while loop relies on a check of !sr.EndOfStream to determine when to stop reading data from the file. The EndOfStream property becomes true when the last bit of data is read from the file. In short, this example demonstrates a number of tricks you can use to make your code extremely short.

For an example of reading arbitrary bytes from a file — which could be either binary or text — see the LoopThroughFiles example in Book 1, Chapter 7. The program actually loops through all files in a target directory, reading each file and dumping its contents to the console, so it gets tedious if there are lots of files. Feel free to terminate it by pressing Ctrl+C or by clicking the console window's close box. See the discussion of BinaryReader in the next section.

More Readers and Writers

Earlier in this chapter, you see the StreamReader and StreamWriter classes that you'll probably use for the bulk of your I/O needs. However, .NET also makes several other reader/writer pairs available:

• BinaryReader/BinaryWriter: A pair of stream classes that contain methods for reading and writing each value type: ReadChar(), WriteChar(), ReadByte(), WriteByte(), and so on. (These classes are a little more primitive: They don't offer ReadLine()/WriteLine() methods.) The classes are useful for reading or writing an object in binary (not human-readable) format, as opposed to text. You can use an array of bytes to work with the binary data as raw bytes. For example, you may need to read or write the bytes that make up a bitmap graphics file.

  Experiment: Open a file with a .EXE extension using Notepad. You may see some readable text in the window, but most of it looks like some sort of garbage. That's binary data.

  The “Formatting the output lines” section of Chapter 7 in Book 1 includes an example, mentioned earlier, that reads binary data. The example uses a BinaryReader with a FileStream object to read chunks of bytes from a file and then writes out the data on the console in hexadecimal (base 16) notation, which is explained in that chapter. Although it wraps a FileStream in the more convenient BinaryReader, that example could just as easily have used the FileStream itself. The reads are identical. Although the BinaryReader brings nothing to the table in that example, it's used there to provide an example of this reader. The example does illustrate reading raw bytes into a buffer (an array big enough to hold the bytes read).

• StringReader/StringWriter: And now for something a little more exotic: simple reader and writer classes that are limited to reading and writing strings. They let you treat a string like a file, an alternative to accessing a string's characters in the usual ways, such as with a foreach loop

  foreach (char c in someString) { Console.Write(c); }

  or with array-style bracket notation ([ ])

  char c = someString[3];

  or with String methods like Split(), Concatenate(), and IndexOf(). With StringReader/StringWriter, you read from and write to a string much as you would to a file. This technique is useful for long strings with hundreds or thousands of characters (such as an entire text file read into a string) that you want to process in bunches, and it provides a handy way to work with a StringBuilder.

  When you create a StringReader, you initialize it with a string to read. When you create a StringWriter, you can pass a StringBuilder object to it or create it empty. Internally, the StringWriter stores a StringBuilder — either the one you passed to its constructor or a new, empty one. You can get at the internal StringBuilder's contents by calling StringWriter’s ToString() method.

  Each time you read from the string (or write to it), the “file pointer” advances to the next available character past the read or write. Thus, as with file I/O, you have the notion of a “current position.” When you read, say, 10 characters from a 1,000-character string, the position is set to the eleventh character after the read.

  The methods in these classes parallel those described earlier for the Stream-Reader and StreamWriter classes. If you can use those, you can use these.

Exploring More Streams than Lewis and Clark

File streams are not the only kinds of Stream classes available. The flood of Stream classes includes (but probably is not limited to) those in the following list. Note that unless otherwise specified, these stream classes all live in the System.IO namespace.

• FileStream: For reading and writing files on a disk.
• MemoryStream: Manages reading and writing data to a block of memory. You see this technique sometimes in unit tests, to avoid actually interacting with the (slow, possibly troublesome) file system. In this way, you can fake a file when testing code that reads and writes.

• BufferedStream: Buffering is a technique for speeding up input/output operations by reading or writing bigger chunks of data at a time. Lots of small reads or writes mean lots of slow disk access — but if you read a much bigger chunk than you need now, you can then continue to read your small chunks out of the buffer — which is far faster than reading the disk. When a BufferedStream's underlying buffer runs out of data, it reads in another big chunk — maybe even the whole file. Buffered writing is similar.

  Class FileStream automatically buffers its operations, so BufferedStream is for special cases, such as working with a NetworkStream to read and write bytes over a network. In this case, you wrap the BufferedStream around the NetworkStream, effectively “chaining” streams. When you write to the BufferedStream, it writes to the underlying NetworkStream, and so on.

  When you're wrapping one stream around another, you’re composing streams. (You can look it up in C# Language Help for more information.) The earlier sidebar, “Wrap my fish in newspaper,” discusses wrapping.

• NetworkStream: Manages reading and writing data over a network. See BufferedStream for a simplified discussion of using it. NetworkStream is in the System.Net.Sockets namespace because it uses a technology called sockets to make connections across a network.
• UnmanagedMemoryStream: Lets you read and write data in unmanaged blocks of memory. Unmanaged means, basically, “not .NET” and not managed by the .NET runtime and its garbage collector. This is advanced stuff, dealing with interaction between .NET code and code written under the Windows operating system.
• CryptoStream: Located in the System.Security.Cryptography namespace, this stream class lets you pass data to and from an encryption or decryption transformation.