1Mail::IMAPClient::MessaUgseeSretC(o3n)tributed Perl DocuMmaeinlt:a:tIiMoAnPClient::MessageSet(3)
2
6 Mail::IMAPClient::MessageSet - ranges of message sequence numbers
7
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 # add message 14 to the set:
14 $msgset += 14;
15 print $msgset; # prints "1,3:6,9:10,14"
16 # 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 # 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 # 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
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 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 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 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 Note that the Mail::IMAPClient Range method can be used as a short-cut
67 to specifying "Mail::IMAPClient::MessageSet->new(@etc)".)
68
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 new
75 Example:
76 my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
78 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 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 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 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
101 The only object method currently available to a
102 Mail::IMAPClient::MessageSet object is the unfold method.
103 unfold
105 Example:
106 my $msgset = $imap->Range( $imap->messages ) ;
108 my @all_messages = $msgset->unfold;
109 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
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 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 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 Example:
130 $msgset += 34;
132 # Message #34 is now in the message set
133 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 Example:
140 $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 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 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 Examples:
153 $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 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
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 This program is free software; you can redistribute it and/or modify it
177 under the terms of either:
178 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 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.
188perl v5.36.0 2023-01-20 Mail::IMAPClient::MessageSet(3)