# FileSource

 Documentation #include

A FileSource allows you to read data from a file using a BufferedTransformation. You can pass an existing istream and the library will read from it. Or you can have the library open anistream for you.

The companion sink object is a FileSink.

The FileSource takes a pointer to a BufferedTransformation. Because a pointer is taken, the FileSource owns the attached transformation, and therefore will destroy it. See ownership for more details.

A FileSource will pump data in blocks or chunks of 4096 bytes. An example of pumping manually is shown below. It allows you to update a progress bar of yield the processor, if needed.

Sources, filters and sinks are discussed at Pipelining. The pipeline article explains the design and shows you how to use them.

## Constructor

FileSource (BufferedTransformation *attachment=NULL)
FileSource (std::istream &in,
bool pumpAll,
BufferedTransformation *attachment=NULL)
FileSource (const char *filename,
bool pumpAll,
BufferedTransformation *attachment=NULL,
bool binary=true)

attachment is a BufferedTransformation, such as another filter or sink. If attachment is NULL, then the Base64Encoder object will internally accumulate the output byte stream.

in is an existing standard istream.

filename is the name of a file. The FileSource will open the file as an istream.

pumpAll specifies whether all the data should be red and processed.

binary is passed to the underlying ostream.

## Examples

The following example demonstrates reading a file using a FileSource, and placing the contents of the file in a string. This is known as pipelining.

string str;
FileSource file(filename, true, new StringSink(str));

cout << str << endl;

The second paramter true indicates the FileSource should pump all the data in the source. That is, it should read the entire file and pump it to its attached transformation.

A slightly more complicated example of pipelining is below. Before the FileSource is placed in the string, it is HexEncoded.

string str;
FileSource file(filename, true, new HexEncoder(new StringSink(str)));

cout << strs << endl;

From above, note that the HexEncoder and StringSink created with new do not require explicit destruction. The FileSource will call delete on the HexEncoder, which in turns calls delete on the StringSink when it (the FileSource) is destroyed.

The following manually pumps the file in chunks of 16 bytes. It allows you to update a progress bar of yield the processor, if needed. Notice pumpAll (the second parameter) is set to false.

string filename = ...;
string str;

FileSource file(filename, false, new HexEncoder(new StringSink(str)));
while(!file.SourceExhausted())
{
file.Pump(16);
}

You can also skip bytes, if needed. The example below skips the first 24 bytes of a file, and then pumps all of the remaining bytes:

string filename = ...;
string str;

FileSource file(filename, false, new HexEncoder(new StringSink(str)));
file.Skip(24);
file.PumpAll();

The examples about use a StringSink but any Sink will do. For example below is an example of a FileSink:

FileSource file(filename1, true, new HexEncoder(new FileSink(filename2)));