|
- Author:
- kris (IP: 17.228.23.90)
- Timestamp:
- 05/07/09 01:23:53 (15 years ago)
- Comment:
updated to 0.99.8 tango.io changes
Legend:
- Unmodified
- Added
- Removed
- Modified
-
ChapterIoStreamProtocol
v4 |
v5 |
|
2 | 2 | |
---|
3 | 3 | = Streams and !StreamIterators = |
---|
4 | | == Streams == |
---|
5 | 4 | |
---|
6 | | === !BufferedStream === |
---|
| 5 | === Buffered === |
---|
7 | 6 | |
---|
8 | | Buffers the flow of data from a upstream input. A downstream |
---|
9 | | neighbour can locate and use this buffer instead of creating |
---|
10 | | another instance of their own. |
---|
| 7 | !BufferedInput and !BufferedOutput buffer the flow of data from a upstream input/output. A downstream neighbour can locate and use this buffer instead of creating another instance of their own. |
---|
11 | 8 | |
---|
12 | | (note that upstream is closer to the source, and downstream is |
---|
13 | | further away) |
---|
| 9 | (note that upstream is closer to the source, and downstream is further away) |
---|
14 | 10 | |
---|
15 | | !BufferedInput, !BufferedOutput are streams buffer the flow of data from a upstream output. A downstream |
---|
16 | | neighbour can locate and use this buffer instead of creating another instance of their own. |
---|
| 11 | === Data === |
---|
17 | 12 | |
---|
18 | | === !DataFileStream === |
---|
19 | | !DataFileInput, !DataFileOutput composes a seekable file with buffer. A seek causes |
---|
20 | | the buffer to be cleared or flushed. |
---|
21 | | |
---|
22 | | === !DataStream === |
---|
23 | | !DataInput[[br]] |
---|
24 | | A simple way to read binary data from an arbitrary !InputStream, such as a file: |
---|
| 13 | !DataInput represents a simple way to read binary data from an arbitrary !InputStream, such as a file: |
---|
25 | 14 | {{{ |
---|
26 | 15 | #!d |
---|
27 | | auto input = new DataInput (new FileInput("path")); |
---|
28 | | auto x = input.getInt; |
---|
29 | | auto y = input.getDouble; |
---|
30 | | input.get (new char[10]); |
---|
| 16 | auto input = new DataInput (new File("path")); |
---|
| 17 | auto x = input.int32; |
---|
| 18 | auto y = input.float64; |
---|
| 19 | char[22] tmp; |
---|
| 20 | auto len = input.array (tmp); |
---|
31 | 21 | input.close; |
---|
32 | 22 | }}} |
---|
33 | 23 | |
---|
34 | | !DataOutput[[br]] |
---|
35 | | A simple way to write binary data to an arbitrary !OutputStream, such as a file: |
---|
| 24 | !DataOutput is is similar, bot for output to an arbitrary !OutputStream, such as a file: |
---|
36 | 25 | {{{ |
---|
37 | 26 | #!d |
---|
38 | | auto output = new DataOutput (new FileOutput("path")); |
---|
39 | | output.putInt (1024); |
---|
40 | | output.putDouble (3.14159); |
---|
41 | | output.put ("hello world"); |
---|
| 27 | auto output = new DataOutput (new File("path", File.WriteCreate)); |
---|
| 28 | output.int32 (1024); |
---|
| 29 | output.float64 (3.14159); |
---|
| 30 | output.array ("hello world"); |
---|
42 | 31 | output.flush.close; |
---|
43 | 32 | }}} |
---|
44 | 33 | |
---|
45 | | === !DigestStream === |
---|
46 | | !DigestInput[[br]] |
---|
47 | | Inject a digest filter into an input stream, updating the digest as information flows through it |
---|
| 34 | === !DataFile === |
---|
48 | 35 | |
---|
49 | | !DigestOutput[[br]] |
---|
50 | | Inject a digest filter into an output stream, updating the digest as information flows through it. Here's an example where we calculate |
---|
51 | | an MD5 digest as a side-effect of copying a file: |
---|
| 36 | !DataFileInput and !DataFileOutput compose a seekable File with a Data class. A seek causes the buffer to be cleared or flushed. |
---|
| 37 | |
---|
| 38 | === Digester === |
---|
| 39 | |
---|
| 40 | !DigestInput injects a digest filter into an input stream, updating the digest as information flows through it. |
---|
| 41 | |
---|
| 42 | !DigestOutput inject a digest filter into an output stream, updating the digest as information flows through it. Here's an example where we calculate an MD5 digest as a side-effect of copying a file: |
---|
52 | 43 | {{{ |
---|
53 | 44 | #!d |
---|
54 | | auto output = new DigestOutput(new FileOutput("output"), new Md5); |
---|
55 | | output.copy (new FileInput("input")); |
---|
| 45 | auto output = new DigestOutput(new File("output", File.WriteCreate), new Md5); |
---|
| 46 | output.copy (new File("input")); |
---|
56 | 47 | |
---|
57 | 48 | Stdout.formatln ("hex digest: {}", output.digest.hexDigest); |
---|
58 | 49 | }}} |
---|
59 | 50 | |
---|
60 | | === !EndianessStream === |
---|
| 51 | === Endian === |
---|
61 | 52 | |
---|
62 | | Streams for swapping endian-order. The stream is treated as a set |
---|
63 | | of same-sized elements. Note that partial elements are not mutated |
---|
| 53 | Streams for swapping endian-order. The stream is treated as a set of same-sized elements. Note that partial elements are not mutated. See !EndianInput and !EndianOutput |
---|
64 | 54 | |
---|
65 | | !EndianInput and !EndianOutput |
---|
| 55 | === Format === |
---|
66 | 56 | |
---|
67 | | === !FileStream === |
---|
68 | | |
---|
69 | | Trivial wrapper around a !FileConduit |
---|
70 | | |
---|
71 | | !FileInput and !FileOutput |
---|
72 | | |
---|
73 | | === !FormatStream === |
---|
74 | | |
---|
75 | | Simple way to hook up a utf8 formatter to an arbitrary !OutputStream, |
---|
76 | | such as a file: |
---|
77 | | |
---|
| 57 | Simple way to hook up a utf8 formatter to an arbitrary !OutputStream, such as a file, socket, or other: |
---|
78 | 58 | {{{ |
---|
79 | 59 | #!d |
---|
80 | | auto output = new FormatOutput (new FileOutput("path")); |
---|
| 60 | auto output = new FormatOutput!(char) (new File("path", File.WriteCreate)); |
---|
81 | 61 | output.formatln ("{} green bottles", 10); |
---|
82 | 62 | output.close; |
---|
83 | 63 | }}} |
---|
84 | 64 | |
---|
85 | | This is a trivial wrapper around the Print class, and is limited |
---|
86 | | to emitting utf8 output. Use the Print class directly in order to |
---|
87 | | generate utf16/32 output instead. |
---|
| 65 | This is a wrapper around the Layout class, and is typed for either char, wchar or dchar output. |
---|
88 | 66 | |
---|
89 | | Note that this class is a true instance of !OutputStream, by way of |
---|
90 | | inheritance via the Print superclass. |
---|
| 67 | === Greedy === |
---|
91 | 68 | |
---|
92 | | === !GreedyStream === |
---|
| 69 | !GreedyOutput is a conduit filter that ensures its output is written in full. |
---|
93 | 70 | |
---|
94 | | !GreedyOutput[[br]] |
---|
95 | | A conduit filter that ensures its output is written in full |
---|
| 71 | !GreedyInput is a conduit filter that ensures its input is read in full. |
---|
96 | 72 | |
---|
97 | | !GreedyInput[[br]] |
---|
98 | | A conduit filter that ensures its input is read in full |
---|
| 73 | === Lines === |
---|
99 | 74 | |
---|
100 | | === !LineStream === |
---|
101 | | |
---|
102 | | !LineInput[[br]] |
---|
103 | | Simple way to hook up a line-tokenizer to an arbitrary !InputStream, |
---|
104 | | such as a file conduit: |
---|
| 75 | Simple way to hook up a line-tokenizer to an arbitrary !InputStream, such as a file conduit: |
---|
105 | 76 | {{{ |
---|
106 | 77 | #!d |
---|
107 | | auto input = new LineInput (new FileInput("path")); |
---|
| 78 | auto input = new LineInput!(char) (new File("path")); |
---|
108 | 79 | foreach (line; input) |
---|
109 | 80 | ... |
---|
111 | 82 | }}} |
---|
112 | 83 | |
---|
113 | | Note that this is just a simple wrapper around !LineIterator, and |
---|
114 | | supports utf8 lines only. Use !LineIterator directly for utf16/32 |
---|
115 | | support, or use the other tango.text.stream classes directly for |
---|
116 | | other tokenizing needs. |
---|
| 84 | === Map === |
---|
117 | 85 | |
---|
118 | | Note that this class is a true instance of !InputStream, by way of |
---|
119 | | inheritance via the Iterator superclass. |
---|
| 86 | !MapInput!(T) provides load facilities for a properties stream. That is, a file or other medium containing lines of text with a name=value layout |
---|
120 | 87 | |
---|
121 | | === !MapStream === |
---|
| 88 | !MapOutput!(T) provides write facilities on a properties stream. That is, a file or other medium which will contain lines of text with a name=value layout |
---|
122 | 89 | |
---|
123 | | !MapInput!(T) |
---|
124 | | Provides load facilities for a properties stream. That is, a file |
---|
125 | | or other medium containing lines of text with a name=value layout |
---|
| 90 | === Snoop === |
---|
126 | 91 | |
---|
127 | | !MapOutput!(T) |
---|
128 | | Provides write facilities on a properties stream. That is, a file |
---|
129 | | or other medium which will contain lines of text with a name=value |
---|
130 | | layout |
---|
| 92 | !SnoopInput, !SnoopOutput represent streams for exposing call behaviour. By default, activity trace is sent to Cerr. This can be useful for logging/debugging the stream calls. |
---|
131 | 93 | |
---|
| 94 | === !TextFile === |
---|
132 | 95 | |
---|
133 | | === !SnoopStream === |
---|
| 96 | !TextFileInput and !TextFileOutput combines a File with Text IO. |
---|
134 | 97 | |
---|
135 | | !SnoopInput, !SnoopOutput |
---|
136 | | Streams to expose call behaviour. By default, activity trace is sent to Cerr. |
---|
| 98 | === Typed === |
---|
137 | 99 | |
---|
138 | | This is usefull for logging/debugging the stream calls. |
---|
| 100 | !TypedInput!(T) and !TypedOutput!(T) are streams to expose simple native types as discrete elements. I/O is buffered and should yield fair performance. |
---|
139 | 101 | |
---|
140 | | === !TextFileStream === |
---|
| 102 | === Utf === |
---|
| 103 | !UtfInput!(T,S) and !UtfOutput!(S,T) represent UTF conversion streams, supporting cross-translation of char, wchar and dchar variants. For supporting endian variations, configure an appropriate Endian upstream of this one (closer to the source) |
---|
141 | 104 | |
---|
142 | | !TextFileInput and !TextFileOutput[[br]] |
---|
143 | | Composes a file with line-oriented input |
---|
| 105 | == Iterators == |
---|
144 | 106 | |
---|
145 | | === !TypedStream === |
---|
146 | | |
---|
147 | | !TypedInput!(T) and !TypedOutput!(T)[[br]] |
---|
148 | | Streams to expose simple native types as discrete elements. I/O is buffered and should yield fair performance. |
---|
149 | | |
---|
150 | | === !UtfStream === |
---|
151 | | !UtfInput!(T,S) and !UtfOutput!(S,T)[[br]] |
---|
152 | | UTF conversion streams, supporting cross-translation of char, wchar |
---|
153 | | and dchar variants. For supporting endian variations, configure the |
---|
154 | | appropriate !EndianStream upstream of this one (closer to the source) |
---|
155 | | |
---|
156 | | |
---|
157 | | == Streaming Iterators == |
---|
158 | | |
---|
159 | | Tango has a set of classes to split streaming text into elements matching a specific pattern. These classes operate upon an !InputStream, and are templated for char, wchar, and dchar data types. For example, there’s an iterator for producing lines of text based upon finding embedded end-of-line markers. Iterator classes are clients of Buffer, and can therefore be mixed with reader and/or writer clients also. |
---|
| 107 | Tango has a set of classes to split streaming text into elements matching a specific pattern. These classes operate upon an !InputStream, and are templated for char, wchar, and dchar data types. For example, there’s an iterator for producing lines of text based upon finding embedded end-of-line markers. See Delimiters, Lines, Patterns and Quotes. |
---|
160 | 108 | |
---|
161 | 109 | Iterator results are usually aliased directly from the containing buffer, thus avoiding heap activity where an application doesn’t need it. Where the resultant element is to be retained by the application, it should be copied before continuing. |
|
|