1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtXmlPatterns module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40//
41// W A R N I N G
42// -------------
43//
44// This file is not part of the Qt API. It exists purely as an
45// implementation detail. This header file may change from version to
46// version without notice, or even be removed.
47//
48// We mean it.
49
50#ifndef Patternist_Cardinality_H
51#define Patternist_Cardinality_H
52
53#include <QtCore/QtGlobal>
54
55QT_BEGIN_NAMESPACE
56
57class QString;
58
59namespace QPatternist
60{
61 /**
62 * @short Represents a cardinality, a possible , often represented by occurrence indicators.
63 *
64 * As opposed to the cardinality concept in the XQuery/XPath specifications, which
65 * only allows cardinalities to be expressed with kleene operators, this representation
66 * allows ranges. For example, the cardinality 10-11, describes a sequence containing
67 * ten or eleven items, inclusive.
68 *
69 * @ingroup Patternist_types
70 * @see ItemType
71 * @see SequenceType
72 * @see <a href="http://www.w3.org/TR/xpath20/#prod-xpath-SequenceType">XML Path Language
73 * (XPath) 2.0, The EBNF grammar for SequenceType</a>
74 * @author Frans Englich <frans.englich@nokia.com>
75 */
76 class Cardinality
77 {
78 public:
79 /**
80 * This integer type, is what Cardinality uses for representing its ranges.
81 */
82 typedef qint32 Count;
83
84 /**
85 * Used with displayName(), and specifies
86 * how a display name for a Cardinality should be.
87 */
88 enum CustomizeDisplayName
89 {
90 /**
91 * Includes a describing string in the return value of displayName().
92 */
93 IncludeExplanation = 1,
94
95 /**
96 * Excludes a describing string in the return value of displayName().
97 */
98 ExcludeExplanation
99 };
100
101 /**
102 * A traditional copy constructor. This Cardinality becomes identical
103 * to @p other.
104 */
105 inline Cardinality(const Cardinality &other) : m_min(other.m_min),
106 m_max(other.m_max)
107 {
108 }
109
110 /**
111 * This default constructor constructs an invalid Cardinality. Using
112 * its operators and members yields undefined results. A value must
113 * first be assigned to it by creating a Cardinality with fromRange(), fromCount(),
114 * or one of the predefined cardinalities such as empty() or oneOrMore().
115 */
116 inline Cardinality() : m_min(-1), m_max(0)
117 {
118 }
119
120 /**
121 * The cardinality assigned to the exprssion <tt>()</tt>, formally speaking. The
122 * cardinality part of <tt>empty-sequence()</tt>.
123 */
124 static inline Cardinality empty()
125 {
126 return Cardinality(0, 0);
127 }
128
129 /**
130 * The cardinality implicitly specified in for example the sequence type
131 * <tt>item()</tt>. It has no kleene operator.
132 */
133 static inline Cardinality exactlyOne()
134 {
135 return Cardinality(1, 1);
136 }
137
138 /**
139 * Allows both no item, as in empty(), and exactlyOne(). Represented
140 * by the kleene operator <tt>?</tt>.
141 */
142 static inline Cardinality zeroOrOne()
143 {
144 return Cardinality(0, 1);
145 }
146
147 /**
148 * Allows any amount. This is therefore the widest, an unconstrained
149 * cardinality. Represented by the kleene operator <tt>*</tt>.
150 */
151 static inline Cardinality zeroOrMore()
152 {
153 return Cardinality(0, -1);
154 }
155
156 /**
157 * Allows one or more. Represented by the kleene operator <tt>+</tt>.
158 */
159 static inline Cardinality oneOrMore()
160 {
161 return Cardinality(1, -1);
162 }
163
164 /**
165 * Allows one or more. This cardinality has no kleene operator and is used
166 * by the implementation in order to be able to know when a cardinality
167 * that at amximum allows one, is exceeded.
168 */
169 static inline Cardinality twoOrMore()
170 {
171 return Cardinality(2, -1);
172 }
173
174 /**
175 * Determines the cardinality from the count of a sequence. For example, if
176 * @p count is 11, a Cardinality is returned that allows at minimum and maximum
177 * 11 items.
178 *
179 * @p count must be positive or zero. If it is not, the result is undefined.
180 * When debugging is enabled, a Q_ASSERT() macro ensures this.
181 */
182 static inline Cardinality fromCount(const Count count)
183 {
184 Q_ASSERT_X(count > -1, Q_FUNC_INFO,
185 "A count smaller than 0 makes no sense.");
186 return Cardinality(count, count);
187 }
188
189 /**
190 * Creates a Cardinality that allows @p minimum and @p maximum
191 * items, inclusive.
192 *
193 * If @p maximum is -1, it signals infinity.
194 *
195 * If you before hand knows that a predefined Cardinality is needed,
196 * remember to use one of the factory functions empty(), zeroOrOne(),
197 * exactlyOne(), oneOrMore() or zeroOrMore(), since they improves
198 * readability, are safer, and slightly faster.
199 */
200 static inline Cardinality fromRange(const Count minimum, const Count maximum)
201 {
202 Q_ASSERT_X(minimum > -1, Q_FUNC_INFO,
203 "minimum should never be less than 0.");
204 Q_ASSERT_X(minimum <= maximum || maximum == -1, Q_FUNC_INFO,
205 "minimum cannot be larger than maximum.");
206
207 return Cardinality(minimum, maximum);
208 }
209
210 static inline Cardinality fromExact(const Count count)
211 {
212 Q_ASSERT(count >= 0);
213 return Cardinality(count, count);
214 }
215
216 /**
217 * @returns the minimum amount of items this Cardinality allows. For example,
218 * for zeroOrOne() is 0 returned.
219 */
220 inline Count minimum() const
221 {
222 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
223 return m_min;
224 }
225
226 /**
227 * @returns the maximum amount of items this Cardinality allows. For example,
228 * for zeroOrOne() is 1 returned.
229 */
230 inline Count maximum() const
231 {
232 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
233 return m_max;
234 }
235
236 /**
237 * @returns @c true if this Cardinality allows one or more items. For example, for
238 * zeroOrOne() is @c false returned, while for zeroOrMore() is @c true returned.
239 */
240 inline bool allowsMany() const
241 {
242 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
243 return m_max == -1 || m_max > 1;
244 }
245
246 /**
247 * @returns @c true if this Cardinality allows no items. For example, for
248 * zeroOrOne() is @c true returned, while for oneOrMore() is @c false returned.
249 */
250 inline bool allowsEmpty() const
251 {
252 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
253 return m_min == 0;
254 }
255
256 /**
257 * Maps directly to Formal Semantics' @c aggregate_quantifier function.
258 *
259 * @returns zeroOrOne() if this Cardinality allows the empty sequence, otherwise exactlyOne()
260 * @see <a href="http://www.w3.org/TR/xquery-semantics/#jd_quantifier">XQuery 1.0 and
261 * XPath 2.0 Formal Semantics, The function quantifier()</a>
262 */
263 inline Cardinality toWithoutMany() const
264 {
265 return m_min == 0 ? Cardinality(0, 1)
266 : Cardinality(1, 1);
267 }
268
269 /**
270 * Determines whether all the possible outcomes represented by @p other,
271 * will always match this Cardinality. For example, if this Cardinality
272 * is oneOrMore(), @c true will be returned if @p other is exactlyOne(), but
273 * false if @p other is zeroOrOne().
274 */
275 inline bool isMatch(const Cardinality &other) const
276 {
277 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
278 if(other.m_min < m_min)
279 return false;
280 else
281 { /* Ok, we now know the minimum will always be ok. */
282 if(m_max == -1)
283 return true; /* We allow infinite, so anything can match. */
284 else if(other.m_max == -1)
285 return false; /* other allows infinity, while we don't. */
286 else
287 return m_max >= other.m_max;
288 }
289 }
290
291 /**
292 * Determines whether at least one of the possible outcomes represented by @p other,
293 * can match this Cardinality. For example, if this Cardinality
294 * is oneOrMore(), @c true will be returned if @p other is exactlyOne() or zeroOrOne().
295 */
296 inline bool canMatch(const Cardinality &other) const
297 {
298 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
299 if(m_max == -1)
300 return m_min <= other.m_min || other.m_max >= m_min || other.m_max == -1;
301 else
302 {
303 if(m_max == other.m_min)
304 return true;
305 else if(m_max > other.m_min)
306 return other.m_max >= m_min || other.m_max == -1;
307 else /* m_max < other.m_min */
308 return false;
309 }
310 }
311
312 /**
313 * @returns @c true if this Cardinality is empty, the <tt>empty-sequence()</tt>, otherwise
314 * @c false.
315 */
316 inline bool isEmpty() const
317 {
318 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
319 return m_min == 0 && m_max == 0;
320 }
321
322 /**
323 * @returns @c true if this Cardinality is zero-or-one, <tt>?</tt>, otherwise
324 * @c false.
325 */
326 inline bool isZeroOrOne() const
327 {
328 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
329 return m_min == 0 && m_max == 1;
330 }
331
332 /**
333 * @returns @c true if this Cardinality only allows exactly one item, otherwise
334 * @c false.
335 */
336 inline bool isExactlyOne() const
337 {
338 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
339 return m_min == 1 && m_max == 1;
340 }
341
342 /**
343 * @returns @c true if this Cardinality only allows one or more items, otherwise
344 * @c false.
345 */
346 inline bool isOneOrMore() const
347 {
348 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
349 return m_min > 0 && (m_max == -1 || m_max >= 1);
350 }
351
352 /**
353 * Determines whether this Cardinality only allows a specific length. For example,
354 * empty() and exactlyOne() are exact, but oneOrMore() or zeroOrOne() is not.
355 */
356 inline bool isExact() const
357 {
358 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
359 return m_min == m_max;
360 }
361
362 /**
363 * Returns a string representation of this Cardinality.
364 *
365 * If @p explain is ExcludeExplanation the kleene operator is returned. For example, if
366 * the Cardinality is zeroOrOne, is "?" returned.
367 *
368 * If explain is IncludeExplanation a string more suited for human interpretation is returned,
369 * which is appropriately translated. For example, when the locale is English and
370 * this Cardinality being zeroOrOne, then is 'zero or one("?")' returned.
371 *
372 * Typically, passing ExcludeExplanation is useful when generating function
373 * signatures and the like, while passing IncludeExplanation
374 * is suitable appropriate when generating error messages.
375 *
376 * @returns a string representation for this Cardinality.
377 */
378 QString displayName(const CustomizeDisplayName explanation) const;
379
380 /**
381 * Computes the Cardinality that comprises this Cardinality as well as @p other. For
382 * example, if this Cardinality is zeroOrOne() and @p other is oneOrMore(), then
383 * is zeroOrMore() returned.
384 */
385 inline Cardinality operator|(const Cardinality &other) const
386 {
387 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
388 if(m_max == -1 || other.m_max == -1)
389 return Cardinality(qMin(a: m_min, b: other.m_min), -1);
390 else
391 return Cardinality(qMin(a: m_min, b: other.m_min), qMax(a: m_max, b: other.m_max));
392 }
393
394 /**
395 * Behaves as operator|() but assigns the result to this Cardinality.
396 */
397 inline Cardinality &operator|=(const Cardinality &other)
398 {
399 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
400 m_min = qMin(a: m_min, b: other.m_min);
401
402 if(m_max == -1)
403 return *this;
404 else if(other.m_max == -1)
405 m_max = -1;
406 else
407 m_max = qMax(a: m_max, b: other.m_max);
408
409 return *this;
410 }
411
412 /**
413 * Computes the intersection of this Cardinality and @p other, and returns
414 * the result. For example, the intersection between zeroOrOne() and
415 * oneOrMore() is exactlyOne().
416 *
417 * If no intersection exists, such as the case in empty() and exactlyOne(), then
418 * is a default constructed Cardinality is returned. That is, an invalid Cardinality.
419 */
420 inline Cardinality operator&(const Cardinality &other) const
421 {
422 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
423
424 if(m_max < other.m_min) /* No intersection. */
425 return empty();
426
427 const Count min = qMax(a: m_min, b: other.m_min);
428
429 if(m_max == -1)
430 return Cardinality(min, other.m_max);
431 else if(other.m_max == -1)
432 return Cardinality(min, m_max);
433 else
434 return Cardinality(min, qMin(a: m_max, b: other.m_max));
435 }
436
437 /**
438 * Adds two cardinalities, as if two sequences represented by them were concatenated.
439 * For example, if this Cardinality allows the range 6-8 and @p other allows
440 * 0-1, the return Cardinality has a range of 6-9.
441 *
442 * @returns the result of the comparison.
443 */
444 inline Cardinality operator+(const Cardinality &other) const
445 {
446 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
447 if(m_max == -1 || other.m_max == -1)
448 return Cardinality(m_min + other.m_min, -1);
449 else
450 return Cardinality(m_min + other.m_min, m_max + other.m_max);
451 }
452
453 /**
454 * Behaves as operator+() but assigns the result to this Cardinality.
455 */
456 inline Cardinality &operator+=(const Cardinality &other)
457 {
458 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO,
459 "One of the cardinalities are invalid.");
460 m_min += other.m_min;
461
462 if(m_max == -1)
463 return *this;
464 if(other.m_max == -1)
465 m_max = -1;
466 else
467 m_max += other.m_max;
468
469 return *this;
470 }
471
472 /**
473 * Multiplies this Cardinality with @p other, and returns the result. The minimum and maximum
474 * of each Cardinality is multiplied such that the new Cardinality represents the possible
475 * range of the two sequences being multiplied, length-wise. For example the Cardinality
476 * 4, 5 multiplied with 2, 3 becomes 8, 15.
477 */
478 inline Cardinality operator*(const Cardinality &other) const
479 {
480 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO,
481 "One of the cardinalities are invalid.");
482 if(m_max == -1 || other.m_max == -1)
483 return Cardinality(m_min * other.m_min, -1);
484 else
485 return Cardinality(m_min * other.m_min, m_max * other.m_max);
486 }
487
488 /**
489 * A traditional assignment operator. Behaves as assignment
490 * operators typically do.
491 */
492 inline Cardinality &operator=(const Cardinality &other)
493 {
494 Q_ASSERT_X(this != &other, Q_FUNC_INFO, "Assigning to oneself makes no sense.");
495 m_min = other.m_min;
496 m_max = other.m_max;
497 return *this;
498 }
499
500 /**
501 * Determines whether @p other is equal to this Cardinality.
502 *
503 * For example, empty() is equal to empty(), but zeroOrOne()
504 * is not equal to exactlyOne().
505 *
506 * @returns @c true if @p other is equal to this Cardinality.
507 */
508 inline bool operator==(const Cardinality &other) const
509 {
510 return m_min == other.m_min &&
511 m_max == other.m_max;
512 }
513
514 /**
515 * @returns the opposite of operator==()
516 */
517 inline bool operator!=(const Cardinality &other) const
518 {
519 return m_min != other.m_min ||
520 m_max != other.m_max;
521 }
522
523 private:
524 inline Cardinality(const Count min, const Count max) : m_min(min),
525 m_max(max)
526 {
527 }
528
529 Count m_min;
530 Count m_max;
531 };
532}
533
534Q_DECLARE_TYPEINFO(QPatternist::Cardinality, Q_MOVABLE_TYPE);
535
536QT_END_NAMESPACE
537
538#endif
539

source code of qtxmlpatterns/src/xmlpatterns/type/qcardinality_p.h