/usr/share/doc/libio-stringy-perl/html/ScalarArray.pm.html

<HTML>
<HEAD>
  <TITLE>IO::ScalarArray 2.103</TITLE>
</HEAD>
<BODY 
       bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666">
<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>
</A><UL>
<LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A>
<LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A>
<LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A>
<LI> <A NAME="menu:PUBLIC_INTERFACE"><A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A></A>
<UL>
<LI> <A NAME="menu:Construction"><A HREF="#Construction">Construction</A></A>
<UL>
<LI> <A NAME="menu:item:new_ARGS"><A HREF="#item:new_ARGS">new [ARGS...]</A></A>
<LI> <A NAME="menu:item:open_ARRAYREF"><A HREF="#item:open_ARRAYREF">open [ARRAYREF]</A></A>
<LI> <A NAME="menu:item:opened"><A HREF="#item:opened">opened</A></A>
<LI> <A NAME="menu:item:close"><A HREF="#item:close">close</A></A>
</UL>
<LI> <A NAME="menu:Input_and_output"><A HREF="#Input_and_output">Input and output</A></A>
<UL>
<LI> <A NAME="menu:item:flush"><A HREF="#item:flush">flush </A></A>
<LI> <A NAME="menu:item:getc"><A HREF="#item:getc">getc</A></A>
<LI> <A NAME="menu:item:getline"><A HREF="#item:getline">getline</A></A>
<LI> <A NAME="menu:item:getlines"><A HREF="#item:getlines">getlines</A></A>
<LI> <A NAME="menu:item:print_ARGS"><A HREF="#item:print_ARGS">print ARGS...</A></A>
<LI> <A NAME="menu:item:read_BUF_NBYTES_OFFSET"><A HREF="#item:read_BUF_NBYTES_OFFSET">read BUF, NBYTES, [OFFSET];</A></A>
<LI> <A NAME="menu:item:write_BUF_NBYTES_OFFSET"><A HREF="#item:write_BUF_NBYTES_OFFSET">write BUF, NBYTES, [OFFSET];</A></A>
</UL>
<LI> <A NAME="menu:Seeking_telling_and_other_attributes"><A HREF="#Seeking_telling_and_other_attributes">Seeking/telling and other attributes</A></A>
<UL>
<LI> <A NAME="menu:item:autoflush"><A HREF="#item:autoflush">autoflush </A></A>
<LI> <A NAME="menu:item:binmode"><A HREF="#item:binmode">binmode</A></A>
<LI> <A NAME="menu:item:clearerr"><A HREF="#item:clearerr">clearerr</A></A>
<LI> <A NAME="menu:item:eof"><A HREF="#item:eof">eof </A></A>
<LI> <A NAME="menu:item:seek_POS_WHENCE"><A HREF="#item:seek_POS_WHENCE">seek POS,WHENCE</A></A>
<LI> <A NAME="menu:item:tell"><A HREF="#item:tell">tell</A></A>
<LI> <A NAME="menu:item:setpos_POS"><A HREF="#item:setpos_POS">setpos POS</A></A>
<LI> <A NAME="menu:item:getpos"><A HREF="#item:getpos">getpos</A></A>
<LI> <A NAME="menu:item:aref"><A HREF="#item:aref">aref</A></A>
</UL>
</UL>
<LI> <A NAME="menu:WARNINGS"><A HREF="#WARNINGS">WARNINGS</A></A>
<LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A>
<LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A>
<UL>
<LI> <A NAME="menu:Principal_author"><A HREF="#Principal_author">Principal author</A></A>
<LI> <A NAME="menu:Other_contributors"><A HREF="#Other_contributors">Other contributors</A></A>
</UL>
</UL>


<P><HR>
<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A>


<P>IO::ScalarArray - IO:: interface for reading/writing an array of scalars



<P><HR>
<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A>


<P>Perform I/O on strings, using the basic OO interface...

<FONT SIZE=3 FACE="courier"><PRE>
    use IO::ScalarArray;
    @data = (&quot;My mes&quot;, &quot;sage:\n&quot;);
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on an array, and append to it:
    $AH = new IO::ScalarArray \@data;
    $AH-&gt;print(&quot;Hello&quot;);       
    $AH-&gt;print(&quot;, world!\nBye now!\n&quot;);  
    print &quot;The array is now: &quot;, @data, &quot;\n&quot;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on an array, read it line-by-line, then close it:
    $AH = new IO::ScalarArray \@data;
    while (defined($_ = $AH-&gt;getline)) { 
	print &quot;Got line: $_&quot;;
    }
    $AH-&gt;close;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on an array, and slurp in all the lines:
    $AH = new IO::ScalarArray \@data;
    print &quot;All lines:\n&quot;, $AH-&gt;getlines; 
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Get the current position (either of two ways):
    $pos = $AH-&gt;getpos;         
    $offset = $AH-&gt;tell;  
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Set the current position (either of two ways):
    $AH-&gt;setpos($pos);        
    $AH-&gt;seek($offset, 0);
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open an anonymous temporary array:
    $AH = new IO::ScalarArray;
    $AH-&gt;print(&quot;Hi there!&quot;);
    print &quot;I printed: &quot;, @{$AH-&gt;aref}, &quot;\n&quot;;      ### get at value
