{
    "mode": "perldoc",
    "parameter": "Mail::IMAPClient::MessageSet",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AIMAPClient%3A%3AMessageSet/json",
    "generated": "2026-06-13T03:52:00Z",
    "synopsis": "my @msgs = $imap->search(\"SUBJECT\",\"Virus\"); # returns 1,3,4,5,6,9,10\nmy $msgset = Mail::IMAPClient::MessageSet->new(@msgs);\nprint $msgset;  # prints \"1,3:6,9:10\"\n# add message 14 to the set:\n$msgset += 14;\nprint $msgset;  # prints \"1,3:6,9:10,14\"\n# add messages 16,17,18,19, and 20 to the set:\n$msgset .= \"16,17,18:20\";\nprint $msgset;  # prints \"1,3:6,9:10,14,16:20\"\n# Hey, I didn't really want message 17 in there; let's take it out:\n$msgset -= 17;\nprint $msgset;  # prints \"1,3:6,9:10,14,16,18:20\"\n# Now let's iterate over each message:\nfor my $msg (@$msgset)\n{  print \"$msg\\n\";  # Prints: \"1\\n3\\n4\\n5\\n6..16\\n18\\n19\\n20\\n\"\n}\nprint join(\"\\n\", @$msgset).\"\\n\";     # same simpler\nlocal $\" = \"\\n\"; print \"@$msgset\\n\"; # even more simple",
    "sections": {
        "NAME": {
            "content": "Mail::IMAPClient::MessageSet - ranges of message sequence numbers\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my @msgs = $imap->search(\"SUBJECT\",\"Virus\"); # returns 1,3,4,5,6,9,10\nmy $msgset = Mail::IMAPClient::MessageSet->new(@msgs);\nprint $msgset;  # prints \"1,3:6,9:10\"\n\n# add message 14 to the set:\n$msgset += 14;\nprint $msgset;  # prints \"1,3:6,9:10,14\"\n\n# add messages 16,17,18,19, and 20 to the set:\n$msgset .= \"16,17,18:20\";\nprint $msgset;  # prints \"1,3:6,9:10,14,16:20\"\n\n# Hey, I didn't really want message 17 in there; let's take it out:\n$msgset -= 17;\nprint $msgset;  # prints \"1,3:6,9:10,14,16,18:20\"\n\n# Now let's iterate over each message:\nfor my $msg (@$msgset)\n{  print \"$msg\\n\";  # Prints: \"1\\n3\\n4\\n5\\n6..16\\n18\\n19\\n20\\n\"\n}\nprint join(\"\\n\", @$msgset).\"\\n\";     # same simpler\nlocal $\" = \"\\n\"; print \"@$msgset\\n\"; # even more simple\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The Mail::IMAPClient::MessageSet module is designed to make life easier for programmers who need\nto manipulate potentially large sets of IMAP message UID's or sequence numbers.\n\nThis module presents an object-oriented interface into handling your message sets. The object\nreference returned by the new method is an overloaded reference to a scalar variable that\ncontains the message set's compact RFC2060 representation. The object is overloaded so that\nusing it like a string returns this compact message set representation. You can also add\nmessages to the set (using either a '.=' operator or a '+=' operator) or remove messages (with\nthe '-=' operator). And if you use it as an array reference, it will humor you and act like one\nby calling unfold for you.\n\nRFC2060 specifies that multiple messages can be provided to certain IMAP commands by separating\nthem with commas. For example, \"1,2,3,4,5\" would specify messages 1, 2, 3, 4, and (you guessed\nit!) 5. However, if you are performing an operation on lots of messages, this string can get\nquite long. So long that it may slow down your transaction, and perhaps even cause the server to\nreject it. So RFC2060 also permits you to specify a range of messages, so that messages 1, 2, 3,\n4 and 5 can also be specified as \"1:5\".\n\nThis is where Mail::IMAPClient::MessageSet comes in. It will convert your message set into the\nshortest correct syntax. This could potentially save you tons of network I/O, as in the case\nwhere you want to fetch the flags for all messages in a 10000 message folder, where the messages\nare all numbered sequentially. Delimited as commas, and making the best-case assumption that the\nfirst message is message \"1\", it would take 48893 bytes to specify the whole message set using\nthe comma-delimited method. To specify it as a range, it takes just seven bytes (1:10000).\n\nNote that the Mail::IMAPClient Range method can be used as a short-cut to specifying\n\"Mail::IMAPClient::MessageSet->new(@etc)\".)\n",
            "subsections": []
        },
        "CLASS METHODS": {
            "content": "The only class method you need to worry about is new. And if you create your\nMail::IMAPClient::MessageSet objects via Mail::IMAPClient's Range method then you don't even\nneed to worry about new.\n\nnew\nExample:\n\nmy $msgset = Mail::IMAPClient::MessageSet->new(@msgs);\n\nThe new method requires at least one argument. That argument can be either a message, a\ncomma-separated list of messages, a colon-separated range of messages, or a combination of\ncomma-separated messages and colon-separated ranges. It can also be a reference to an array of\nmessages, comma-separated message lists, and colon separated ranges.\n\nIf more then one argument is supplied to new, then those arguments should be more message\nnumbers, lists, and ranges (or references to arrays of them) just as in the first argument.\n\nThe message numbers passed to new can really be any kind of number at all but to be useful in a\nMail::IMAPClient session they should be either message UID's (if your *Uid* parameter is true)\nor message sequence numbers.\n\nThe new method will return a reference to a Mail::IMAPClient::MessageSet object. That object,\nwhen double quoted, will act just like a string whose value is the message set expressed in the\nshortest possible way, with the message numbers sorted in ascending order and with duplicates\nremoved.\n",
            "subsections": []
        },
        "OBJECT METHODS": {
            "content": "The only object method currently available to a Mail::IMAPClient::MessageSet object is the\nunfold method.\n\nunfold\nExample:\n\nmy $msgset = $imap->Range( $imap->messages ) ;\nmy @allmessages = $msgset->unfold;\n\nThe unfold method returns an array of messages that belong to the message set. If called in a\nscalar context it returns a reference to the array instead.\n",
            "subsections": []
        },
        "OVERRIDDEN OPERATIONS": {
            "content": "Mail::IMAPClient::MessageSet overrides a number of operators in order to make manipulating your\nmessage sets easier. The overridden operations are:\n\nstringify\nAttempts to stringify a Mail::IMAPClient::MessageSet object will result in the compact message\nspecification being returned, which is almost certainly what you will want.\n",
            "subsections": [
                {
                    "name": "Auto-increment",
                    "content": "Attempts to autoincrement a Mail::IMAPClient::MessageSet object will result in a message (or\nmessages) being added to the object's message set.\n\nExample:\n\n$msgset += 34;\n# Message #34 is now in the message set\n"
                },
                {
                    "name": "Concatenate",
                    "content": "Attempts to concatenate to a Mail::IMAPClient::MessageSet object will result in a message (or\nmessages) being added to the object's message set.\n\nExample:\n\n$msgset .= \"34,35,36,40:45\";\n# Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set\n\nThe \".=\" operator and the \"+=\" operator can be used interchangeably, but as you can see by\nlooking at the examples there are times when use of one has an aesthetic advantage over use of\nthe other.\n"
                },
                {
                    "name": "Autodecrement",
                    "content": "Attempts to autodecrement a Mail::IMAPClient::MessageSet object will result in a message being\nremoved from the object's message set.\n\nExamples:\n\n$msgset -= 34;\n# Message #34 is no longer in the message set\n$msgset -= \"1:10\";\n# Messages 1 through 10 are no longer in the message set\n\nIf you attempt to remove a message that was not in the original message set then your resulting\nmessage set will be the same as the original, only more expensive. However, if you attempt to\nremove several messages from the message set and some of those messages were in the message set\nand some were not, the additional overhead of checking for the messages that were not there is\nnegligible. In either case you get back the message set you want regardless of whether it was\nalready like that or not.\n"
                }
            ]
        },
        "AUTHOR": {
            "content": "David J. Kernen\nThe Kernen Consulting Group, Inc\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.\nAll rights reserved.\n\nThis program is free software; you can redistribute it and/or modify it under the terms of\neither:\n\na) the \"Artistic License\" which comes with this Kit, or\nb) the GNU General Public License as published by the Free Software Foundation; either version\n1, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See\neither the GNU General Public License or the Artistic License for more details. All your base\nare belong to us.\n",
            "subsections": []
        }
    },
    "summary": "Mail::IMAPClient::MessageSet - ranges of message sequence numbers",
    "flags": [],
    "examples": [],
    "see_also": []
}