# phpman > man > Mail::IMAPClient::MessageSet

## NAME
    [Mail::IMAPClient::MessageSet](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) - 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient/markdown) Range method can be used as a short-cut to specifying
    "[Mail::IMAPClient::MessageSet](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown)->new(@etc)".)

## CLASS METHODS
    The only class method you need to worry about is new. And if you create your
    [Mail::IMAPClient::MessageSet](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) objects via [Mail::IMAPClient](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient/markdown)'s Range method then you don't even
    need to worry about new.

  new
    Example:

     my $msgset = [Mail::IMAPClient::MessageSet](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/markdown) 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.