KIMAP

imapset.h
1 /*
2  SPDX-FileCopyrightText: 2007 Volker Krause <[email protected]>
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 
17 namespace KIMAP
18 {
19 /**
20  Represents a single interval in an ImapSet.
21  This class is implicitly shared.
22 */
23 class KIMAP_EXPORT ImapInterval
24 {
25 public:
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  */
39  ImapInterval();
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  */
56  ~ImapInterval();
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 
116 private:
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 */
126 class KIMAP_EXPORT ImapSet
127 {
128 public:
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 
221 private:
222  class Private;
224 };
225 
226 }
227 
228 KIMAP_EXPORT QDebug &operator<<(QDebug &d, const KIMAP::ImapInterval &interval);
229 KIMAP_EXPORT QDebug &operator<<(QDebug &d, const KIMAP::ImapSet &set);
230 
231 Q_DECLARE_METATYPE(KIMAP::ImapInterval)
232 Q_DECLARE_METATYPE(KIMAP::ImapInterval::List)
233 Q_DECLARE_METATYPE(KIMAP::ImapSet)
qint64 Id
Describes the ids stored in the interval.
Definition: imapset.h:29
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Represents a single interval in an ImapSet.
Definition: imapset.h:23
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition: imapset.h:126
qint64 Id
Describes the ids stored in the set.
Definition: imapset.h:132
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 03:51:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.