KIMAP

imapset.h
1/*
2 SPDX-FileCopyrightText: 2007 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "kimap_export.h"
10
11#include <QByteArray>
12#include <QDebug>
13#include <QList>
14#include <QMetaType>
15#include <QSharedDataPointer>
16
17namespace KIMAP
18{
19/**
20 Represents a single interval in an ImapSet.
21 This class is implicitly shared.
22*/
23class KIMAP_EXPORT ImapInterval
24{
25public:
26 /**
27 * Describes the ids stored in the interval.
28 */
29 using Id = qint64;
30
31 /**
32 A list of ImapInterval objects.
33 */
35
36 /**
37 Constructs an interval that covers all positive numbers.
38 */
40
41 /**
42 Copy constructor.
43 */
44 ImapInterval(const ImapInterval &other);
45
46 /**
47 Create a new interval.
48 @param begin The begin of the interval.
49 @param end Keep default (0) to just set the interval begin
50 */
51 explicit ImapInterval(Id begin, Id end = 0);
52
53 /**
54 Destructor.
55 */
57
58 /**
59 Assignment operator.
60 */
61 ImapInterval &operator=(const ImapInterval &other);
62
63 /**
64 Comparison operator.
65 */
66 bool operator==(const ImapInterval &other) const;
67
68 /**
69 Returns the size of this interval.
70 Size is only defined for finite intervals.
71 */
72 Id size() const;
73
74 /**
75 Returns true if this interval has a defined begin.
76 */
77 bool hasDefinedBegin() const;
78
79 /**
80 Returns the begin of this interval. The value is the smallest value part of the interval.
81 Only valid if begin is defined.
82 */
83 Id begin() const;
84
85 /**
86 Returns true if this intercal has been defined.
87 */
88 bool hasDefinedEnd() const;
89
90 /**
91 Returns the end of this interval. This value is the largest value part of the interval.
92 Only valid if hasDefinedEnd() returned true.
93 */
94 Id end() const;
95
96 /**
97 Sets the begin of the interval.
98 */
99 void setBegin(Id value);
100
101 /**
102 Sets the end of this interval.
103 */
104 void setEnd(Id value);
105
106 /**
107 Converts this set into an IMAP compatible sequence.
108 */
109 [[nodiscard]] QByteArray toImapSequence() const;
110
111 /**
112 Return the interval corresponding to the given IMAP-compatible QByteArray representation
113 */
114 static ImapInterval fromImapSequence(const QByteArray &sequence);
115
116private:
117 class Private;
119};
120
121/**
122 Represents a set of natural numbers (1->∞) in a as compact as possible form.
123 Used to address Akonadi items via the IMAP protocol or in the database.
124 This class is implicitly shared.
125*/
126class KIMAP_EXPORT ImapSet
127{
128public:
129 /**
130 * Describes the ids stored in the set.
131 */
132 using Id = qint64;
133
134 /**
135 Constructs an empty set.
136 */
137 ImapSet();
138
139 /**
140 Constructs a set containing a single interval.
141 */
142 ImapSet(Id begin, Id end);
143
144 /**
145 Constructs a set containing a single value.
146 */
147 explicit ImapSet(Id value);
148
149 /**
150 Copy constructor.
151 */
152 ImapSet(const ImapSet &other);
153
154 /**
155 Destructor.
156 */
157 ~ImapSet();
158
159 /**
160 Assignment operator.
161 */
162 ImapSet &operator=(const ImapSet &other);
163
164 /**
165 Comparison operator.
166 */
167 bool operator==(const ImapSet &other) const;
168
169 /**
170 Adds a single positive integer numbers to the set.
171 The list is sorted and split into as large as possible intervals.
172 No interval merging is performed.
173 @param value A positive integer number
174 */
175 void add(Id value);
176
177 /**
178 Adds the given list of positive integer numbers to the set.
179 The list is sorted and split into as large as possible intervals.
180 No interval merging is performed.
181 @param values List of positive integer numbers in arbitrary order
182 */
183 void add(const QList<Id> &values);
184
185 /**
186 Adds the given ImapInterval to this set.
187 No interval merging is performed.
188 @param interval the interval to add
189 */
190 void add(const ImapInterval &interval);
191
192 /**
193 Returns a IMAP-compatible QByteArray representation of this set.
194 */
195 [[nodiscard]] QByteArray toImapSequenceSet() const;
196
197 /**
198 Return the set corresponding to the given IMAP-compatible QByteArray representation
199 */
200 static ImapSet fromImapSequenceSet(const QByteArray &sequence);
201
202 /**
203 Returns the intervals this set consists of.
204 */
205 [[nodiscard]] ImapInterval::List intervals() const;
206
207 /**
208 Returns true if this set doesn't contains any values.
209 */
210 [[nodiscard]] bool isEmpty() const;
211
212 /**
213 * Optimizes the ImapSet by sorting and merging overlapping intervals.
214 *
215 * Normally you shouldn't need to call this method. KIMAP will make sure
216 * to opimize the ImapSet before serializing it to string and sending it
217 * to the IMAP server.
218 */
219 void optimize();
220
221private:
222 class Private;
224};
225
226}
227
228KIMAP_EXPORT QDebug &operator<<(QDebug &d, const KIMAP::ImapInterval &interval);
229KIMAP_EXPORT QDebug &operator<<(QDebug &d, const KIMAP::ImapSet &set);
230
231Q_DECLARE_METATYPE(KIMAP::ImapInterval)
232Q_DECLARE_METATYPE(KIMAP::ImapInterval::List)
233Q_DECLARE_METATYPE(KIMAP::ImapSet)
Represents a single interval in an ImapSet.
Definition imapset.h:24
qint64 Id
Describes the ids stored in the interval.
Definition imapset.h:29
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition imapset.h:127
qint64 Id
Describes the ids stored in the set.
Definition imapset.h:132
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:02:55 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.