.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::ScalarArray 3pm"
.TH IO::ScalarArray 3pm "2005-02-10" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::ScalarArray \- IO:: interface for reading/writing an array of scalars
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Perform I/O on strings, using the basic \s-1OO\s0 interface...
.PP
.Vb 2
\&    use IO::ScalarArray;
\&    @data = ("My mes", "sage:\en");
\&
\&    ### Open a handle on an array, and append to it:
\&    $AH = new IO::ScalarArray \e@data;
\&    $AH\->print("Hello");       
\&    $AH\->print(", world!\enBye now!\en");  
\&    print "The array is now: ", @data, "\en";
\&
\&    ### Open a handle on an array, read it line\-by\-line, then close it:
\&    $AH = new IO::ScalarArray \e@data;
\&    while (defined($_ = $AH\->getline)) { 
\&        print "Got line: $_";
\&    }
\&    $AH\->close;
\&
\&    ### Open a handle on an array, and slurp in all the lines:
\&    $AH = new IO::ScalarArray \e@data;
\&    print "All lines:\en", $AH\->getlines; 
\&
\&    ### Get the current position (either of two ways):
\&    $pos = $AH\->getpos;         
\&    $offset = $AH\->tell;  
\&
\&    ### Set the current position (either of two ways):
\&    $AH\->setpos($pos);        
\&    $AH\->seek($offset, 0);
\&
\&    ### Open an anonymous temporary array:
\&    $AH = new IO::ScalarArray;
\&    $AH\->print("Hi there!");
\&    print "I printed: ", @{$AH\->aref}, "\en";      ### get at value
.Ve
.PP
Don't like \s-1OO\s0 for your I/O?  No problem.  
Thanks to the magic of an invisible \fItie()\fR, the following now 
works out of the box, just as it does with IO::Handle:
.PP
.Vb 2
\&    use IO::ScalarArray;
\&    @data = ("My mes", "sage:\en");
\&
\&    ### Open a handle on an array, and append to it:
\&    $AH = new IO::ScalarArray \e@data;
\&    print $AH "Hello";    
\&    print $AH ", world!\enBye now!\en";
\&    print "The array is now: ", @data, "\en";
\&
\&    ### Open a handle on a string, read it line\-by\-line, then close it:
\&    $AH = new IO::ScalarArray \e@data;
\&    while (<$AH>) {
\&        print "Got line: $_";
\&    }
\&    close $AH;
\&
\&    ### Open a handle on a string, and slurp in all the lines:
\&    $AH = new IO::ScalarArray \e@data;
\&    print "All lines:\en", <$AH>;
\&
\&    ### Get the current position (WARNING: requires 5.6):
\&    $offset = tell $AH;
\&
\&    ### Set the current position (WARNING: requires 5.6):
\&    seek $AH, $offset, 0;
\&
\&    ### Open an anonymous temporary scalar:
\&    $AH = new IO::ScalarArray;
\&    print $AH "Hi there!";
\&    print "I printed: ", @{$AH\->aref}, "\en";      ### get at value
.Ve
.PP
And for you folks with 1.x code out there: the old \fItie()\fR style still works,
though this is \fIunnecessary and deprecated\fR:
.PP
.Vb 1
\&    use IO::ScalarArray;
\&
\&    ### Writing to a scalar...
\&    my @a; 
\&    tie *OUT, \*(AqIO::ScalarArray\*(Aq, \e@a;
\&    print OUT "line 1\enline 2\en", "line 3\en";
\&    print "Array is now: ", @a, "\en"
\&
\&    ### Reading and writing an anonymous scalar... 
\&    tie *OUT, \*(AqIO::ScalarArray\*(Aq;
\&    print OUT "line 1\enline 2\en", "line 3\en";
\&    tied(OUT)\->seek(0,0);
\&    while (<OUT>) { 
\&        print "Got line: ", $_;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is part of the IO::Stringy distribution;
see IO::Stringy for change log and general information.
.PP
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 \*(L"file\*(R" whose contents are
the concatenation of the scalars in the array.  The handles created by 
this class are automatically tiehandle'd (though please see \*(L"\s-1WARNINGS\s0\*(R"
for information relevant to your Perl version).
.PP
For writing large amounts of data with individual \fIprint()\fR statements, 
this class is likely to be more efficient than IO::Scalar.
.PP
Basically, this:
.PP
.Vb 4
\&    my @a;
\&    $AH = new IO::ScalarArray \e@a;
\&    $AH\->print("Hel", "lo, ");         ### OO style
\&    $AH\->print("world!\en");            ### ditto
.Ve
.PP
Or this:
.PP
.Vb 4
\&    my @a;
\&    $AH = new IO::ScalarArray \e@a;
\&    print $AH "Hel", "lo, ";           ### non\-OO style
\&    print $AH "world!\en";              ### ditto
.Ve
.PP
Causes \f(CW@a\fR to be set to the following array of 3 strings:
.PP
.Vb 3
\&    ( "Hel" , 
\&      "lo, " , 
\&      "world!\en" )
.Ve
.PP
See IO::Scalar and compare with this class.
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "Construction"
.IX Subsection "Construction"
.IP "new [\s-1ARGS\s0...]" 4
.IX Item "new [ARGS...]"
\&\fIClass method.\fR
Return a new, unattached array handle.  
If any arguments are given, they're sent to \fIopen()\fR.
.IP "open [\s-1ARRAYREF\s0]" 4
.IX Item "open [ARRAYREF]"
\&\fIInstance method.\fR
Open the array handle on a new array, pointed to by \s-1ARRAYREF\s0.
If no \s-1ARRAYREF\s0 is given, a \*(L"private\*(R" array is created to hold
the file data.
.Sp
Returns the self object on success, undefined on error.
.IP "opened" 4
.IX Item "opened"
\&\fIInstance method.\fR
Is the array handle opened on something?
.IP "close" 4
.IX Item "close"
\&\fIInstance method.\fR
Disassociate the array handle from its underlying array.
Done automatically on destroy.
.SS "Input and output"
.IX Subsection "Input and output"
.IP "flush" 4
.IX Item "flush"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "getc" 4
.IX Item "getc"
\&\fIInstance method.\fR
Return the next character, or undef if none remain.
This does a \fIread\fR\|(1), which is somewhat costly.
.IP "getline" 4
.IX Item "getline"
\&\fIInstance method.\fR
Return the next line, or undef on end of data.
Can safely be called in an array context.
Currently, lines are delimited by \*(L"\en\*(R".
.IP "getlines" 4
.IX Item "getlines"
\&\fIInstance method.\fR
Get all remaining lines.
It will \fIcroak()\fR if accidentally called in a scalar context.
.IP "print \s-1ARGS\s0..." 4
.IX Item "print ARGS..."
\&\fIInstance method.\fR
Print \s-1ARGS\s0 to the underlying array.
.Sp
Currently, this always causes a \*(L"seek to the end of the array\*(R"
and generates a new array entry.  This may change in the future.
.IP "read \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0];" 4
.IX Item "read BUF, NBYTES, [OFFSET];"
\&\fIInstance method.\fR
Read some bytes from the array.
Returns the number of bytes actually read, 0 on end-of-file, undef on error.
.IP "write \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0];" 4
.IX Item "write BUF, NBYTES, [OFFSET];"
\&\fIInstance method.\fR
Write some bytes into the array.
.SS "Seeking/telling and other attributes"
.IX Subsection "Seeking/telling and other attributes"
.IP "autoflush" 4
.IX Item "autoflush"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "binmode" 4
.IX Item "binmode"
\&\fIInstance method.\fR
No-op, provided for \s-1OO\s0 compatibility.
.IP "clearerr" 4
.IX Item "clearerr"
\&\fIInstance method.\fR  Clear the error and \s-1EOF\s0 flags.  A no-op.
.IP "eof" 4
.IX Item "eof"
\&\fIInstance method.\fR  Are we at end of file?
.IP "seek \s-1POS\s0,WHENCE" 4
.IX Item "seek POS,WHENCE"
\&\fIInstance method.\fR
Seek to a given position in the stream.
Only a \s-1WHENCE\s0 of 0 (\s-1SEEK_SET\s0) is supported.
.IP "tell" 4
.IX Item "tell"
\&\fIInstance method.\fR
Return the current position in the stream, as a numeric offset.
.IP "setpos \s-1POS\s0" 4
.IX Item "setpos POS"
\&\fIInstance method.\fR
Seek to a given position in the array, using the opaque \fIgetpos()\fR value.
Don't expect this to be a number.
.IP "getpos" 4
.IX Item "getpos"
\&\fIInstance method.\fR
Return the current position in the array, as an opaque value.
Don't expect this to be a number.
.IP "aref" 4
.IX Item "aref"
\&\fIInstance method.\fR
Return a reference to the underlying array.
.SH "WARNINGS"
.IX Header "WARNINGS"
Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
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 \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
and you see something like this...
.PP
.Vb 1
\&    attempt to seek on unopened filehandle
.Ve
.PP
\&...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 \s-1OO\s0 version; e.g.:
.PP
.Vb 2
\&    $AH\->seek(0,0);    ### GOOD: will work on any 5.005
\&    seek($AH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR ScalarArray.pm,v 1.7 2005/02/10 21:21:53 dfs Exp $
.SH "AUTHOR"
.IX Header "AUTHOR"
.SS "Primary Maintainer"
.IX Subsection "Primary Maintainer"
David F. Skoll (\fIdfs@roaringpenguin.com\fR).
.SS "Principal author"
.IX Subsection "Principal author"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SS "Other contributors"
.IX Subsection "Other contributors"
Thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):
.PP
\&\fIAndy Glew,\fR
for suggesting \f(CW\*(C`getc()\*(C'\fR.
.PP
\&\fIBrandon Browning,\fR
for suggesting \f(CW\*(C`opened()\*(C'\fR.
.PP
\&\fIEric L. Brine,\fR
for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
.PP
\&\fIDoug Wilson,\fR
for the IO::Handle inheritance and automatic tie-ing.