tango.io.Buffer

License:
BSD style: see license.txt

Version:
Mar 2004: Initial release Dec 2006: Outback release

Authors:
Kris

protected void* memcpy (void* dst, void* src, uint);

class Buffer : tango.io.model.IBuffer.IBuffer;

Buffer is central concept in Tango I/O. Each buffer acts as a queue (line) where items are removed from the front and new items are added to the back. Buffers are modeled by tango.io.model.IBuffer, and a concrete implementation is provided by this class.

Buffer can be read from and written to directly, though various data-converters and filters are often leveraged to apply structure to what might otherwise be simple raw data.

Buffers may also be tokenized by applying an Iterator. This can be handy when one is dealing with text input, and/or the content suits a more fluid format than most typical converters support. Iterator tokens are mapped directly onto buffer content (sliced), making them quite efficient in practice. Like other types of buffer client, multiple iterators can be mapped onto one common buffer and access will be serialized.

Buffers are sometimes memory-only, in which case there is nothing left to do when a client has consumed all the content. Other buffers are themselves bound to an external device called a conduit. When this is the case, a consumer will eventually cause a buffer to reload via its associated conduit and previous buffer content will be lost.

A similar approach is applied to clients which populate a buffer, whereby the content of a full buffer will be flushed to a bound conduit before continuing. Another variation is that of a memory-mapped buffer, whereby the buffer content is mapped directly to virtual memory exposed via the OS. This can be used to address large files as an array of content.

Direct buffer manipulation typically involves appending, as in the following example:

        // create a small buffer
        auto buf = new Buffer (256);

        auto foo = "to write some D";

        // append some text directly to it
        buf.append ("now is the time for all good men ").append(foo);

Alternatively, one might use a formatter to append the buffer:

        auto output = new FormatOutput (new Buffer(256));
        output.format ("now is the time for {} good men {}", 3, foo);

A slice() method will return all valid content within a buffer. GrowBuffer can be used instead, where one wishes to append beyond a specified limit.

A common usage of a buffer is in conjunction with a conduit, such as FileConduit. Each conduit exposes a preferred-size for its associated buffers, utilized during buffer construction:

        auto file = new FileConduit ("file.name");
        auto buf = new Buffer (file);

However, this is typically hidden by higher level constructors such as those exposed via the stream wrappers. For example:

        auto input = new DataInput (new FileInput("file.name"));

There is indeed a buffer between the resultant stream and the file source, but explicit buffer construction is unecessary in common cases.

An Iterator is constructed in a similar manner, where you provide it an input stream to operate upon. There's a variety of iterators available in the tango.text.stream package, and they are templated for each of utf8, utf16, and utf32. This example uses a line iterator to sweep a text file:

        auto lines = new LineInput (new FileInput("file.name"));
        foreach (line; lines)
                 Cout(line).newline;

Buffers are useful for many purposes within Tango, but there are times when it may be more appropriate to sidestep them. For such cases, all conduit derivatives (such as FileConduit) support direct array-based IO via a pair of read() and write() methods.

this(IConduit conduit);