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 KIMAP_IMAPSET_H
21#define KIMAP_IMAPSET_H
22
23#include "kimap_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 KIMAP {
32
33/**
34 Represents a single interval in an ImapSet.
35 This class is implicitly shared.
36*/
37class KIMAP_EXPORT ImapInterval
38{
39 public:
40 /**
41 * Describes the ids stored in the interval.
42 */
43 typedef qint64 Id;
44
45 /**
46 A list of ImapInterval objects.
47 */
48 typedef QList<ImapInterval> List;
49
50 /**
51 Constructs an interval that covers all positive numbers.
52 */
53 ImapInterval();
54
55 /**
56 Copy constructor.
57 */
58 ImapInterval( const ImapInterval &other );
59
60 /**
61 Create a new interval.
62 @param begin The begin of the interval.
63 @param end Keep default (0) to just set the interval begin
64 */
65 explicit ImapInterval( Id begin, Id end = 0 );
66
67 /**
68 Destructor.
69 */
70 ~ImapInterval();
71
72 /**
73 Assignment operator.
74 */
75 ImapInterval& operator=( const ImapInterval &other );
76
77 /**
78 Comparison operator.
79 */
80 bool operator==( const ImapInterval &other ) const;
81
82 /**
83 Returns the size of this interval.
84 Size is only defined for finite intervals.
85 */
86 Id size() const;
87
88 /**
89 Returns true if this interval has a defined begin.
90 */
91 bool hasDefinedBegin() const;
92
93 /**
94 Returns the begin of this interval. The value is the smallest value part of the interval.
95 Only valid if begin is defined.
96 */
97 Id begin() const;
98
99 /**
100 Returns true if this intercal has been defined.
101 */
102 bool hasDefinedEnd() const;
103
104 /**
105 Returns the end of this interval. This value is the largest value part of the interval.
106 Only valid if hasDefinedEnd() returned true.
107 */
108 Id end() const;
109
110 /**
111 Sets the begin of the interval.
112 */
113 void setBegin( Id value );
114
115 /**
116 Sets the end of this interval.
117 */
118 void setEnd( Id value );
119
120 /**
121 Converts this set into an IMAP compatible sequence.
122 */
123 QByteArray toImapSequence() const;
124
125 /**
126 Return the interval corresponding to the given IMAP-compatible QByteArray representation
127 */
128 static ImapInterval fromImapSequence( const QByteArray &sequence );
129
130 private:
131 class Private;
132 QSharedDataPointer<Private> d;
133};
134
135/**
136 Represents a set of natural numbers (1->\f$\infty\f$) in a as compact as possible form.
137 Used to address Akonadi items via the IMAP protocol or in the database.
138 This class is implicitly shared.
139*/
140class KIMAP_EXPORT ImapSet
141{
142 public:
143 /**
144 * Describes the ids stored in the set.
145 */
146 typedef qint64 Id;
147
148 /**
149 Constructs an empty set.
150 */
151 ImapSet();
152
153 /**
154 Constructs a set containing a single interval.
155 */
156 ImapSet( Id begin, Id end );
157
158 /**
159 Constructs a set containing a single value.
160 */
161 explicit ImapSet( Id value );
162
163 /**
164 Copy constructor.
165 */
166 ImapSet( const ImapSet &other );
167
168 /**
169 Destructor.
170 */
171 ~ImapSet();
172
173 /**
174 Assignment operator.
175 */
176 ImapSet& operator=( const ImapSet &other );
177
178 /**
179 Comparison operator.
180 */
181 bool operator==( const ImapSet &other ) const;
182
183 /**
184 Adds a single positive integer numbers to the set.
185 The list is sorted and split into as large as possible intervals.
186 No interval merging is performed.
187 @param value A positive integer number
188 */
189 void add( Id value );
190
191 /**
192 Adds the given list of positive integer numbers to the set.
193 The list is sorted and split into as large as possible intervals.
194 No interval merging is performed.
195 @param values List of positive integer numbers in arbitrary order
196 */
197 void add( const QList<Id> &values );
198
199 /**
200 Adds the given ImapInterval to this set.
201 No interval merging is performed.
202 @param interval the interval to add
203 */
204 void add( const ImapInterval &interval );
205
206 /**
207 Returns a IMAP-compatible QByteArray representation of this set.
208 */
209 QByteArray toImapSequenceSet() const;
210
211 /**
212 Return the set corresponding to the given IMAP-compatible QByteArray representation
213 */
214 static ImapSet fromImapSequenceSet( const QByteArray &sequence );
215
216 /**
217 Returns the intervals this set consists of.
218 */
219 ImapInterval::List intervals() const;
220
221 /**
222 Returns true if this set doesn't contains any values.
223 */
224 bool isEmpty() const;
225
226 private:
227 class Private;
228 QSharedDataPointer<Private> d;
229};
230
231}
232
233KIMAP_EXPORT QDebug& operator<<( QDebug& d, const KIMAP::ImapInterval &interval );
234KIMAP_EXPORT QDebug& operator<<( QDebug& d, const KIMAP::ImapSet &set );
235
236Q_DECLARE_METATYPE( KIMAP::ImapInterval )
237Q_DECLARE_METATYPE( KIMAP::ImapInterval::List )
238Q_DECLARE_METATYPE( KIMAP::ImapSet )
239
240#endif
241