17.2. String Stream

The string stream is for reading and writing a string. There are 4 kinds of the string stream corresponding to the type of the string and the read or write type as in the table below:

Table 17.4. String Stream

Type of the String	For Reading	For Writing
AChar Type	`SFXAnsiStringStreamReader`	`SFXAnsiStringStreamWriter`
WChar Type	`SFXWideStringStreamReader`	`SFXWideStringStreamWriter`

17.2.1. Reading and Writing the String Class Using the String Stream

In the string stream, by specifying the SFXAnsiString / SFXWideString instance in the argument of the ReadSFXAnsiString / ReadSFXWideString function or the WriteSFXAnsiString / WriteSFXWideString function or in the operand of the inserter(<< operator) or extractor(>> operator), data of the string class can be read from or written into the storage.

17.2.1.1. Reading from the String Stream into the String Class

In case of reading data of the string class from the string stream, the data until the next '\0' or the tail will be read into the variable of the SFXAnsiString / SFXWideString type.

In this case, there is no need to set the size of the variable in advance. The memory area of the variable will be allocated automatically depending on the length of the strings to be read.

	In Case of Reading from the String Stream into the Buffer Class
	In case of reading data from the string stream into the variable of the `SFXBuffer` class, it is necessary to set the size of the variable in advance. The memory area of the variable will not be allocated automatically.

	'\0' Separator
	The '\0', separator to separate the strings in the stream is 1 byte in case of the AChar string(`SFXAnsiString`), or 2 bytes in case of the WChar string(`SFXWideString`).

	In Case of Reading the String from the Binary Stream
In the binary stream, if the next '\0' is not found until the tail, an error will occur and nothing will be stored into the variable(the content of the variable will be the same as before reading). At this time, the ReadSFXAnsiString / ReadSFXWideString function of the binary stream will return SFERR_INVALID_STATE, but the extractor(>> operator) will return no error.

In Case of Reading the String from the Binary Stream

In the binary stream, if the next '\0' is not found until the tail, an error will occur and nothing will be stored into the variable(the content of the variable will be the same as before reading).

At this time, the ReadSFXAnsiString / ReadSFXWideString function of the binary stream will return SFERR_INVALID_STATE, but the extractor(>> operator) will return no error.

Example 17.1. The string in hexadecimal to be read: "/dir/data.txt"

61 62 63 64 00 65 66 67 68 00 69 6A 6B 6C // HEX format

Example 17.2. Reading from the String Stream into the String Class

// *** in the code below, the error handling is omitted.
SFXFile file;                     // file
SFXAnsiStringStreamReader reader; // string stream for reading from the file
SFXAnsiString string;             // variable to read into

// open the file in the read-only mode
file.OpenReadOnly(SFXPath("/dir/data.txt"));

// get the string stream for reading from the file
// * the stream buffer is variable since the size argument is not specified
file.GetStreamReader(&reader);

// read data from the file into the stream buffer
// * the stream buffer will be expanded automatically depending on the size of data to be read into
//   the read operation will finish by calling the Fetch function once
reader.Fetch();

// read data from the stream buffer into the string variable
reader >> string; // get data string until '\0' is reached string = "abcd"
reader >> string; // get string up to next '\0'            string = "efgh"
reader >> string; // get until end                         string = "ijkl"
reader >> string; // get until end                         string = empty

// release the string stream for reading from the file
reader.Release();

// close the file
file.Close();

17.2.1.2. Writing from the String Class into the String Stream

If a SFXAnsiString / SFXWideString string is written into the stream by using the WriteSFXAnsiString / WriteSFXWideString function or the inserter(<< operator) of the string stream, '\0' will not be appended at the tail of the string.

	In Case of Writing the String into the Binary Stream
	In case of writing into the binary stream, '\0' will be automatically appended at the tail of the string.

To write '\0' into the string stream, write "ends" into the stream as in the sample code below.

Example 17.3. Method to write '\0'

writer << ends; // write '\0' into the stream

	'\0' Separator
	The '\0', separator to separate the strings in the stream is 1 byte in case of the AChar string(`SFXAnsiString`), or 2 bytes in case of the WChar string(`SFXWideString`).

Example 17.4. Writinging from the String Class into the String Stream

// *** in the code below, the error handling is omitted.
SFXFile file;                            // file
SFXAnsiStringStreamWriter writer;        // string stream for writing into the file
SFXAnsiString string("abcd");  // string to write

// open the file in the read-write mode
file.OpenReadWrite(SFXPath("/dir/data.txt"));

// get the string stream for writing into the file
// * the stream buffer is variable since the size argument is not specified
file.GetStreamWriter(&writer);

