.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "Mail::IMAPClient::MessageSet 3"
.TH Mail::IMAPClient::MessageSet 3 2024-09-01 "perl v5.40.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::IMAPClient::MessageSet \- ranges of message sequence numbers
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& my @msgs = $imap\->search("SUBJECT","Virus"); # returns 1,3,4,5,6,9,10
\& my $msgset = Mail::IMAPClient::MessageSet\->new(@msgs);
\& print $msgset;  # prints "1,3:6,9:10"
\&
\& # add message 14 to the set:
\& $msgset += 14;
\& print $msgset;  # prints "1,3:6,9:10,14"
\&
\& # add messages 16,17,18,19, and 20 to the set:
\& $msgset .= "16,17,18:20";
\& print $msgset;  # prints "1,3:6,9:10,14,16:20"
\&
\& # Hey, I didn\*(Aqt really want message 17 in there; let\*(Aqs take it out:
\& $msgset \-= 17;
\& print $msgset;  # prints "1,3:6,9:10,14,16,18:20"
\&
\& # Now let\*(Aqs iterate over each message:
\& for my $msg (@$msgset)
\& {  print "$msg\en";  # Prints: "1\en3\en4\en5\en6..16\en18\en19\en20\en"
\& }
\& print join("\en", @$msgset)."\en";     # same simpler
\& local $" = "\en"; print "@$msgset\en"; # even more simple
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBMail::IMAPClient::MessageSet\fR module is designed to make life easier
for programmers who need to manipulate potentially large sets of IMAP
message UID's or sequence numbers.
.PP
This module presents an object-oriented interface into handling your
message sets. The object reference returned by the new method is an
overloaded reference to a scalar variable that contains the message set's
compact RFC2060 representation. The object is overloaded so that using
it like a string returns this compact message set representation. You
can also add messages to the set (using either a '.=' operator or a '+='
operator) or remove messages (with the '\-=' operator). And if you use
it as an array reference, it will humor you and act like one by calling
unfold for you.
.PP
RFC2060 specifies that multiple messages can be provided to certain IMAP
commands by separating them with commas. For example, "1,2,3,4,5" would
specify messages 1, 2, 3, 4, and (you guessed it!) 5. However, if you are
performing an operation on lots of messages, this string can get quite long.
So long that it may slow down your transaction, and perhaps even cause the
server to reject it. So RFC2060 also permits you to specify a range of
messages, so that messages 1, 2, 3, 4 and 5 can also be specified as
"1:5".
.PP
This is where \fBMail::IMAPClient::MessageSet\fR comes in. It will convert
your message set into the shortest correct syntax. This could potentially
save you tons of network I/O, as in the case where you want to fetch the
flags for all messages in a 10000 message folder, where the messages
are all numbered sequentially. Delimited as commas, and making the
best-case assumption that the first message is message "1", it would take
48893 bytes to specify the whole message set using the comma-delimited
method. To specify it as a range, it takes just seven bytes (1:10000).
.PP
Note that the Mail::IMAPClient \fBRange\fR method can be used as
a short-cut to specifying \f(CW\*(C`Mail::IMAPClient::MessageSet\->new(@etc)\*(C'\fR.)
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
The only class method you need to worry about is \fBnew\fR. And if you create
your \fBMail::IMAPClient::MessageSet\fR objects via Mail::IMAPClient's
\&\fBRange\fR method then you don't even need to worry about \fBnew\fR.
.SS new
.IX Subsection "new"
Example:
.PP
.Vb 1
\& my $msgset = Mail::IMAPClient::MessageSet\->new(@msgs);
.Ve
.PP
The \fBnew\fR method requires at least one argument. That argument can be
either a message, a comma-separated list of messages, a colon-separated
range of messages, or a combination of comma-separated messages and
colon-separated ranges. It can also be a reference to an array of messages,
comma-separated message lists, and colon separated ranges.
.PP
If more then one argument is supplied to \fBnew\fR, then those arguments should
be more message numbers, lists, and ranges (or references to arrays of them)
just as in the first argument.
.PP
The message numbers passed to \fBnew\fR can really be any kind of number at
all but to be useful in a Mail::IMAPClient session they should be either
message UID's (if your \fIUid\fR parameter is true) or message sequence numbers.
.PP
The \fBnew\fR method will return a reference to a \fBMail::IMAPClient::MessageSet\fR
object. That object, when double quoted, will act just like a string whose
value is the message set expressed in the shortest possible way, with the
message numbers sorted in ascending order and with duplicates removed.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
The only object method currently available to a \fBMail::IMAPClient::MessageSet\fR
object is the unfold method.
.SS unfold
.IX Subsection "unfold"
Example:
.PP
.Vb 2
\&    my $msgset = $imap\->Range( $imap\->messages ) ;
\&    my @all_messages = $msgset\->unfold;
.Ve
.PP
The \fBunfold\fR method returns an array of messages that belong to the
message set. If called in a scalar context it returns a reference to the
array instead.
.SH "OVERRIDDEN OPERATIONS"
.IX Header "OVERRIDDEN OPERATIONS"
\&\fBMail::IMAPClient::MessageSet\fR overrides a number of operators in order
to make manipulating your message sets easier. The overridden operations are:
.SS stringify
.IX Subsection "stringify"
Attempts to stringify a \fBMail::IMAPClient::MessageSet\fR object will result in
the compact message specification being returned, which is almost certainly
what you will want.
.SS Auto-increment
.IX Subsection "Auto-increment"
Attempts to autoincrement a \fBMail::IMAPClient::MessageSet\fR object will
result in a message (or messages) being added to the object's message set.
.PP
Example:
.PP
.Vb 2
\&    $msgset += 34;
\&    # Message #34 is now in the message set
.Ve
.SS Concatenate
.IX Subsection "Concatenate"
Attempts to concatenate to a \fBMail::IMAPClient::MessageSet\fR object will
result in a message (or messages) being added to the object's message set.
.PP
Example:
.PP
.Vb 2
\&    $msgset .= "34,35,36,40:45";
\&    # Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set
.Ve
.PP
The \f(CW\*(C`.=\*(C'\fR operator and the \f(CW\*(C`+=\*(C'\fR operator can be used interchangeably, but
as you can see by looking at the examples there are times when use of one
has an aesthetic advantage over use of the other.
.SS Autodecrement
.IX Subsection "Autodecrement"
Attempts to autodecrement a \fBMail::IMAPClient::MessageSet\fR object will
result in a message being removed from the object's message set.
.PP
Examples:
.PP
.Vb 4
\&    $msgset \-= 34;
\&    # Message #34 is no longer in the message set
\&    $msgset \-= "1:10";
\&    # Messages 1 through 10 are no longer in the message set
.Ve
.PP
If you attempt to remove a message that was not in the original message set
then your resulting message set will be the same as the original, only more
expensive. However, if you attempt to remove several messages from the message
set and some of those messages were in the message set and some were not,
the additional overhead of checking for the messages that were not there
is negligible. In either case you get back the message set you want regardless
of whether it was already like that or not.
.SH AUTHOR
.IX Header "AUTHOR"
.Vb 2
\& David J. Kernen
\& The Kernen Consulting Group, Inc
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
.Vb 2
\& Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
\& All rights reserved.
.Ve
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either:
.IP "a) the ""Artistic License"" which comes with this Kit, or" 4
.IX Item "a) the ""Artistic License"" which comes with this Kit, or"
.PD 0
.IP "b) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version." 4
.IX Item "b) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version."
.PD
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
General Public License or the Artistic License for more details. All your
base are belong to us.