StringSource

A StringSource is a source for byte arrays, C-strings and C++ strings.

StringSource

Documentation

#include <cryptopp/filters.h>

Constructors

StringSource (BufferedTransformation *attachment=NULL)

StringSource (const char *zstring,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

StringSource (const std::string &string,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

StringSource (const byte *bstring,
              size_t length,
              bool pumpAll,
              BufferedTransformation *attachment=NULL)

zstring is a NULL terminated C-string.

string is a C++ string.

bstring is a byte array.

length is the length of the byte array.

pumpAll is a boolen value indicating if the StringSource should pump all of the data immediately to its attached transformation.

attachment is a BufferedTransformation, such as another filter or sink.

Examples

The following examples demonstrate creation of a StringSource.

StringSource ss( "Hello World" );

string data;
StringSource ss( data );

The following example demonstrates writing a string to a file.

string data;
StringSource ss( data, true /*pumpAll*/, new FileSink( "test.txt" ) );

The following example performs the same operation as above, but without the variable s.

string data;
StringSource ss( data, true /*pumpAll*/, new FileSink( "test.txt" ) );

The following example uses a byte array rather than a string. Note an alternate constructor is used in this case.

const byte arr[] = {0, 2, 4, 6, 8};
StringSource ss( arr, 5, true /*pumpAll*/, new FileSink( "test.txt" ) );

A slightly more complicated example of pipelining is below. Before the string is written to the file, it is HexEncoded.

string s;
StringSource ss( s, true /*pumpAll*/, new HexEncoder( new FileSink( "test.txt" ) ) );

Sometimes the pipeline will be coded over multiple lines to aid in readability. The following is equivalent to the previous.

string s;
StringSource ss( s, true /*pumpAll*/,
    new HexEncoder(
        new FileSink( "test.txt" )
    ) // HexEncoder
); // StringSource

Note that the HexEncoder and FileSink created with new do not require explicit destruction - the StringSource will call delete on the HexEncoder, which in turns calls delete on the FileSink when it (the StringSource) is destroyed.

Missing Data

Its not uncommon to experience Missing Data in a pipeline. A source will send data through a pipeline but have nothing in the sink. This is usually due to the compiler matching the wrong function. For example:

string source = "FF 88 00", destination;
StringSink ss(source,
    new HexDecoder(
        new StringSink(destination)
    ) // HexDecoder
); // StringSink

After the above code executes, destination will likely be empty because the compiler coerces the HexDecoder (the pointer) to a bool (the pumpAll parameter), which leaves the StringSource's attached transformation NULL. The compiler will do so without warning, even with -Wall -Wextra -Wconversion. To resolve the issue, explicitly specify the pumpAll parameter:

string source = "FF 88 00", destination;
StringSink ss(source, true /*pumpAll*/,
    new HexDecoder(
        new StringSink(destination)
    ) // HexDecoder
); // StringSink

Another way data ends up missing is failing to call MessageEnd() when pumping data. For example, the following may not produce expected results:

// The 4-bit nibble will be buffered waiting for another nibble
string source = "FF 88 0", destination;

HexDecoder decoder(new StringSink(destination));
decoder.Put(source.data(), source.size());

// Do something with destination

Be sure to call MessageEnd() when data comes up missing:

string source = "FF 88 0", destination;

HexDecoder decoder(new StringSink(destination));
decoder.Put(source.data(), source.size());
decoder.MessageEnd();

// Do something with destination