tango.io.protocol.model.IReader

License:
BSD style: see license.txt

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

author:
Kris Ivan Senji (the "alias get" idea)

class IReader ;

IReader interface. Each reader operates upon an IBuffer, which is provided at construction time. Readers are simple converters of data, and have reasonably rigid rules regarding data format. For example, each request for data expects the content to be available; an exception is thrown where this is not the case. If the data is arranged in a more relaxed fashion, consider using IBuffer directly instead.

All readers support the full set of native data types, plus a full selection of array types. The latter can be configured to produce either a copy (.dup) of the buffer content, or a slice. See classes HeapCopy, BufferSlice and HeapSlice for more on this topic. Applications can disable memory management by configuring a Reader with one of the binary oriented protocols, and ensuring the optional protocol 'prefix' is disabled.

Readers support Java-esque get() notation. However, the Tango style is to place IO elements within their own parenthesis, like

so:

        int count;
        char[] verse;

        read (verse) (count);

Note that each element read is distict; this style is affectionately known as "whisper". The code below illustrates basic operation upon a memory buffer:

        auto buf = new Buffer (256);

        // map same buffer into both reader and writer
        auto read = new Reader (buf);
        auto write = new Writer (buf);

        int i = 10;
        long j = 20;
        double d = 3.14159;
        char[] c = "fred";

        // write data using whisper syntax
        write (c) (i) (j) (d);

        // read them back again
        read (c) (i) (j) (d);


        // same thing again, but using put() syntax instead
        write.put(c).put(i).put(j).put(d);
        read.get(c).get(i).get(j).get(d);

Note that certain protocols, such as the basic binary implementation, expect to retrieve the number of array elements from the source. For

example:
when reading an array from a file, the number of elements is read from the file also, and the configurable memory-manager is invoked to provide the array space. If content is not arranged in such a manner you may read array content directly either by creating a Reader with a protocol configured to sidestep array-prefixing, or by accessing buffer content directly (via the methods exposed there) e.g.

        void[10] data;

        reader.buffer.fill (data);

Readers may also be used with any class implementing the IReadable interface, along with any struct implementing an equivalent method

abstract IReader get (ref bool x); abstract IReader get (ref byte x); abstract IReader get (ref ubyte x); abstract IReader get (ref short x); abstract IReader get (ref ushort x); abstract IReader get (ref int x); abstract IReader get (ref uint x); abstract IReader get (ref long x); abstract IReader get (ref ulong x); abstract IReader get (ref float x); abstract IReader get (ref double x); abstract IReader get (ref real x); abstract IReader get (ref char x); abstract IReader get (ref wchar x); abstract IReader get (ref dchar x); abstract IReader get (ref bool[] x); abstract IReader get (ref byte[] x); abstract IReader get (ref short[] x); abstract IReader get (ref int[] x); abstract IReader get (ref long[] x); abstract IReader get (ref ubyte[] x); abstract IReader get (ref ushort[] x); abstract IReader get (ref uint[] x); abstract IReader get (ref ulong[] x); abstract IReader get (ref float[] x); abstract IReader get (ref double[] x); abstract IReader get (ref real[] x); abstract IReader get (ref char[] x); abstract IReader get (ref wchar[] x); abstract IReader get (ref dchar[] x);: These are the basic reader methods
abstract IReader get (IReadable);: This is the mechanism used for binding arbitrary classes to the IO system. If a class implements IReadable, it can be used as a target for IReader get () operations. That is, implementing IReadable is intended to transform any class into an IReader adaptor for the content held therein.
abstract IBuffer buffer ();: Return the buffer associated with this reader
abstract IAllocator allocator ();: Get the allocator to use for array management. Arrays are generally allocated by the IReader, via configured managers. A number of Allocator classes are available to manage memory when reading array content. Alternatively, the application may obtain responsibility for allocation by selecting one of the NativeProtocol deriviatives and setting 'prefix' to be false. The latter disables internal array management.

Gaining access to the allocator can expose some additional controls. For example, some allocators benefit from a reset operation after each data 'record' has been processed.

By default, an IReader will allocate each array from the heap. You can change that by constructing the Reader with an Allocator of choice. For instance, there is a BufferSlice which will slice an array directly from the buffer where possible. Also available is the record- oriented HeaoSlice, which slices memory from within a pre-allocated heap area, and should be reset by the client code after each record has been read (to avoid unnecessary growth).

See module tango.io.protocol.Allocator for more information

interface IReadable ;

Any class implementing IReadable becomes part of the Reader framework

anchorFromTitle('tango.io.protocol.model.IReader', 'source/', 'html');