Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

IReader.d

Go to the documentation of this file.
00001 /*******************************************************************************
00002 
00003         @file IReader.d
00004         
00005         Copyright (C) 2004 Kris Bell
00006         
00007         This software is provided 'as-is', without any express or implied
00008         warranty. In no event will the authors be held liable for damages
00009         of any kind arising from the use of this software.
00010         
00011         Permission is hereby granted to anyone to use this software for any 
00012         purpose, including commercial applications, and to alter it and/or 
00013         redistribute it freely, subject to the following restrictions:
00014         
00015         1. The origin of this software must not be misrepresented; you must 
00016            not claim that you wrote the original software. If you use this 
00017            software in a product, an acknowledgment within documentation of 
00018            said product would be appreciated but is not required.
00019 
00020         2. Altered source versions must be plainly marked as such, and must 
00021            not be misrepresented as being the original software.
00022 
00023         3. This notice may not be removed or altered from any distribution
00024            of the source.
00025 
00026 
00027                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
00028 
00029 
00030         @version        Initial version, March 2004      
00031         @author         Kris
00032 
00033 
00034 *******************************************************************************/
00035 
00036 module mango.io.model.IReader;
00037 
00038 public import mango.io.model.IBuffer;
00039 
00040 /*******************************************************************************
00041 
00042         Any class implementing IReadable becomes part of the Reader framework
00043         
00044 *******************************************************************************/
00045 
00046 interface IReadable
00047 {
00048         void read (IReader r);
00049 }
00050 
00051 /*******************************************************************************
00052 
00053 *******************************************************************************/
00054 
00055 interface IArrayAllocator
00056 {
00057         void reset ();
00058         bool isReadOnly (void* x);
00059         void allocate (void[]* x, BufferConverter convert);
00060 }
00061 
00062 /*******************************************************************************
00063 
00064         Use instances of IStringDecoder to convert between character 'sizes'
00065         and to unwrap the various character encodings. These may throw an
00066         exception if they don't support the requested type. For example, an
00067         exception would/should be thrown where a Unicode-based IStringDecoder 
00068         is requested to provide a char[] instead of a wchar[].
00069 
00070         An appropriate IStringDecoder should be attached to each IReader, and
00071         thus be available for subsequent use. A raw binary implementation is 
00072         attached by default (no decoding at all).
00073 
00074         Note that the 'count' argument is the number of bytes available in
00075         the 'dst' buffer. The decoders are expected to fill exactly that 
00076         amount, or throw an exception.
00077 
00078 *******************************************************************************/
00079 
00080 interface IStringDecoder
00081 {
00082         void char8  (void *dst, uint count);
00083         void char16 (void *dst, uint count);
00084         void char32 (void *dst, uint count);
00085 }
00086 
00087 /*******************************************************************************
00088 
00089         All reader instances should implement this interface.
00090 
00091 *******************************************************************************/
00092 
00093 interface IReader
00094 {
00095         /***********************************************************************
00096         
00097                 These are the basic reader methods
00098 
00099         ***********************************************************************/
00100 
00101         IReader get (inout bool x);
00102         IReader get (inout byte x);
00103         IReader get (inout ubyte x);
00104         IReader get (inout short x);
00105         IReader get (inout ushort x);
00106         IReader get (inout int x);
00107         IReader get (inout uint x);
00108         IReader get (inout long x);
00109         IReader get (inout ulong x);
00110         IReader get (inout float x);
00111         IReader get (inout double x);
00112         IReader get (inout real x);
00113 
00114         IReader get (inout char x);
00115         IReader get (inout wchar x);
00116         IReader get (inout dchar x);
00117 
00118         IReader get (inout char[] x);
00119         IReader get (inout wchar[] x);
00120         IReader get (inout dchar[] x);
00121 
00122         // these are currently disabled until a future release
00123         //IWriter get (inout bool[] x);
00124         //IWriter get (inout byte[] x);
00125         //IWriter get (inout short[] x);
00126         //IWriter get (inout int[] x);
00127         //IWriter get (inout long[] x);
00128         //IWriter get (inout ubyte[] x);
00129         //IWriter get (inout ushort[] x);
00130         //IWriter get (inout uint[] x);
00131         //IWriter get (inout ulong[] x);
00132         //IWriter get (inout float[] x);
00133         //IWriter get (inout double[] x);
00134         //IWriter get (inout real[] x);
00135 
00136         /***********************************************************************
00137         
00138                 This is the mechanism used for binding arbitrary classes 
00139                 to the IO system. If a class implements IReadable, it can
00140                 be used as a target for IReader get() operations. That is, 
00141                 implementing IReadable is intended to transform any class 
00142                 into an IReader adaptor for the content held therein.
00143 
00144         ***********************************************************************/
00145 
00146         IReader get (IReadable x);
00147 
00148         /***********************************************************************
00149         
00150                 Push the size (in bytes) to use for the next array-read.
00151                 By default, array sizes are read from the input stream, 
00152                 so this is the means by which one may specify the size
00153                 where the stream is not formatted in such a manner.
00154 
00155                 @code
00156                         char[]  x;
00157                         int     size;
00158                         IReader reader;
00159 
00160                         reader.push(size).get(x);
00161                 @endcode
00162 
00163         ***********************************************************************/
00164 
00165         IReader push (uint size);
00166 
00167         /***********************************************************************
00168                 
00169                 Pause the current thread until some content arrives in
00170                 the associated input buffer. This may stall forever.
00171 
00172         ***********************************************************************/
00173 
00174         void wait ();
00175 
00176         /***********************************************************************
00177         
00178                 Return the size (byte count) of the subsequent data stream. 
00179                 This is typically read from the stream as a number, but may 
00180                 be provided by the client code via the push() method.
00181 
00182         ***********************************************************************/
00183 
00184         uint length ();
00185 
00186         /***********************************************************************
00187         
00188                 Return the buffer associated with this reader
00189 
00190         ***********************************************************************/
00191 
00192         IBuffer getBuffer ();
00193 
00194         /***********************************************************************
00195         
00196                 Set the allocator to use for array management. Arrays are
00197                 always allocated by the IReader. That is, you cannot read
00198                 data into an array slice (for example). Instead, a number
00199                 of IArrayAllocator classes are available to manage memory
00200                 allocation when reading array content. 
00201 
00202                 By default, an IReader will allocate each array from the 
00203                 heap. You can change that behavior by calling this method
00204                 with an IArrayAllocator of choice. For instance, there 
00205                 is a BufferAllocator which will slice an array directly 
00206                 from the buffer where possible. Also available is the 
00207                 record-oriented SliceAllocator, which slices memory from 
00208                 within a pre-allocated heap area, and should be reset by
00209                 the client code after each record has been read (to avoid 
00210                 unnecessary growth).
00211 
00212                 See ArrayAllocator for more information.
00213 
00214         ***********************************************************************/
00215 
00216         void setAllocator (IArrayAllocator memory); 
00217 
00218         /***********************************************************************
00219         
00220         ***********************************************************************/
00221 
00222         IArrayAllocator getAllocator (); 
00223 
00224         /***********************************************************************
00225         
00226                 Set the configured IStringDecoder. These are intended to
00227                 be used as a conversion mechanism between various character
00228                 representations. They are also expected to be used for the
00229                 process of applying character encodings.
00230 
00231         ***********************************************************************/
00232 
00233         void setStringDecoder (IStringDecoder s);
00234 
00235         /***********************************************************************
00236         
00237                 And these are used for the >> syntax
00238 
00239         ***********************************************************************/
00240 
00241         version (UseShiftOperators)
00242         {
00243                 IReader opShr (IReadable s);
00244                 IReader opShr (inout bool x);
00245                 IReader opShr (inout ubyte x);
00246                 IReader opShr (inout byte x);
00247                 IReader opShr (inout ushort x);
00248                 IReader opShr (inout short x);
00249                 IReader opShr (inout uint x);
00250                 IReader opShr (inout int x);
00251                 IReader opShr (inout ulong x);
00252                 IReader opShr (inout long x);
00253                 IReader opShr (inout float x);
00254                 IReader opShr (inout double x);
00255                 IReader opShr (inout real x);
00256 
00257                 IReader opShr (inout char x);
00258                 IReader opShr (inout wchar x);
00259                 IReader opShr (inout dchar x);
00260 
00261                 IReader opShr (inout char[] x);
00262                 IReader opShr (inout wchar[] x);
00263                 IReader opShr (inout dchar[] x);
00264         }
00265 }

Generated on Sun Nov 7 19:06:52 2004 for Mango by doxygen 1.3.6