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 }