.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 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.
.\"
.\" 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
.\"
.\" 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 "Mail::Box::Tie::ARRAY 3pm"
.TH Mail::Box::Tie::ARRAY 3pm "2014-08-24" "perl v5.20.0" "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"
Mail::Box::Tie::ARRAY \- access an existing message folder as array
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use Mail::Box::Manager;
\& my $mgr    = Mail::Box::Manager\->new;
\& my $folder = $mgr\->open(folder => \*(Aqinbox\*(Aq);
\&
\& use Mail::Box::Tie::ARRAY;
\& tie my(@inbox), \*(AqMail::Box::Tie::ARRAY\*(Aq, $folder;
\&
\& # deprecated, but works too
\& use Mail::Box::Tie;
\& tie my(@inbox), \*(AqMail::Box::Tie\*(Aq, $folder;
\&
\& foreach (@inbox) {print $_\->short}
\& print $_\->print foreach @inbox;
\& my $emails = @inbox;
\&
\& print $inbox[3];
\& print scalar @inbox;
\& push @inbox, Mail::Box::Message\->new(...);
\& delete $inbox[6];
\& print $inbox[0]\->head\->get(\*(Aqstatus\*(Aq);
\&
\& my $folder = tied @inbox;
\& untie @inbox;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Certainly when you look at a folder as a list of messages, it is logical to
access the folder through an array.
.PP
Not all operations on arrays are supported.  Actually, most functions which
would reduce the size of the array are modified instead to mark messages for
deletion.
.PP
Examples what you \fIcannot\fR do:
.PP
.Vb 1
\& shift/unshift/pop/splice @inbox;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
.IP "\fB\s-1TIEARRAY\s0\fR('Mail::Box::Tie::ARRAY', \s-1FOLDER\s0)" 4
.IX Item "TIEARRAY('Mail::Box::Tie::ARRAY', FOLDER)"
Create the tie on an existing folder.
.Sp
example: tie an array to a folder
.Sp
.Vb 3
\& my $mgr   = Mail::Box::Manager\->new;
\& my $inbox = $mgr\->new(folder => $ENV{MAIL});
\& tie my(@inbox), \*(AqMail::Box::Tie::Array\*(Aq, ref $inbox, $inbox;
.Ve
.SS "Tied Interface"
.IX Subsection "Tied Interface"
.ie n .IP "$obj\->\fB\s-1DELETE\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1DELETE\s0\fR()" 4
.IX Item "$obj->DELETE()"
Flag a message to be removed.  Be warned that the message stays in
the folder, and is not removed before the folder is written.
.Sp
example:
.Sp
.Vb 2
\& delete $inbox[5];
\& $inbox[5]\->delete;   #same
.Ve
.ie n .IP "$obj\->\fB\s-1FETCH\s0\fR($index)" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1FETCH\s0\fR($index)" 4
.IX Item "$obj->FETCH($index)"
Get the message which is at the indicated location in the list of
messages contained in this folder.  Deleted messages will be returned
as \f(CW\*(C`undef\*(C'\fR.
.Sp
example:
.Sp
.Vb 3
\& print $inbox[3];     # 4th message in the folder
\& print @inbox[3,0];   # 4th and first of the folder
\& print $inbox[\-1];    # last message
.Ve
.ie n .IP "$obj\->\fB\s-1FETCHSIZE\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1FETCHSIZE\s0\fR()" 4
.IX Item "$obj->FETCHSIZE()"
Return the total number of messages in a folder.  This is called when
the folder-array is used in scalar context, for instance.
.Sp
example:
.Sp
.Vb 2
\& if(@inbox > 10)    # contains more than 10 messages?
\& my $nrmsgs = @inbox;
.Ve
.ie n .IP "$obj\->\fB\s-1PUSH\s0\fR(@messages)" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1PUSH\s0\fR(@messages)" 4
.IX Item "$obj->PUSH(@messages)"
Add \f(CW@messages\fR to the end of the folder.
.Sp
example:
.Sp
.Vb 1
\&    push @inbox, $newmsg;
.Ve
.ie n .IP "$obj\->\fB\s-1STORE\s0\fR($index, $message)" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1STORE\s0\fR($index, \f(CW$message\fR)" 4
.IX Item "$obj->STORE($index, $message)"
Random message replacement is not permitted \-\-doing so would disturb threads
etc.  An error occurs if you try to do this. The only thing which is allowed
is to store a message at the first free index at the end of the folder (which
is also achievable with \s-1\fIPUSH\s0()\fR).
.Sp
example:
.Sp
.Vb 3
\& $inbox[8] = $add;
\& $inbox[\-1] = $add;
\& push @inbox, $add;
.Ve
.ie n .IP "$obj\->\fB\s-1STORESIZE\s0\fR($length)" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1STORESIZE\s0\fR($length)" 4
.IX Item "$obj->STORESIZE($length)"
Sets all messages behind from \f(CW$length\fR to the end of folder to be deleted.
.SH "DETAILS"
.IX Header "DETAILS"
.SS "Folder tied as array"
.IX Subsection "Folder tied as array"
\fILimitations\fR
.IX Subsection "Limitations"
.PP
This module implements \f(CW\*(C`TIEARRAY\*(C'\fR, \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR, \f(CW\*(C`FETCHSIZE\*(C'\fR,
\&\f(CW\*(C`STORESIZE\*(C'\fR, \f(CW\*(C`DELETE\*(C'\fR, \f(CW\*(C`PUSH\*(C'\fR, and \f(CW\*(C`DESTROY\*(C'\fR.
.PP
This module does not implement all other methods as described in
the Tie::Array documentation, because the real array of messages
is not permitted to shrink or be mutilated.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.117,
built on August 24, 2014. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR