KIMAP2

imapset.h
1 /*
2  Copyright (c) 2007 Volker Krause <[email protected]>
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 
31 namespace KIMAP2
32 {
33 
34 /**
35  Represents a single interval in an ImapSet.
36  This class is implicitly shared.
37 */
38 class KIMAP2_EXPORT ImapInterval
39 {
40 public:
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  */
54  ImapInterval();
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  */
71  ~ImapInterval();
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 
131 private:
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 */
141 class KIMAP2_EXPORT ImapSet
142 {
143 public:
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 
236 private:
237  class Private;
239 };
240 
241 }
242 
243 KIMAP2_EXPORT QDebug &operator<<(QDebug &d, const KIMAP2::ImapInterval &interval);
244 KIMAP2_EXPORT QDebug &operator<<(QDebug &d, const KIMAP2::ImapSet &set);
245 
246 Q_DECLARE_METATYPE(KIMAP2::ImapInterval)
247 Q_DECLARE_METATYPE(KIMAP2::ImapInterval::List)
248 Q_DECLARE_METATYPE(KIMAP2::ImapSet)
249 
250 #endif
qint64 Id
Describes the ids stored in the set.
Definition: imapset.h:147
Represents a single interval in an ImapSet.
Definition: imapset.h:38
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:141
QList< ImapInterval > List
A list of ImapInterval objects.
Definition: imapset.h:49
Definition: acl.cpp:25
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 23:10:17 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.