=head1 NAME

Mail::IMAPClient::MessageSet - ranges of message sequence nummers

=head1 INHERITANCE

=head1 SYNOPSIS

 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't really want message 17 in there; let's take it out:
 $msgset -= 17;
 print $msgset;  # prints "1,3:6,9:10,14,16,18:20"

 # Now let's iterate over each message:
 for my $msg (@$msgset)
 {  print "$msg\n";  # Prints: "1\n3\n4\n5\n6..16\n18\n19\n20\n"
 }
 print join("\n", @$msgset)."\n";     # same simpler
 local $" = "\n"; print "@$msgset\n"; # even more simple

=head1 DESCRIPTION

The B<Mail::IMAPClient::MessageSet> module is designed to make life easier
for programmers who need to manipulate potentially large sets of IMAP
message UID's or sequence numbers.

This module presents an object-oriented interface into handling your
message sets. The object reference returned by the L<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
L<unfold> for you.

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 specifiy a range of
messages, so that messages 1, 2, 3, 4 and 5 can also be specified as
"1:5".

This is where B<Mail::IMAPClient::MessageSet> 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).

Note that the L<Mail::IMAPClient> B<Range> method can be used as
a short-cut to specifying C<Mail::IMAPClient::MessageSet-E<gt>new(@etc)>.)

=head1 SEE ALSO

This module is part of Mail-IMAPClient distribution version 3.07,
built on April 28, 2008.

=head1 LICENSE

Copyrights 2008. For other contributors see Changes.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

