Mail::IMAPClient::MessageSet - phpMan

NAME
    Mail::IMAPClient::MessageSet - ranges of message sequence numbers

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
    specify 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)".)

CLASS METHODS
    The only class method you need to worry about is new. And if you create
    your Mail::IMAPClient::MessageSet objects via Mail::IMAPClient's Range
    method then you don't even need to worry about new.

  new
    Example:

     my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);

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

    If more then one argument is supplied to new, then those arguments
    should be more message numbers, lists, and ranges (or references to
    arrays of them) just as in the first argument.

    The message numbers passed to new 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 *Uid* parameter is true) or message sequence
    numbers.

    The new method will return a reference to a Mail::IMAPClient::MessageSet
    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.

OBJECT METHODS
    The only object method currently available to a
    Mail::IMAPClient::MessageSet object is the unfold method.

  unfold
    Example:

        my $msgset = $imap->Range( $imap->messages ) ;
        my @all_messages = $msgset->unfold;

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

OVERRIDDEN OPERATIONS
    Mail::IMAPClient::MessageSet overrides a number of operators in order to
    make manipulating your message sets easier. The overridden operations
    are:

  stringify
    Attempts to stringify a Mail::IMAPClient::MessageSet object will result
    in the compact message specification being returned, which is almost
    certainly what you will want.

  Auto-increment
    Attempts to autoincrement a Mail::IMAPClient::MessageSet object will
    result in a message (or messages) being added to the object's message
    set.

    Example:

        $msgset += 34;
        # Message #34 is now in the message set

  Concatenate
    Attempts to concatenate to a Mail::IMAPClient::MessageSet object will
    result in a message (or messages) being added to the object's message
    set.

    Example:

        $msgset .= "34,35,36,40:45";
        # Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set

    The ".=" operator and the "+=" 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.

  Autodecrement
    Attempts to autodecrement a Mail::IMAPClient::MessageSet object will
    result in a message being removed from the object's message set.

    Examples:

        $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

    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.

AUTHOR
     David J. Kernen
     The Kernen Consulting Group, Inc

COPYRIGHT
     Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
     All rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either:

    a) the "Artistic License" which comes with this Kit, or
    b) the GNU General Public License as published by the Free Software
    Foundation; either version 1, or (at your option) any later version.

    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.