Changes between Version 4 and Version 5 of ChapterIoStreamProtocol

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 File~~Output("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 File~~Output("output"~~), new Md5);
55		output.copy (new File~~Input~~("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.

Wiki Navigation

Changes between Version 4 and Version 5 of ChapterIoStreamProtocol

Legend:

ChapterIoStreamProtocol