/ 
Mail-IMAPClient-3.07
River stage one • 9 direct dependents • 9 total dependents
/ Mail::IMAPClient::MessageSet

NAME

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

INHERITANCE

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

DESCRIPTION

The 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 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.

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 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 Mail::IMAPClient Range method can be used as a short-cut to specifying Mail::IMAPClient::MessageSet->new(@etc).)

SEE ALSO

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

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 http://www.perl.com/perl/misc/Artistic.html