Mercurial > ~dholland > hg > ag > index.cgi

comparison doc/misc/html/oldclasslib/charsink.html @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>Character Sink Class Definitions</TITLE>
5 </HEAD>
6
7
8 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
9 TEXT="#000000" LINK="#0033CC"
10 VLINK="#CC0033" ALINK="#CC0099">
11
12 <P>
13 <IMG ALIGN="right" SRC="../images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30 >
15 <BR CLEAR="all">
16 Back to :
17 <A HREF="../index.html">Index</A> |
18 <A HREF="index.html">Class libraries for examples</A>
19 <P>
20
21
22 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
23 WIDTH=1010 HEIGHT=2 >
24 <P>
25
26 <H1>Character Sink Class Definitions</H1>
27 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
28 WIDTH=1010 HEIGHT=2 >
29 <P>
30 <BR>
31 <H2>Introduction</H2>
32
33 A character_sink is an abstract class, from which are derived
34 two useful classes, an output_file class and a
35 string_accumulator class. The basic idea of a character sink
36 is that it can be used as the generic output device for a
37 process that generates characters. Other character_sink
38 classes can easily be imagined, in particular, parsers that
39 take character input.
40 <P>
41 Because character_sink is an abstract class, you cannot
42 declare a character_sink. You may however declare a pointer
43 to a character sink:
44 <PRE>
45 character_sink *sink;
46 </PRE>
47 Character sinks overload the "&lt;&lt;" operator for int, (char *)
48 and (unsigned char *) operands and return a reference to the
49 sink so that multiple operations are possible. For example:
50 <PRE>
51 *sink &lt;&lt; 'c' &lt;&lt; "xyz";
52 </PRE>
53 The important aspect of a character sink is that a stream of
54 characters can be easily switched from one destination to
55 another.
56 <P>
57 <BR>
58
59 <H2> The output_file Class </H2>
60 The output_file class is derived from the character sink
61 class. There are two initializers: one with no arguments,
62 which simply sends characters on to stdout; and one which
63 takes a file name as an argument. If the file can be opened,
64 characters are sent to the file, otherwise, they go to
65 stdout. For example:
66 <PRE>
67 output_file out; //sinks characters to stdout
68 output_file out("foo.bar"); //sinks characters to foo.bar
69 output_file out(NULL); //sinks characters to stdout
70
71 out &lt;&lt; "Hello, world" &lt;&lt; '!';
72
73 character_sink *sink = &out; // sink points to an output_file
74 </PRE>
75 Note, that unlike normal C++ stream I/O, there is no binary
76 to ascii conversion involved.
77 <P>
78 <BR>
79
80 <H2> The string_accumulator Class </H2>
81
82 The string_accumulator is derived from the character sink
83 class, so you may use it as a destination for any character
84 stream. Rather than pass characters on, however, a
85 string_accumulator saves them up for later use. A
86 string_accumulator works like a push down stack. Each level
87 of the stack consists of a string. When you add characters to
88 a string_accumulator they are appended to the topmost string
89 on the stack.
90
91 Operators are provided for the following functions:
92 <UL>
93 <LI> increment the stack level, thus starting a new string </LI>
94 <LI> decrement the stack level, thus discarding the top string </LI>
95 <LI> append a character or string to the top string </LI>
96 <LI> remove the last character from the top string on the stack </LI>
97 <LI> inspect or change characters on the stack. </LI>
98 <LI> obtain a pointer to the top string on the stack </LI>
99 <LI> concatenate the top strings on the stack </LI>
100 <LI> obtain a permanent copy of the top string on the stack </LI>
101 <LI> find the length of a string </LI>
102 <LI> reset the string accumulator </LI>
103 </UL>
104 <P>
105 <BR>
106
107 <H2> Declaring a string_accumulator </H2>
108
109 To declare a string_accumulator, you must specify the amount
110 of storage to be reserved for string storage. If you wish you
111 may also specify the maximum number of levels. If you do not
112 specify the number of levels you will get just one level. For
113 example:
114 <PRE>
115 string_accumulator sa(1000, 20);
116 string_accumulator lsa(100);
117 </PRE>
118 provides for 1000 characters and 20 levels in sa but just 100
119 characters in a single level in lsa.
120 <P>
121 <BR>
122
123 <H2> Changing Levels </H2>
124
125 The "++" operator has been overloaded to increment the stack
126 level. You may pre-increment the level to begin accumulating a
127 nested string of characters. For example:
128 <PRE>
129 ++sa;
130 </PRE>
131 To discard the top string on the stack, use the pre-decrement
132 operator "--":
133 <PRE>
134 --sa;
135 </PRE>
136 The pre-increment and pre-decrement operators return a
137 reference to the string_accumulator so that you may combine
138 operations in a single expression:
139 <PRE>
140 ++sa &lt;&lt; "Hello, world!";
141 </PRE>
142 If you store characters on a stack without incrementing the
143 level, they are appended to the string at the current level.
144 In particular, if you declare a string_accumulator with only
145 a single level, you need never increment or decrement it. You
146 may, however, wish to use the reset operator.
147 <P>
148 Post-increment and post-decrement operators are also defined
149 for convenience in use. Instead of returning a reference to
150 the string_accumulator, however, they simply return a copy of
151 the control structure (in its pre-decrement or
152 pre-increment state) which allows read-only access to the
153 content of the string_accumulator. This can nevertheless be
154 quite useful:
155 <PRE>
156 char *top_string = copy(sa--);
157 </PRE>
158 <P>
159 <BR>
160
161 <H2> Appending Characters to a String </H2>
162
163 To append characters you may use the overloaded "&lt;&lt;"
164 operator, which also returns a reference to the string
165 accumulator so you may combine operations:
166 <PRE>
167 sa &lt;&lt; "Hello, world" &lt;&lt; '!';
168 </PRE>
169 To start a new string and append characters use the
170 pre-increment operator as well:
171 <PRE>
172 ++sa &lt;&lt; "Hello, world" &lt;&lt; '!';
173 </PRE>
174 <P>
175 <BR>
176
177 <H2> Removing Characters from a String </H2>
178
179 To pop off the last character on the top string:
180 <PFRE>
181 int c;
182 sa &lt;&lt; c;
183 </PRE>
184 <P>
185 <BR>
186
187 <H2> Accessing the Content of a String </H2>
188
189 To inspect or change the k'th character from the top of the
190 stack:
191 <PRE>
192 int c = sa[k];
193 sa[k] = '!';
194 </PRE>
195 If k is zero you get the last character on topmost string
196 in the string_accumulator.
197 <P>
198 To get a pointer to the top string on the stack, use the
199 (char *) cast operator:
200 <PRE>
201 char *p;
202 p = (char *) sa;
203 </PRE>
204 <BR>
205
206 <H2> Concatenating Strings </H2>
207
208 To concatenate the top two strings on the stack, use
209 concat():
210 <PRE>
211 concat(sa);
212 </PRE>
213 <BR>
214
215 <H2> Making a Permanent Copy of a String </H2>
216
217 To make a copy of the top string on the stack, use copy():
218 <PRE>
219 char *p = copy(sa);
220 </PRE>
221 Note that copy differs greatly from (char *), in that copy
222 allocates storage for a new copy of the string. When you are
223 done with it you should delete it:
224 <PRE>
225 delete [] p;
226 </PRE>
227 Note that copy() does not remove the string from the stack.
228 Use "--" to discard the string from the stack.
229 <P>
230 <BR>
231
232 <H2> Finding the Length of a String </H2>
233
234 To find the length of the top string on the stack, use
235 size():
236 <PRE>
237 unsigned n = size(sa);
238 </PRE>
239 Like strlen, size does not count the terminating null
240 character.
241 <P>
242 <BR>
243
244 <H2> Resetting a string_accumulator </H2>
245
246 The overloaded function reset() may be applied to a
247 string_accumulator to reset it to its initial state:
248 <PRE>
249 reset(sa);
250 </PRE>
251 reset returns a reference to the string accumulator so that
252 you may reset it and append text in a single statement:
253 <PRE>
254 reset(sa) &lt;&lt; "Hello, world!";
255 </PRE>
256 <P>
257 <BR>
258
259
260 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
261 WIDTH=1010 HEIGHT=2 >
262 <P>
263 <IMG ALIGN="right" SRC="../images/pslrb6d.gif" ALT="Parsifal Software"
264 WIDTH=181 HEIGHT=25>
265 <BR CLEAR="right">
266
267 <P>
268 Back to :
269 <A HREF="../index.html">Index</A> |
270 <A HREF="index.html">Class libraries for examples</A>
271
272 <P>
273 <ADDRESS><FONT SIZE="-1">
274 AnaGram parser generator - examples<BR>
275 Class libraries - Character sink class definitions<BR>
276 Copyright &copy; 1993-1999, Parsifal Software. <BR>
277 All Rights Reserved.<BR>
278 </FONT></ADDRESS>
279
280 </BODY>
281 </HTML>