.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::ScalarArray 3"
.TH IO::ScalarArray 3 "2020-05-18" "perl v5.30.2" "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 \fBtie()\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 \fBtie()\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 \f(CW\*(C`tiehandle\*(C'\fRd (though please see \*(L"\s-1WARNINGS\*(R"\s0
for information relevant to your Perl version).
.PP
For writing large amounts of data with individual \fBprint()\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 \fBopen()\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 "fileno" 4
.IX Item "fileno"
\&\fIInstance method.\fR
No-op, returns undef
.IP "getc" 4
.IX Item "getc"
\&\fIInstance method.\fR
Return the next character, or undef if none remain.
This does a \fBread\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 \fBcroak()\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, NBYTES,\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, NBYTES,\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,WHENCE\s0" 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 \fBgetpos()\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 "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Dianne Skoll (\fIdfs@roaringpenguin.com\fR).
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.