Add ARM files
[dh-make-perl] / dev / arm / libio-stringy-perl / io-stringy-2.110 / debian / libio-stringy-perl / usr / share / doc / libio-stringy-perl / html / ScalarArray.pm.html
1 <HTML>
2 <HEAD>
3   <TITLE>IO::ScalarArray 2.103</TITLE>
4 </HEAD>
5 <BODY 
6        bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
7 <FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>IO::ScalarArray 2.103</H1>
8 </A><UL>
9 <LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
10 <LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
11 <LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
12 <LI> <A NAME="menu:PUBLIC_INTERFACE"><A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A></A>
13 <UL>
14 <LI> <A NAME="menu:Construction"><A HREF="#Construction">Construction</A></A>
15 <UL>
16 <LI> <A NAME="menu:item:new_ARGS"><A HREF="#item:new_ARGS">new [ARGS...]</A></A>
17 <LI> <A NAME="menu:item:open_ARRAYREF"><A HREF="#item:open_ARRAYREF">open [ARRAYREF]</A></A>
18 <LI> <A NAME="menu:item:opened"><A HREF="#item:opened">opened</A></A>
19 <LI> <A NAME="menu:item:close"><A HREF="#item:close">close</A></A>
20 </UL>
21 <LI> <A NAME="menu:Input_and_output"><A HREF="#Input_and_output">Input and output</A></A>
22 <UL>
23 <LI> <A NAME="menu:item:flush"><A HREF="#item:flush">flush </A></A>
24 <LI> <A NAME="menu:item:getc"><A HREF="#item:getc">getc</A></A>
25 <LI> <A NAME="menu:item:getline"><A HREF="#item:getline">getline</A></A>
26 <LI> <A NAME="menu:item:getlines"><A HREF="#item:getlines">getlines</A></A>
27 <LI> <A NAME="menu:item:print_ARGS"><A HREF="#item:print_ARGS">print ARGS...</A></A>
28 <LI> <A NAME="menu:item:read_BUF_NBYTES_OFFSET"><A HREF="#item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET];</A></A>
29 <LI> <A NAME="menu:item:write_BUF_NBYTES_OFFSET"><A HREF="#item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET];</A></A>
30 </UL>
31 <LI> <A NAME="menu:Seeking_telling_and_other_attributes"><A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A></A>
32 <UL>
33 <LI> <A NAME="menu:item:autoflush"><A HREF="#item:autoflush">autoflush </A></A>
34 <LI> <A NAME="menu:item:binmode"><A HREF="#item:binmode">binmode</A></A>
35 <LI> <A NAME="menu:item:clearerr"><A HREF="#item:clearerr">clearerr</A></A>
36 <LI> <A NAME="menu:item:eof"><A HREF="#item:eof">eof </A></A>
37 <LI> <A NAME="menu:item:seek_POS_WHENCE"><A HREF="#item:seek_POS_WHENCE">seek POS,WHENCE</A></A>
38 <LI> <A NAME="menu:item:tell"><A HREF="#item:tell">tell</A></A>
39 <LI> <A NAME="menu:item:setpos_POS"><A HREF="#item:setpos_POS">setpos POS</A></A>
40 <LI> <A NAME="menu:item:getpos"><A HREF="#item:getpos">getpos</A></A>
41 <LI> <A NAME="menu:item:aref"><A HREF="#item:aref">aref</A></A>
42 </UL>
43 </UL>
44 <LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A>
45 <LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A>
46 <LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
47 <UL>
48 <LI> <A NAME="menu:Principal_author"><A HREF="#Principal_author">Principal author</A></A>
49 <LI> <A NAME="menu:Other_contributors"><A HREF="#Other_contributors">Other contributors</A></A>
50 </UL>
51 </UL>
52
53
54 <P><HR>
55 <A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>
56
57
58 <P>IO::ScalarArray - IO:: interface for reading/writing an array of scalars
59
60
61
62 <P><HR>
63 <A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>
64
65
66 <P>Perform I/O on strings, using the basic OO interface...
67
68 <FONT SIZE=3 FACE="courier"><PRE>
69     use IO::ScalarArray;
70     @data = (&quot;My mes&quot;, &quot;sage:\n&quot;);
71 </PRE></FONT>
72 <FONT SIZE=3 FACE="courier"><PRE>
73     ### Open a handle on an array, and append to it:
74     $AH = new IO::ScalarArray \@data;
75     $AH-&gt;print(&quot;Hello&quot;);       
76     $AH-&gt;print(&quot;, world!\nBye now!\n&quot;);  
77     print &quot;The array is now: &quot;, @data, &quot;\n&quot;;
78 </PRE></FONT>
79 <FONT SIZE=3 FACE="courier"><PRE>
80     ### Open a handle on an array, read it line-by-line, then close it:
81     $AH = new IO::ScalarArray \@data;
82     while (defined($_ = $AH-&gt;getline)) { 
83         print &quot;Got line: $_&quot;;
84     }
85     $AH-&gt;close;
86 </PRE></FONT>
87 <FONT SIZE=3 FACE="courier"><PRE>
88     ### Open a handle on an array, and slurp in all the lines:
89     $AH = new IO::ScalarArray \@data;
90     print &quot;All lines:\n&quot;, $AH-&gt;getlines; 
91 </PRE></FONT>
92 <FONT SIZE=3 FACE="courier"><PRE>
93     ### Get the current position (either of two ways):
94     $pos = $AH-&gt;getpos;         
95     $offset = $AH-&gt;tell;  
96 </PRE></FONT>
97 <FONT SIZE=3 FACE="courier"><PRE>
98     ### Set the current position (either of two ways):
99     $AH-&gt;setpos($pos);        
100     $AH-&gt;seek($offset, 0);
101 </PRE></FONT>
102 <FONT SIZE=3 FACE="courier"><PRE>
103     ### Open an anonymous temporary array:
104     $AH = new IO::ScalarArray;
105     $AH-&gt;print(&quot;Hi there!&quot;);
106     print &quot;I printed: &quot;, @{$AH-&gt;aref}, &quot;\n&quot;;      ### get at value
107 </PRE></FONT>
108
109 <P>Don't like OO for your I/O?  No problem.  
110 Thanks to the magic of an invisible tie(), the following now 
111 works out of the box, just as it does with IO::Handle:
112     
113     use IO::ScalarArray;
114     @data = (&quot;My mes&quot;, &quot;sage:\n&quot;);
115
116 <FONT SIZE=3 FACE="courier"><PRE>
117     ### Open a handle on an array, and append to it:
118     $AH = new IO::ScalarArray \@data;
119     print $AH &quot;Hello&quot;;    
120     print $AH &quot;, world!\nBye now!\n&quot;;
121     print &quot;The array is now: &quot;, @data, &quot;\n&quot;;
122 </PRE></FONT>
123 <FONT SIZE=3 FACE="courier"><PRE>
124     ### Open a handle on a string, read it line-by-line, then close it:
125     $AH = new IO::ScalarArray \@data;
126     while (&lt;$AH&gt;) {
127         print &quot;Got line: $_&quot;;
128     }
129     close $AH;
130 </PRE></FONT>
131 <FONT SIZE=3 FACE="courier"><PRE>
132     ### Open a handle on a string, and slurp in all the lines:
133     $AH = new IO::ScalarArray \@data;
134     print &quot;All lines:\n&quot;, &lt;$AH&gt;;
135 </PRE></FONT>
136 <FONT SIZE=3 FACE="courier"><PRE>
137     ### Get the current position (WARNING: requires 5.6):
138     $offset = tell $AH;
139 </PRE></FONT>
140 <FONT SIZE=3 FACE="courier"><PRE>
141     ### Set the current position (WARNING: requires 5.6):
142     seek $AH, $offset, 0;
143 </PRE></FONT>
144 <FONT SIZE=3 FACE="courier"><PRE>
145     ### Open an anonymous temporary scalar:
146     $AH = new IO::ScalarArray;
147     print $AH &quot;Hi there!&quot;;
148     print &quot;I printed: &quot;, @{$AH-&gt;aref}, &quot;\n&quot;;      ### get at value
149 </PRE></FONT>
150
151 <P>And for you folks with 1.x code out there: the old tie() style still works,
152 though this is <I>unnecessary and deprecated</I>:
153
154 <FONT SIZE=3 FACE="courier"><PRE>
155     use IO::ScalarArray;
156 </PRE></FONT>
157 <FONT SIZE=3 FACE="courier"><PRE>
158     ### Writing to a scalar...
159     my @a; 
160     tie *OUT, 'IO::ScalarArray', \@a;
161     print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
162     print &quot;Array is now: &quot;, @a, &quot;\n&quot;
163 </PRE></FONT>
164 <FONT SIZE=3 FACE="courier"><PRE>
165     ### Reading and writing an anonymous scalar... 
166     tie *OUT, 'IO::ScalarArray';
167     print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
168     tied(OUT)-&gt;seek(0,0);
169     while (&lt;OUT&gt;) { 
170         print &quot;Got line: &quot;, $_;
171     }
172 </PRE></FONT>
173
174
175 <P><HR>
176 <A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>
177
178
179 <P>This class is part of the IO::Stringy distribution;
180 see <A HREF="../IO/Stringy.pm.html">IO::Stringy</A> for change log and general information.
181
182
183 <P>The IO::ScalarArray class implements objects which behave just like 
184 IO::Handle (or FileHandle) objects, except that you may use them 
185 to write to (or read from) arrays of scalars.  Logically, an
186 array of scalars defines an in-core &quot;file&quot; whose contents are
187 the concatenation of the scalars in the array.  The handles created by 
188 this class are automatically tiehandle'd (though please see <A HREF="#WARNINGS">WARNINGS</A>
189 for information relevant to your Perl version).
190
191
192 <P>For writing large amounts of data with individual print() statements, 
193 this class is likely to be more efficient than IO::Scalar.
194
195
196 <P>Basically, this:
197
198 <FONT SIZE=3 FACE="courier"><PRE>
199     my @a;
200     $AH = new IO::ScalarArray \@a;
201     $AH-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;);         ### OO style
202     $AH-&gt;print(&quot;world!\n&quot;);            ### ditto
203 </PRE></FONT>
204
205 <P>Or this:
206
207 <FONT SIZE=3 FACE="courier"><PRE>
208     my @a;
209     $AH = new IO::ScalarArray \@a;
210     print $AH &quot;Hel&quot;, &quot;lo, &quot;;           ### non-OO style
211     print $AH &quot;world!\n&quot;;              ### ditto
212 </PRE></FONT>
213
214 <P>Causes @a to be set to the following array of 3 strings:
215
216 <FONT SIZE=3 FACE="courier"><PRE>
217     ( &quot;Hel&quot; , 
218       &quot;lo, &quot; , 
219       &quot;world!\n&quot; )
220 </PRE></FONT>
221
222 <P>See <A HREF="../IO/Scalar.pm.html">IO::Scalar</A> and compare with this class.
223
224
225
226 <P><HR>
227 <A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A>
228
229
230
231 <P><HR>
232 <A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A>
233
234
235
236 <DL>
237 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:new"><A NAME="item:new_ARGS">new [ARGS...]</A></A></B></DT>
238 <DD>
239 <I>Class method.</I>
240 Return a new, unattached array handle.  
241 If any arguments are given, they're sent to open().
242
243 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:open"><A NAME="item:open_ARRAYREF">open [ARRAYREF]</A></A></B></DT>
244 <DD>
245 <I>Instance method.</I>
246 Open the array handle on a new array, pointed to by ARRAYREF.
247 If no ARRAYREF is given, a &quot;private&quot; array is created to hold
248 the file data.
249
250
251 <P>Returns the self object on success, undefined on error.
252
253 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:opened">opened</A></B></DT>
254 <DD>
255 <I>Instance method.</I>
256 Is the array handle opened on something?
257
258 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:close">close</A></B></DT>
259 <DD>
260 <I>Instance method.</I>
261 Disassociate the array handle from its underlying array.
262 Done automatically on destroy.
263
264 </DL>
265
266
267
268 <P><HR>
269 <A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A>
270
271
272
273 <DL>
274 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:flush">flush</A></B></DT>
275 <DD>
276 <I>Instance method.</I>
277 No-op, provided for OO compatibility.
278
279 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getc">getc</A></B></DT>
280 <DD>
281 <I>Instance method.</I>
282 Return the next character, or undef if none remain.
283 This does a read(1), which is somewhat costly.
284
285 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getline">getline</A></B></DT>
286 <DD>
287 <I>Instance method.</I>
288 Return the next line, or undef on end of data.
289 Can safely be called in an array context.
290 Currently, lines are delimited by &quot;\n&quot;.
291
292 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getlines">getlines</A></B></DT>
293 <DD>
294 <I>Instance method.</I>
295 Get all remaining lines.
296 It will croak() if accidentally called in a scalar context.
297
298 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:print"><A NAME="item:print_ARGS">print ARGS...</A></A></B></DT>
299 <DD>
300 <I>Instance method.</I>
301 Print ARGS to the underlying array.  
302
303
304 <P>Currently, this always causes a &quot;seek to the end of the array&quot;
305 and generates a new array entry.  This may change in the future.
306
307 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:read"><A NAME="item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET];</A></A></B></DT>
308 <DD>
309 <I>Instance method.</I>
310 Read some bytes from the array.
311 Returns the number of bytes actually read, 0 on end-of-file, undef on error.
312
313 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:write"><A NAME="item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET];</A></A></B></DT>
314 <DD>
315 <I>Instance method.</I>
316 Write some bytes into the array.
317
318 </DL>
319
320
321
322 <P><HR>
323 <A NAME="Seeking_telling_and_other_attributes"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Seeking/telling and other attributes</H3></A>
324
325
326
327 <DL>
328 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:autoflush">autoflush</A></B></DT>
329 <DD>
330 <I>Instance method.</I>
331 No-op, provided for OO compatibility.
332
333 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:binmode">binmode</A></B></DT>
334 <DD>
335 <I>Instance method.</I>
336 No-op, provided for OO compatibility.
337
338 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:clearerr">clearerr</A></B></DT>
339 <DD>
340 <I>Instance method.</I>  Clear the error and EOF flags.  A no-op.
341
342 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:eof">eof</A></B></DT>
343 <DD>
344 <I>Instance method.</I>  Are we at end of file?
345
346 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:seek"><A NAME="item:seek_POS_WHENCE">seek POS,WHENCE</A></A></B></DT>
347 <DD>
348 <I>Instance method.</I>
349 Seek to a given position in the stream.
350 Only a WHENCE of 0 (SEEK_SET) is supported.
351
352 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tell">tell</A></B></DT>
353 <DD>
354 <I>Instance method.</I>
355 Return the current position in the stream, as a numeric offset.
356
357 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:setpos"><A NAME="item:setpos_POS">setpos POS</A></A></B></DT>
358 <DD>
359 <I>Instance method.</I>
360 Seek to a given position in the array, using the opaque getpos() value.
361 Don't expect this to be a number.
362
363 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getpos">getpos</A></B></DT>
364 <DD>
365 <I>Instance method.</I>
366 Return the current position in the array, as an opaque value.
367 Don't expect this to be a number.
368
369 <P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:aref">aref</A></B></DT>
370 <DD>
371 <I>Instance method.</I>
372 Return a reference to the underlying array.
373
374 </DL>
375
376
377
378 <P><HR>
379 <A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>
380
381
382 <P>Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
383 it was missing support for <CODE>seek()</CODE>, <CODE>tell()</CODE>, and <CODE>eof()</CODE>.
384 Attempting to use these functions with an IO::ScalarArray will not work
385 prior to 5.005_57. IO::ScalarArray will not have the relevant methods 
386 invoked; and even worse, this kind of bug can lie dormant for a while.
387 If you turn warnings on (via <CODE>$^W</CODE> or <CODE>perl -w</CODE>),
388 and you see something like this...
389
390 <FONT SIZE=3 FACE="courier"><PRE>
391     attempt to seek on unopened filehandle
392 </PRE></FONT>
393
394 <P>...then you are probably trying to use one of these functions
395 on an IO::ScalarArray with an old Perl.  The remedy is to simply
396 use the OO version; e.g.:
397
398 <FONT SIZE=3 FACE="courier"><PRE>
399     $AH-&gt;seek(0,0);    ### GOOD: will work on any 5.005
400     seek($AH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
401 </PRE></FONT>
402
403
404 <P><HR>
405 <A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>
406
407
408 <P>$Id: ScalarArray.pm,v 2.103 2001/08/09 08:04:44 eryq Exp $
409
410
411
412 <P><HR>
413 <A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>
414
415
416
417 <P><HR>
418 <A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A>
419
420
421 <P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
422 President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).
423
424
425
426 <P><HR>
427 <A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A>
428
429
430 <P>Thanks to the following individuals for their invaluable contributions
431 (if I've forgotten or misspelled your name, please email me!):
432
433
434 <P><I>Andy Glew,</I>
435 for suggesting <CODE>getc()</CODE>.
436
437
438 <P><I>Brandon Browning,</I>
439 for suggesting <CODE>opened()</CODE>.
440
441
442 <P><I>Eric L. Brine,</I>
443 for his offset-using read() and write() implementations. 
444
445
446 <P><I>Doug Wilson,</I>
447 for the IO::Handle inheritance and automatic tie-ing.
448
449 <P><HR>
450 <ADDRESS><FONT SIZE=-1>
451 Generated Sun Dec 21 13:54:37 2003 by cvu_pod2html
452 </FONT></ADDRESS>
453 </FONT></BODY>
454 </HTML>