1Mail::IMAPClient::MessaUgseeSretC(o3n)tributed Perl DocuMmaeinlt:a:tIiMoAnPClient::MessageSet(3)
2
3
4

NAME

6       Mail::IMAPClient::MessageSet - ranges of message sequence numbers
7

SYNOPSIS

9        my @msgs = $imap->search("SUBJECT","Virus"); # returns 1,3,4,5,6,9,10
10        my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
11        print $msgset;  # prints "1,3:6,9:10"
12
13        # add message 14 to the set:
14        $msgset += 14;
15        print $msgset;  # prints "1,3:6,9:10,14"
16
17        # add messages 16,17,18,19, and 20 to the set:
18        $msgset .= "16,17,18:20";
19        print $msgset;  # prints "1,3:6,9:10,14,16:20"
20
21        # Hey, I didn't really want message 17 in there; let's take it out:
22        $msgset -= 17;
23        print $msgset;  # prints "1,3:6,9:10,14,16,18:20"
24
25        # Now let's iterate over each message:
26        for my $msg (@$msgset)
27        {  print "$msg\n";  # Prints: "1\n3\n4\n5\n6..16\n18\n19\n20\n"
28        }
29        print join("\n", @$msgset)."\n";     # same simpler
30        local $" = "\n"; print "@$msgset\n"; # even more simple
31

DESCRIPTION

33       The Mail::IMAPClient::MessageSet module is designed to make life easier
34       for programmers who need to manipulate potentially large sets of IMAP
35       message UID's or sequence numbers.
36
37       This module presents an object-oriented interface into handling your
38       message sets. The object reference returned by the new method is an
39       overloaded reference to a scalar variable that contains the message
40       set's compact RFC2060 representation. The object is overloaded so that
41       using it like a string returns this compact message set representation.
42       You can also add messages to the set (using either a '.=' operator or a
43       '+=' operator) or remove messages (with the '-=' operator). And if you
44       use it as an array reference, it will humor you and act like one by
45       calling unfold for you.
46
47       RFC2060 specifies that multiple messages can be provided to certain
48       IMAP commands by separating them with commas. For example, "1,2,3,4,5"
49       would specify messages 1, 2, 3, 4, and (you guessed it!) 5. However, if
50       you are performing an operation on lots of messages, this string can
51       get quite long.  So long that it may slow down your transaction, and
52       perhaps even cause the server to reject it. So RFC2060 also permits you
53       to specify a range of messages, so that messages 1, 2, 3, 4 and 5 can
54       also be specified as "1:5".
55
56       This is where Mail::IMAPClient::MessageSet comes in. It will convert
57       your message set into the shortest correct syntax. This could
58       potentially save you tons of network I/O, as in the case where you want
59       to fetch the flags for all messages in a 10000 message folder, where
60       the messages are all numbered sequentially. Delimited as commas, and
61       making the best-case assumption that the first message is message "1",
62       it would take 48893 bytes to specify the whole message set using the
63       comma-delimited method. To specify it as a range, it takes just seven
64       bytes (1:10000).
65
66       Note that the Mail::IMAPClient Range method can be used as a short-cut
67       to specifying "Mail::IMAPClient::MessageSet->new(@etc)".)
68

CLASS METHODS

70       The only class method you need to worry about is new. And if you create
71       your Mail::IMAPClient::MessageSet objects via Mail::IMAPClient's Range
72       method then you don't even need to worry about new.
73
74   new
75       Example:
76
77        my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
78
79       The new method requires at least one argument. That argument can be
80       either a message, a comma-separated list of messages, a colon-separated
81       range of messages, or a combination of comma-separated messages and
82       colon-separated ranges. It can also be a reference to an array of
83       messages, comma-separated message lists, and colon separated ranges.
84
85       If more then one argument is supplied to new, then those arguments
86       should be more message numbers, lists, and ranges (or references to
87       arrays of them) just as in the first argument.
88
89       The message numbers passed to new can really be any kind of number at
90       all but to be useful in a Mail::IMAPClient session they should be
91       either message UID's (if your Uid parameter is true) or message
92       sequence numbers.
93
94       The new method will return a reference to a
95       Mail::IMAPClient::MessageSet object. That object, when double quoted,
96       will act just like a string whose value is the message set expressed in
97       the shortest possible way, with the message numbers sorted in ascending
98       order and with duplicates removed.
99

OBJECT METHODS

101       The only object method currently available to a
102       Mail::IMAPClient::MessageSet object is the unfold method.
103
104   unfold
105       Example:
106
107           my $msgset = $imap->Range( $imap->messages ) ;
108           my @all_messages = $msgset->unfold;
109
110       The unfold method returns an array of messages that belong to the
111       message set. If called in a scalar context it returns a reference to
112       the array instead.
113

OVERRIDDEN OPERATIONS

115       Mail::IMAPClient::MessageSet overrides a number of operators in order
116       to make manipulating your message sets easier. The overridden
117       operations are:
118
119   stringify
120       Attempts to stringify a Mail::IMAPClient::MessageSet object will result
121       in the compact message specification being returned, which is almost
122       certainly what you will want.
123
124   Auto-increment
125       Attempts to autoincrement a Mail::IMAPClient::MessageSet object will
126       result in a message (or messages) being added to the object's message
127       set.
128
129       Example:
130
131           $msgset += 34;
132           # Message #34 is now in the message set
133
134   Concatenate
135       Attempts to concatenate to a Mail::IMAPClient::MessageSet object will
136       result in a message (or messages) being added to the object's message
137       set.
138
139       Example:
140
141           $msgset .= "34,35,36,40:45";
142           # Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set
143
144       The ".=" operator and the "+=" operator can be used interchangeably,
145       but as you can see by looking at the examples there are times when use
146       of one has an aesthetic advantage over use of the other.
147
148   Autodecrement
149       Attempts to autodecrement a Mail::IMAPClient::MessageSet object will
150       result in a message being removed from the object's message set.
151
152       Examples:
153
154           $msgset -= 34;
155           # Message #34 is no longer in the message set
156           $msgset -= "1:10";
157           # Messages 1 through 10 are no longer in the message set
158
159       If you attempt to remove a message that was not in the original message
160       set then your resulting message set will be the same as the original,
161       only more expensive. However, if you attempt to remove several messages
162       from the message set and some of those messages were in the message set
163       and some were not, the additional overhead of checking for the messages
164       that were not there is negligible. In either case you get back the
165       message set you want regardless of whether it was already like that or
166       not.
167

AUTHOR

169        David J. Kernen
170        The Kernen Consulting Group, Inc
171
173        Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
174        All rights reserved.
175
176       This program is free software; you can redistribute it and/or modify it
177       under the terms of either:
178
179       a) the "Artistic License" which comes with this Kit, or
180       b) the GNU General Public License as published by the Free Software
181       Foundation; either version 1, or (at your option) any later version.
182
183       This program is distributed in the hope that it will be useful, but
184       WITHOUT ANY WARRANTY; without even the implied warranty of
185       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
186       General Public License or the Artistic License for more details. All
187       your base are belong to us.
188
189
190
191perl v5.36.0                      2023-01-20   Mail::IMAPClient::MessageSet(3)
Impressum