</PRE></FONT>

<P>Don't like OO for your I/O?  No problem.  
Thanks to the magic of an invisible tie(), the following now 
works out of the box, just as it does with IO::Handle:
    
    use IO::ScalarArray;
    @data = (&quot;My mes&quot;, &quot;sage:\n&quot;);

<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on an array, and append to it:
    $AH = new IO::ScalarArray \@data;
    print $AH &quot;Hello&quot;;    
    print $AH &quot;, world!\nBye now!\n&quot;;
    print &quot;The array is now: &quot;, @data, &quot;\n&quot;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, read it line-by-line, then close it:
    $AH = new IO::ScalarArray \@data;
    while (&lt;$AH&gt;) {
	print &quot;Got line: $_&quot;;
    }
    close $AH;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open a handle on a string, and slurp in all the lines:
    $AH = new IO::ScalarArray \@data;
    print &quot;All lines:\n&quot;, &lt;$AH&gt;;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Get the current position (WARNING: requires 5.6):
    $offset = tell $AH;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Set the current position (WARNING: requires 5.6):
    seek $AH, $offset, 0;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Open an anonymous temporary scalar:
    $AH = new IO::ScalarArray;
    print $AH &quot;Hi there!&quot;;
    print &quot;I printed: &quot;, @{$AH-&gt;aref}, &quot;\n&quot;;      ### get at value
</PRE></FONT>

<P>And for you folks with 1.x code out there: the old tie() style still works,
though this is <I>unnecessary and deprecated</I>:

<FONT SIZE=3 FACE="courier"><PRE>
    use IO::ScalarArray;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Writing to a scalar...
    my @a; 
    tie *OUT, 'IO::ScalarArray', \@a;
    print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
    print &quot;Array is now: &quot;, @a, &quot;\n&quot;
</PRE></FONT>
<FONT SIZE=3 FACE="courier"><PRE>
    ### Reading and writing an anonymous scalar... 
    tie *OUT, 'IO::ScalarArray';
    print OUT &quot;line 1\nline 2\n&quot;, &quot;line 3\n&quot;;
    tied(OUT)-&gt;seek(0,0);
    while (&lt;OUT&gt;) { 
        print &quot;Got line: &quot;, $_;
    }
</PRE></FONT>


<P><HR>
<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A>


<P>This class is part of the IO::Stringy distribution;
see <A HREF="../IO/Stringy.pm.html">IO::Stringy</A> for change log and general information.


<P>The IO::ScalarArray class implements objects which behave just like 
IO::Handle (or FileHandle) objects, except that you may use them 
to write to (or read from) arrays of scalars.  Logically, an
array of scalars defines an in-core &quot;file&quot; whose contents are
the concatenation of the scalars in the array.  The handles created by 
this class are automatically tiehandle'd (though please see <A HREF="#WARNINGS">WARNINGS</A>
for information relevant to your Perl version).


<P>For writing large amounts of data with individual print() statements, 
this class is likely to be more efficient than IO::Scalar.


<P>Basically, this:

<FONT SIZE=3 FACE="courier"><PRE>
    my @a;
    $AH = new IO::ScalarArray \@a;
    $AH-&gt;print(&quot;Hel&quot;, &quot;lo, &quot;);         ### OO style
    $AH-&gt;print(&quot;world!\n&quot;);            ### ditto
</PRE></FONT>

<P>Or this:

<FONT SIZE=3 FACE="courier"><PRE>
    my @a;
    $AH = new IO::ScalarArray \@a;
    print $AH &quot;Hel&quot;, &quot;lo, &quot;;           ### non-OO style
    print $AH &quot;world!\n&quot;;              ### ditto
</PRE></FONT>

<P>Causes @a to be set to the following array of 3 strings:

<FONT SIZE=3 FACE="courier"><PRE>
    ( &quot;Hel&quot; , 
      &quot;lo, &quot; , 
      &quot;world!\n&quot; )
</PRE></FONT>

<P>See <A HREF="../IO/Scalar.pm.html">IO::Scalar</A> and compare with this class.



<P><HR>
<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A>



<P><HR>
<A NAME="Construction"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Construction</H3></A>



<DL>
<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>
<DD>
<I>Class method.</I>
Return a new, unattached array handle.  
If any arguments are given, they're sent to open().

