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 4. Derivative works are permitted, but they must carry this notice 00027 in full and credit the original source. 00028 00029 00030 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 00031 00032 00033 @version Initial version, March 2004 00034 @author Kris 00035 @author Ivan Senji (the "alias get" idea) 00036 00037 00038 *******************************************************************************/ 00039 00040 module mango.io.model.IReader; 00041 00042 public import mango.io.model.IBuffer; 00043 00044 /******************************************************************************* 00045 00046 *******************************************************************************/ 00047 00048 typedef uint delegate (void* dst, uint count) BufferDecoder; 00049 00050 /******************************************************************************* 00051 00052 Any class implementing IReadable becomes part of the Reader framework 00053 00054 *******************************************************************************/ 00055 00056 interface IReadable 00057 { 00058 void read (IReader input); 00059 } 00060 00061 /******************************************************************************* 00062 00063 Any class implementing IDecoder can be bound to a reader using 00064 the setDecoder() method. 00065 00066 *******************************************************************************/ 00067 00068 interface IDecoder 00069 { 00070 ConverterType type (); 00071 00072 BufferDecoder bind (IReader input); 00073 } 00074 00075 /******************************************************************************* 00076 00077 *******************************************************************************/ 00078 00079 interface IArrayAllocator 00080 { 00081 void reset (); 00082 00083 void bind (IReader input); 00084 00085 bool isMutable (void* x); 00086 00087 void allocate (void[]* x, uint size, uint width, BufferDecoder convert); 00088 } 00089 00090 /******************************************************************************* 00091 00092 All reader instances should implement this interface. 00093 00094 *******************************************************************************/ 00095 00096 interface IReader 00097 { 00098 alias get opShr; 00099 alias get opCall; 00100 00101 /*********************************************************************** 00102 00103 These are the basic reader methods 00104 00105 ***********************************************************************/ 00106 00107 IReader get (inout bool x); 00108 IReader get (inout byte x); 00109 IReader get (inout ubyte x); 00110 IReader get (inout short x); 00111 IReader get (inout ushort x); 00112 IReader get (inout int x); 00113 IReader get (inout uint x); 00114 IReader get (inout long x); 00115 IReader get (inout ulong x); 00116 IReader get (inout float x); 00117 IReader get (inout double x); 00118 IReader get (inout real x); 00119 IReader get (inout char x); 00120 IReader get (inout wchar x); 00121 IReader get (inout dchar x); 00122 00123 IReader get (inout byte[] x, uint elements = uint.max); 00124 IReader get (inout short[] x, uint elements = uint.max); 00125 IReader get (inout int[] x, uint elements = uint.max); 00126 IReader get (inout long[] x, uint elements = uint.max); 00127 IReader get (inout ubyte[] x, uint elements = uint.max); 00128 IReader get (inout ushort[] x, uint elements = uint.max); 00129 IReader get (inout uint[] x, uint elements = uint.max); 00130 IReader get (inout ulong[] x, uint elements = uint.max); 00131 IReader get (inout float[] x, uint elements = uint.max); 00132 IReader get (inout double[] x, uint elements = uint.max); 00133 IReader get (inout real[] x, uint elements = uint.max); 00134 IReader get (inout char[] x, uint elements = uint.max); 00135 IReader get (inout wchar[] x, uint elements = uint.max); 00136 IReader get (inout dchar[] x, uint elements = uint.max); 00137 00138 /*********************************************************************** 00139 00140 This is the mechanism used for binding arbitrary classes 00141 to the IO system. If a class implements IReadable, it can 00142 be used as a target for IReader get() operations. That is, 00143 implementing IReadable is intended to transform any class 00144 into an IReader adaptor for the content held therein. 00145 00146 ***********************************************************************/ 00147 00148 IReader get (IReadable x); 00149 00150 /*********************************************************************** 00151 00152 Pause the current thread until some content arrives in 00153 the associated input buffer. This may stall forever. 00154 00155 ***********************************************************************/ 00156 00157 void wait (); 00158 00159 /*********************************************************************** 00160 00161 Return the buffer associated with this reader 00162 00163 ***********************************************************************/ 00164 00165 IBuffer getBuffer (); 00166 00167 /*********************************************************************** 00168 00169 Get the allocator to use for array management. Arrays are 00170 always allocated by the IReader. That is, you cannot read 00171 data into an array slice (for example). Instead, a number 00172 of IArrayAllocator classes are available to manage memory 00173 allocation when reading array content. 00174 00175 You might use this to manage the assigned allocator. For 00176 example, some allocators benefit from a reset() operation 00177 after each data 'record' has been processed. 00178 00179 ***********************************************************************/ 00180 00181 IArrayAllocator getAllocator (); 00182 00183 /*********************************************************************** 00184 00185 Set the allocator to use for array management. Arrays are 00186 always allocated by the IReader. That is, you cannot read 00187 data into an array slice (for example). Instead, a number 00188 of IArrayAllocator classes are available to manage memory 00189 allocation when reading array content. 00190 00191 By default, an IReader will allocate each array from the 00192 heap. You can change that behavior by calling this method 00193 with an IArrayAllocator of choice. For instance, there 00194 is a BufferAllocator which will slice an array directly 00195 from the buffer where possible. Also available is the 00196 record-oriented SliceAllocator, which slices memory from 00197 within a pre-allocated heap area, and should be reset by 00198 the client code after each record has been read (to avoid 00199 unnecessary growth). 00200 00201 See ArrayAllocator for more information. 00202 00203 ***********************************************************************/ 00204 00205 void setAllocator (IArrayAllocator memory); 00206 00207 /*********************************************************************** 00208 00209 Bind an IDecoder to the writer. Decoders are intended to 00210 be used as a conversion mechanism between various character 00211 representations (encodings), or the translation of any data 00212 type from one representation to another. Each data type may 00213 be configured with a distinct decoder, covering all native 00214 types (15 in total). 00215 00216 An appropriate decoder set should be attached to each 00217 IReader, and thus be available for subsequent use. A raw 00218 binary implementation is attached by default (no encoding). 00219 00220 See module mango.icu.UMango for an example of decoder 00221 implementation -- those classes bind the ICU converters 00222 to this IO package. 00223 00224 ***********************************************************************/ 00225 00226 void setDecoder (IDecoder d); 00227 }