KIMAP2

imapset.h
1/*
2 Copyright (c) 2007 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef KIMAP2_IMAPSET_H
21#define KIMAP2_IMAPSET_H
22
23#include "kimap2_export.h"
24
25#include <QtCore/QByteArray>
26#include <QtCore/QDebug>
27#include <QtCore/QList>
28#include <QtCore/QMetaType>
29#include <QtCore/QSharedDataPointer>
30
31namespace KIMAP2
32{
33
34/**
35 Represents a single interval in an ImapSet.
36 This class is implicitly shared.
37*/
38class KIMAP2_EXPORT ImapInterval
39{
40public:
41 /**
42 * Describes the ids stored in the interval.
43 */
44 typedef qint64 Id;
45
46 /**
47 A list of ImapInterval objects.
48 */
50
51 /**
52 Constructs an interval that covers all positive numbers.
53 */
55
56 /**
57 Copy constructor.
58 */
59 ImapInterval(const ImapInterval &other);
60
61 /**
62 Create a new interval.
63 @param begin The begin of the interval.
64 @param end Keep default (0) to just set the interval begin
65 */
66 explicit ImapInterval(Id begin, Id end = 0);
67
68 /**
69 Destructor.
70 */
72
73 /**
74 Assignment operator.
75 */
76 ImapInterval &operator=(const ImapInterval &other);
77
78 /**
79 Comparison operator.
80 */
81 bool operator==(const ImapInterval &other) const;
82
83 /**
84 Returns the size of this interval.
85 Size is only defined for finite intervals.
86 */
87 Id size() const;
88
89 /**
90 Returns true if this interval has a defined begin.
91 */
92 bool hasDefinedBegin() const;
93
94 /**
95 Returns the begin of this interval. The value is the smallest value part of the interval.
96 Only valid if begin is defined.
97 */
98 Id begin() const;
99
100 /**
101 Returns true if this intercal has been defined.
102 */
103 bool hasDefinedEnd() const;
104
105 /**
106 Returns the end of this interval. This value is the largest value part of the interval.
107 Only valid if hasDefinedEnd() returned true.
108 */
109 Id end() const;
110
111 /**
112 Sets the begin of the interval.
113 */
114 void setBegin(Id value);
115
116 /**
117 Sets the end of this interval.
118 */
119 void setEnd(Id value);
120
121 /**
122 Converts this set into an IMAP compatible sequence.
123 */
125
126 /**
127 Return the interval corresponding to the given IMAP-compatible QByteArray representation
128 */
129 static ImapInterval fromImapSequence(const QByteArray &sequence);
130
131private:
132 class Private;
134};
135
136/**
137 Represents a set of natural numbers (1->∞) in a as compact as possible form.
138 Used to address Akonadi items via the IMAP protocol or in the database.
139 This class is implicitly shared.
140*/
141class KIMAP2_EXPORT ImapSet
142{
143public:
144 /**
145 * Describes the ids stored in the set.
146 */
147 typedef qint64 Id;
148
149 /**
150 Constructs an empty set.
151 */
152 ImapSet();
153
154 /**
155 Constructs a set containing a single interval.
156 */
157 ImapSet(Id begin, Id end);
158
159 /**
160 Constructs a set containing a single value.
161 */
162 explicit ImapSet(Id value);
163
164 /**
165 Copy constructor.
166 */
167 ImapSet(const ImapSet &other);
168
169 /**
170 Destructor.
171 */
172 ~ImapSet();
173
174 /**
175 Assignment operator.
176 */
177 ImapSet &operator=(const ImapSet &other);
178
179 /**
180 Comparison operator.
181 */
182 bool operator==(const ImapSet &other) const;
183
184 /**
185 Adds a single positive integer numbers to the set.
186 The list is sorted and split into as large as possible intervals.
187 No interval merging is performed.
188 @param value A positive integer number
189 */
190 void add(Id value);
191
192 /**
193 Adds the given list of positive integer numbers to the set.
194 The list is sorted and split into as large as possible intervals.
195 No interval merging is performed.
196 @param values List of positive integer numbers in arbitrary order
197 */
198 void add(const QVector<Id> &values);
199
200 /**
201 Adds the given ImapInterval to this set.
202 No interval merging is performed.
203 @param interval the interval to add
204 */
205 void add(const ImapInterval &interval);
206
207 /**
208 Returns a IMAP-compatible QByteArray representation of this set.
209 */
211
212 /**
213 Return the set corresponding to the given IMAP-compatible QByteArray representation
214 */
215 static ImapSet fromImapSequenceSet(const QByteArray &sequence);
216
217 /**
218 Returns the intervals this set consists of.
219 */
221
222 /**
223 Returns true if this set doesn't contains any values.
224 */
225 bool isEmpty() const;
226
227 /**
228 * Optimizes the ImapSet by sorting and merging overlapping intervals.
229 *
230 * Normally you shouldn't need to call this method. KIMAP will make sure
231 * to opimize the ImapSet before serializing it to string and sending it
232 * to the IMAP server.
233 */
234 void optimize();
235
236private:
237 class Private;
239};
240
241}
242
243KIMAP2_EXPORT QDebug &operator<<(QDebug &d, const KIMAP2::ImapInterval &interval);
244KIMAP2_EXPORT QDebug &operator<<(QDebug &d, const KIMAP2::ImapSet &set);
245
246Q_DECLARE_METATYPE(KIMAP2::ImapInterval)
247Q_DECLARE_METATYPE(KIMAP2::ImapInterval::List)
248Q_DECLARE_METATYPE(KIMAP2::ImapSet)
249
250#endif
Represents a single interval in an ImapSet.
Definition imapset.h:39
bool hasDefinedBegin() const
Returns true if this interval has a defined begin.
Definition imapset.cpp:104
ImapInterval()
Constructs an interval that covers all positive numbers.
Definition imapset.cpp:59
ImapInterval & operator=(const ImapInterval &other)
Assignment operator.
Definition imapset.cpp:80
static ImapInterval fromImapSequence(const QByteArray &sequence)
Return the interval corresponding to the given IMAP-compatible QByteArray representation.
Definition imapset.cpp:159
Id end() const
Returns the end of this interval.
Definition imapset.cpp:119
qint64 Id
Describes the ids stored in the interval.
Definition imapset.h:44
Id begin() const
Returns the begin of this interval.
Definition imapset.cpp:109
void setEnd(Id value)
Sets the end of this interval.
Definition imapset.cpp:134
Id size() const
Returns the size of this interval.
Definition imapset.cpp:93
bool operator==(const ImapInterval &other) const
Comparison operator.
Definition imapset.cpp:88
bool hasDefinedEnd() const
Returns true if this intercal has been defined.
Definition imapset.cpp:114
void setBegin(Id value)
Sets the begin of the interval.
Definition imapset.cpp:127
QList< ImapInterval > List
A list of ImapInterval objects.
Definition imapset.h:49
QByteArray toImapSequence() const
Converts this set into an IMAP compatible sequence.
Definition imapset.cpp:141
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition imapset.h:142
bool isEmpty() const
Returns true if this set doesn't contains any values.
Definition imapset.cpp:314
ImapSet()
Constructs an empty set.
Definition imapset.cpp:190
void optimize()
Optimizes the ImapSet by sorting and merging overlapping intervals.
Definition imapset.cpp:319
qint64 Id
Describes the ids stored in the set.
Definition imapset.h:147
QByteArray toImapSequenceSet() const
Returns a IMAP-compatible QByteArray representation of this set.
Definition imapset.cpp:272
void add(Id value)
Adds a single positive integer numbers to the set.
Definition imapset.cpp:239
static ImapSet fromImapSequenceSet(const QByteArray &sequence)
Return the set corresponding to the given IMAP-compatible QByteArray representation.
Definition imapset.cpp:294
bool operator==(const ImapSet &other) const
Comparison operator.
Definition imapset.cpp:224
ImapInterval::List intervals() const
Returns the intervals this set consists of.
Definition imapset.cpp:309
ImapSet & operator=(const ImapSet &other)
Assignment operator.
Definition imapset.cpp:216
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 31 2025 12:10:33 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.