Stream Writing

A streaming operation consists of creating a stream. Once the stream is ready, you can write data to it. The writing operation can be performed using a class named  TTextWriter. In reality, TTextWriter is an abstract class, which means you cannot use it for a variable. Instead, it gives access to other classes used for file streaming. One of the classes used to stream is named TStreamWriter.

The TStreamWriter class can be used to write values of primitive data types (char, int, float, double, etc). To use a TStreamWriter value, you can first declare its variable using one of its five constructors. One of the conostructors uses the following syntax:

Classes::TStreamWriter * __fastcall TStreamWriter(System::UnicodeString Filename,
                                                  bool Append);

This constructor takes two arguments. The first argument is the name of the file you will write (a) value(s) to. The second argument specifies whether you want to work on the file from scratch and ignore the values in it, if any; or you want to add the new value(s) at the end of the existing ones, if any. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSaveClick(TObject *Sender)
{
	TTextWriter * twSave = new TStreamWriter("Example.txt", False);
}
//---------------------------------------------------------------------------

After declaring the variable, you can write values to it. To support this operation, the TStreamWriter class is equipped with a method named Write and another method named WriteLine. If you use the Write() method, a value is written to the file and, if you decide another that value, that one is added subsequently. The WriteLine() method writes a value and creates a new line.

After using a TStreamWriter object, you should close it to free the resources it was using. To support this, the TTextWriter is equipped with a method named Close. Its syntax is:

virtual void __fastcall Close(void);

Here is an example of using a TStreamWriter object:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSaveClick(TObject *Sender)
{
	String Filename = L"Employee1.spr";
	TTextWriter * twSave = new TStreamWriter(Filename, False);

	twSave->WriteLine(edtFirstName->Text);
	twSave->WriteLine(edtLastName->Text);
	twSave->WriteLine(edtDateOfBirth->Text);
	twSave->WriteLine(edtGender->Text);

	edtFirstName->Text = L"";
	edtLastName->Text = L"";
	edtDateOfBirth->Text = L"";
	edtGender->Text = L"";

	twSave->Close();
}
//--------------------------------------------------------------------------- this,

Another constructor of the TStreamWriter class uses the following syntax:

Classes::TStreamWriter * __fastcall TStreamWriter(Classes::TStream * Stream);

This constructor takes one argument that is of type TStream. That is, it must be a value of the type of the descendants of the TStream class. If you use this constructor, the object passed as argument should hold all the necessary information of a stream, such as a file name. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnSaveClick(TObject *Sender)
{
	TFileStream * fsIceCreamer = new TFileStream("Example.txt", fmOpenRead);
	TTextWriter * twSave = new TStreamWriter(fsIceCreamer);
}
//---------------------------------------------------------------------------

After declaring the variable, you can use the TStream-based object to write values.

Another constructor of the TStreamWriter class uses the following syntax:

Classes::TStreamWriter * __fastcall TStreamWriter(System::UnicodeString Filename,
		                                  bool Append,
		                                  Sysutils::TEncoding * Encoding,
		                                  int BufferSize);

This constructor takes four arguments.  We have already seen the first and the second arguments. The third argument allows you to specify the type of text formatting scheme you want to use. This detail is handled by a class named TEncoding, which is defined in the Sysutils namespace.

As opposed to writing to a stream, you may want to read existing data from it. To support this operation, you can use the TStreamReader class. The TStreamReader class is derived from TTextReader, which is an abstract class. The TStream class is equipped with various constructor. One of them uses the followinig syntax:

Classes::TStreamReader * __fastcall TStreamReader(System::UnicodeString Filename);

This constructor takes one argument as the name of the file to be read from. To actually read the values from the file, the TStreamReader class is equipped with a method named Read that continuously reads value on a line. If the values were added each on its own line, to use them, you can use use the ReadLine() method of the TTextReader class. The syntax of the TTextReader::ReadLine() method is:

virtual System::UnicodeString __fastcall ReadLine(void);

After using a TStreamReader object, call its Close() method to free the resources it was using. Here is an example of calling this method:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnOpenClick(TObject *Sender)
{
	String Filename = L"Employee1.spr";
	TTextReader * srOpen = new TStreamReader(Filename);

	edtFirstName->Text = srOpen->ReadLine();
	edtLastName->Text = srOpen->ReadLine();
	edtDateOfBirth->Text = srOpen->ReadLine();
	edtGender->Text = srOpen->ReadLine();

	srOpen->Close();
}
//---------------------------------------------------------------------------

The TStreamReader class has another constructor that uses the following syntax:

Classes::TStreamReader * __fastcall TStreamReader(Classes::TStream * Stream);

This constructor takes as argument a TStream value, which could be a TFileStream object. After declaring a TFileStream variable using this constructor, you can read data from it.