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 */
124 QByteArray toImapSequence() const;
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 */
210 QByteArray toImapSequenceSet() const;
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 */
220 ImapInterval::List intervals() const;
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
QList< ImapInterval > List
A list of ImapInterval objects.
Definition imapset.h:49
qint64 Id
Describes the ids stored in the interval.
Definition imapset.h:44
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition imapset.h:142
qint64 Id
Describes the ids stored in the set.
Definition imapset.h:147
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:56:30 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.