<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>
<DD>
<I>Instance method.</I>
Open the array handle on a new array, pointed to by ARRAYREF.
If no ARRAYREF is given, a &quot;private&quot; array is created to hold
the file data.


<P>Returns the self object on success, undefined on error.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:opened">opened</A></B></DT>
<DD>
<I>Instance method.</I>
Is the array handle opened on something?

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:close">close</A></B></DT>
<DD>
<I>Instance method.</I>
Disassociate the array handle from its underlying array.
Done automatically on destroy.

</DL>



<P><HR>
<A NAME="Input_and_output"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Input and output</H3></A>



<DL>
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:flush">flush</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getc">getc</A></B></DT>
<DD>
<I>Instance method.</I>
Return the next character, or undef if none remain.
This does a read(1), which is somewhat costly.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getline">getline</A></B></DT>
<DD>
<I>Instance method.</I>
Return the next line, or undef on end of data.
Can safely be called in an array context.
Currently, lines are delimited by &quot;\n&quot;.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getlines">getlines</A></B></DT>
<DD>
<I>Instance method.</I>
Get all remaining lines.
It will croak() if accidentally called in a scalar context.

<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>
<DD>
<I>Instance method.</I>
Print ARGS to the underlying array.  


<P>Currently, this always causes a &quot;seek to the end of the array&quot;
and generates a new array entry.  This may change in the future.

<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>
<DD>
<I>Instance method.</I>
Read some bytes from the array.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.

<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>
<DD>
<I>Instance method.</I>
Write some bytes into the array.

</DL>



<P><HR>
<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>



<DL>
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:autoflush">autoflush</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:binmode">binmode</A></B></DT>
<DD>
<I>Instance method.</I>
No-op, provided for OO compatibility.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:clearerr">clearerr</A></B></DT>
<DD>
<I>Instance method.</I>  Clear the error and EOF flags.  A no-op.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:eof">eof</A></B></DT>
<DD>
<I>Instance method.</I>  Are we at end of file?

<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>
<DD>
<I>Instance method.</I>
Seek to a given position in the stream.
Only a WHENCE of 0 (SEEK_SET) is supported.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tell">tell</A></B></DT>
<DD>
<I>Instance method.</I>
Return the current position in the stream, as a numeric offset.

<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>
<DD>
<I>Instance method.</I>
Seek to a given position in the array, using the opaque getpos() value.
Don't expect this to be a number.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:getpos">getpos</A></B></DT>
<DD>
<I>Instance method.</I>
Return the current position in the array, as an opaque value.
Don't expect this to be a number.

<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:aref">aref</A></B></DT>
<DD>
<I>Instance method.</I>
Return a reference to the underlying array.

</DL>



<P><HR>
<A NAME="WARNINGS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> WARNINGS</H2></A>


<P>Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
it was missing support for <CODE>seek()</CODE>, <CODE>tell()</CODE>, and <CODE>eof()</CODE>.
Attempting to use these functions with an IO::ScalarArray will not work
prior to 5.005_57. IO::ScalarArray will not have the relevant methods 
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via <CODE>$^W</CODE> or <CODE>perl -w</CODE>),
and you see something like this...

<FONT SIZE=3 FACE="courier"><PRE>
    attempt to seek on unopened filehandle
</PRE></FONT>

<P>...then you are probably trying to use one of these functions
on an IO::ScalarArray with an old Perl.  The remedy is to simply
use the OO version; e.g.:

<FONT SIZE=3 FACE="courier"><PRE>
    $AH-&gt;seek(0,0);    ### GOOD: will work on any 5.005
    seek($AH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
</PRE></FONT>


<P><HR>
<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A>


<P>$Id: ScalarArray.pm,v 2.103 2001/08/09 08:04:44 eryq Exp $



<P><HR>
<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A>



<P><HR>
<A NAME="Principal_author"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Principal author</H3></A>


<P>Eryq (<I><FILE><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></FILE></I>).
President, ZeeGee Software Inc (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>).



<P><HR>
<A NAME="Other_contributors"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Other contributors</H3></A>


<P>Thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):


<P><I>Andy Glew,</I>
for suggesting <CODE>getc()</CODE>.


<P><I>Brandon Browning,</I>
for suggesting <CODE>opened()</CODE>.


<P><I>Eric L. Brine,</I>
for his offset-using read() and write() implementations. 


<P><I>Doug Wilson,</I>
for the IO::Handle inheritance and automatic tie-ing.

<P><HR>
<ADDRESS><FONT SIZE=-1>
Generated Sun Dec 21 13:54:37 2003 by cvu_pod2html
</FONT></ADDRESS>
</FONT></BODY>
</HTML>
libio-stringy-perl 2.110-5 / usr / share / doc / libio-stringy-perl / html / ScalarArray.pm.html