// write data from the string variable into the stream buffer
// * the stream buffer will be expanded automatically depending on the size of data to be written
writer << string; // write "abcd" 
writer << "efgh"; // write "efgh" 
writer << string; // write "abcd" 

// write data from the stream buffer into the file
// * the write operation will finish by calling the Flush function once
writer.Flush();

// release the string stream for writing into the file
writer.Release();

// close the file
file.Close();

Example 17.5. The written string in hexadecimal: "/dir/data.txt"

61 62 63 64 65 66 67 68 61 62 63 64  // HEX format

17.2.2. Reading and Writing the Buffer Class Using the String Stream

By specifying the SFXBuffer instance in the argument of the Read or Write function, data of the SFXBuffer type can be read from or written into the storage.

	Caution
	In the string stream, the `SFXBuffer` instance cannot be specified as the operand of the inserter(<< operator) or extractor(>> operator). However, in case of the binary stream, it can be specified.

17.2.2.1. Reading from the String Stream into the Buffer Class

In case of reading data from the string stream into the variable of the SFXBuffer type, it is necessary to set the size of the variable in advance. The memory region of the variable will not be allocated automatically.

	Caution
	If only data less than the specified size can be read, an error will occur.

In case of reading the string class

	In case of reading the string class
In case of reading into the variable of the `SFXAnsiString` / `SFXWideString` type, there is no need to set the size of the variable in advance. The memory region of the variable will be allocated automatically depending on the length of the string to be read.

In case of reading into the variable of the SFXAnsiString / SFXWideString type, there is no need to set the size of the variable in advance.

The memory region of the variable will be allocated automatically depending on the length of the string to be read.

Example 17.6. The string in hexadecimal to be read: "/dir/data.txt"

61 62 63 64 65 66 67 68 61 62 63  // HEX format

Example 17.7. Reading from the String Stream into the Buffer Class

// *** in the code below, the error handling is omitted.
SFXFile file;                      // file
SFXAnsiStringStreamReader reader;  // string stream for reading from the file
SFXBuffer buffer;  // buffer to read
buffer.SetSize(4); // it is necessary to set the size of data to be read in advance

// open the file in the read-only mode
file.OpenReadOnly(SFXPath("/dir/data.txt"));

// get the string stream for reading from the file
// * the stream buffer is variable since the size argument is not specified
file.GetStreamReader(&reader);

// read data from the file into the stream buffer
// * the stream buffer will be expanded automatically depending on the size of data to be read into
//   the read operation will finish by calling the Fetch function once
reader.Fetch();

// read data from the stream buffer into the buffer variable
// * extractor(>> operator) cannot be used
reader.Read(&buffer);   // get the first 4 byte. "61 62 63 64" (HEX format) will be stored into buffer.
reader.Read(&buffer);  // get the next 4 byte.  "65 66 67 68" (HEX format) will be stored into buffer.

// here, data of 3 bytes remain in the stream buffer
// since the size of buffer 4 byte, data to be read is bigger than data which remain in the stream buffer.
reader.Read(&buffer);  // after this statement, even if the stream try to be read, the content of buffer will remain to be "65 66 67 68" (HEX format).
                   // The SFERR_FAILED error will be returned.

// release the string stream for reading from the file
reader.Release();

// close the file
file.Close();

17.2.2.2. Writing from the Buffer Class into the String Stream

Example 17.8. Writing from the Buffer Class into the String Stream

// *** in the code below, the error handling is omitted.
SFXFile file;                                   // file
SFXAnsiStringStreamWriter writer;               // string stream for writing into the file
SFXBuffer buffer;                               // buffer
AChar data[] = {0x61, 0x62, 0x63, 0x64, 0x65};  // data to set to the buffer

buffer.Set(data, 5);  // set the buffer to data of 5 bytes

// open the file in the read-write mode
file.OpenReadWrite(SFXPath("/dir/data.txt"));

// get the string stream for writing into the file
// * the stream buffer is variable since the size argument is not specified
file.GetStreamWriter(&writer);

// write data from the buffer variable into the stream buffer
// * inserter(<< operator) cannot be used
writer.Write(buffer); // write the buffer of 5 bytes into the string stream
writer.Write(buffer); // write the buffer of 5 bytes into the string stream

// write data from the stream buffer into the file
// * the write operation will finish by calling the Flush function once
writer.Flush();

// release the string stream for writing into the file
writer.Release();

// close the file
file.Close();

Example 17.9. The written string in hexadecimal: "/dir/data.txt"

61 62 63 64 65 61 62 63 64 65  // HEX format