1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
46 // This file is not part of the Qt API. It exists purely as an
47 // implementation detail. This header file may change from version to
48 // version without notice, or even be removed.
52 #ifndef Patternist_Cardinality_H
53 #define Patternist_Cardinality_H
55 #include <QtCore/QtGlobal>
66 * @short Represents a cardinality, a possible , often represented by occurrence indicators.
68 * As opposed to the cardinality concept in the XQuery/XPath specifications, which
69 * only allows cardinalities to be expressed with kleene operators, this representation
70 * allows ranges. For example, the cardinality 10-11, describes a sequence containing
71 * ten or eleven items, inclusive.
73 * @ingroup Patternist_types
76 * @see <a href="http://www.w3.org/TR/xpath20/#prod-xpath-SequenceType">XML Path Language
77 * (XPath) 2.0, The EBNF grammar for SequenceType</a>
78 * @author Frans Englich <frans.englich@nokia.com>
84 * This integer type, is what Cardinality uses for representing its ranges.
89 * Used with displayName(), and specifies
90 * how a display name for a Cardinality should be.
92 enum CustomizeDisplayName
95 * Includes a describing string in the return value of displayName().
97 IncludeExplanation = 1,
100 * Excludes a describing string in the return value of displayName().
106 * A traditional copy constructor. This Cardinality becomes identical
109 inline Cardinality(const Cardinality &other) : m_min(other.m_min),
115 * This default constructor constructs an invalid Cardinality. Using
116 * its operators and members yields undefined results. A value must
117 * first be assigned to it by creating a Cardinality with fromRange(), fromCount(),
118 * or one of the predefined cardinalities such as empty() or oneOrMore().
120 inline Cardinality() : m_min(-1), m_max(0)
125 * The cardinality assigned to the exprssion <tt>()</tt>, formally speaking. The
126 * cardinality part of <tt>empty-sequence()</tt>.
128 static inline Cardinality empty()
130 return Cardinality(0, 0);
134 * The cardinality implicitly specified in for example the sequence type
135 * <tt>item()</tt>. It has no kleene operator.
137 static inline Cardinality exactlyOne()
139 return Cardinality(1, 1);
143 * Allows both no item, as in empty(), and exactlyOne(). Represented
144 * by the kleene operator <tt>?</tt>.
146 static inline Cardinality zeroOrOne()
148 return Cardinality(0, 1);
152 * Allows any amount. This is therefore the widest, an unconstrained
153 * cardinality. Represented by the kleene operator <tt>*</tt>.
155 static inline Cardinality zeroOrMore()
157 return Cardinality(0, -1);
161 * Allows one or more. Represented by the kleene operator <tt>+</tt>.
163 static inline Cardinality oneOrMore()
165 return Cardinality(1, -1);
169 * Allows one or more. This cardinality has no kleene operator and is used
170 * by the implementation in order to be able to know when a cardinality
171 * that at amximum allows one, is exceeded.
173 static inline Cardinality twoOrMore()
175 return Cardinality(2, -1);
179 * Determines the cardinality from the count of a sequence. For example, if
180 * @p count is 11, a Cardinality is returned that allows at minimum and maximum
183 * @p count must be positive or zero. If it is not, the result is undefined.
184 * When debugging is enabled, a Q_ASSERT() macro ensures this.
186 static inline Cardinality fromCount(const Count count)
188 Q_ASSERT_X(count > -1, Q_FUNC_INFO,
189 "A count smaller than 0 makes no sense.");
190 return Cardinality(count, count);
194 * Creates a Cardinality that allows @p minimum and @p maximum
197 * If @p maximum is -1, it signals infinity.
199 * If you before hand knows that a predefined Cardinality is needed,
200 * remember to use one of the factory functions empty(), zeroOrOne(),
201 * exactlyOne(), oneOrMore() or zeroOrMore(), since they improves
202 * readability, are safer, and slightly faster.
204 static inline Cardinality fromRange(const Count minimum, const Count maximum)
206 Q_ASSERT_X(minimum > -1, Q_FUNC_INFO,
207 "minimum should never be less than 0.");
208 Q_ASSERT_X(minimum <= maximum || maximum == -1, Q_FUNC_INFO,
209 "minimum cannot be larger than maximum.");
211 return Cardinality(minimum, maximum);
214 static inline Cardinality fromExact(const Count count)
216 Q_ASSERT(count >= 0);
217 return Cardinality(count, count);
221 * @returns the minimum amount of items this Cardinality allows. For example,
222 * for zeroOrOne() is 0 returned.
224 inline Count minimum() const
226 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
231 * @returns the maximum amount of items this Cardinality allows. For example,
232 * for zeroOrOne() is 1 returned.
234 inline Count maximum() const
236 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
241 * @returns @c true if this Cardinality allows one or more items. For example, for
242 * zeroOrOne() is @c false returned, while for zeroOrMore() is @c true returned.
244 inline bool allowsMany() const
246 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
247 return m_max == -1 || m_max > 1;
251 * @returns @c true if this Cardinality allows no items. For example, for
252 * zeroOrOne() is @c true returned, while for oneOrMore() is @c false returned.
254 inline bool allowsEmpty() const
256 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
261 * Maps directly to Formal Semantics' @c aggregate_quantifier function.
263 * @returns zeroOrOne() if this Cardinality allows the empty sequence, otherwise exactlyOne()
264 * @see <a href="http://www.w3.org/TR/xquery-semantics/#jd_quantifier">XQuery 1.0 and
265 * XPath 2.0 Formal Semantics, The function quantifier()</a>
267 inline Cardinality toWithoutMany() const
269 return m_min == 0 ? Cardinality(0, 1)
274 * Determines whether all the possible outcomes represented by @p other,
275 * will always match this Cardinality. For example, if this Cardinality
276 * is oneOrMore(), @c true will be returned if @p other is exactlyOne(), but
277 * false if @p other is zeroOrOne().
279 inline bool isMatch(const Cardinality &other) const
281 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
282 if(other.m_min < m_min)
285 { /* Ok, we now know the minimum will always be ok. */
287 return true; /* We allow infinite, so anything can match. */
288 else if(other.m_max == -1)
289 return false; /* other allows infinity, while we don't. */
291 return m_max >= other.m_max;
296 * Determines whether at least one of the possible outcomes represented by @p other,
297 * can match this Cardinality. For example, if this Cardinality
298 * is oneOrMore(), @c true will be returned if @p other is exactlyOne() or zeroOrOne().
300 inline bool canMatch(const Cardinality &other) const
302 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
304 return m_min <= other.m_min || other.m_max >= m_min || other.m_max == -1;
307 if(m_max == other.m_min)
309 else if(m_max > other.m_min)
310 return other.m_max >= m_min || other.m_max == -1;
311 else /* m_max < other.m_min */
317 * @returns @c true if this Cardinality is empty, the <tt>empty-sequence()</tt>, otherwise
320 inline bool isEmpty() const
322 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
323 return m_min == 0 && m_max == 0;
327 * @returns @c true if this Cardinality is zero-or-one, <tt>?</tt>, otherwise
330 inline bool isZeroOrOne() const
332 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
333 return m_min == 0 && m_max == 1;
337 * @returns @c true if this Cardinality only allows exactly one item, otherwise
340 inline bool isExactlyOne() const
342 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
343 return m_min == 1 && m_max == 1;
347 * @returns @c true if this Cardinality only allows one or more items, otherwise
350 inline bool isOneOrMore() const
352 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
353 return m_min > 0 && (m_max == -1 || m_max >= 1);
357 * Determines whether this Cardinality only allows a specific length. For example,
358 * empty() and exactlyOne() are exact, but oneOrMore() or zeroOrOne() is not.
360 inline bool isExact() const
362 Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
363 return m_min == m_max;
367 * Returns a string representation of this Cardinality.
369 * If @p explain is ExcludeExplanation the kleene operator is returned. For example, if
370 * the Cardinality is zeroOrOne, is "?" returned.
372 * If explain is IncludeExplanation a string more suited for human interpretation is returned,
373 * which is appropriately translated. For example, when the locale is English and
374 * this Cardinality being zeroOrOne, then is 'zero or one("?")' returned.
376 * Typically, passing ExcludeExplanation is useful when generating function
377 * signatures and the like, while passing IncludeExplanation
378 * is suitable appropriate when generating error messages.
380 * @returns a string representation for this Cardinality.
382 QString displayName(const CustomizeDisplayName explanation) const;
385 * Computes the Cardinality that comprises this Cardinality as well as @p other. For
386 * example, if this Cardinality is zeroOrOne() and @p other is oneOrMore(), then
387 * is zeroOrMore() returned.
389 inline Cardinality operator|(const Cardinality &other) const
391 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
392 if(m_max == -1 || other.m_max == -1)
393 return Cardinality(qMin(m_min, other.m_min), -1);
395 return Cardinality(qMin(m_min, other.m_min), qMax(m_max, other.m_max));
399 * Behaves as operator|() but assigns the result to this Cardinality.
401 inline Cardinality &operator|=(const Cardinality &other)
403 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
404 m_min = qMin(m_min, other.m_min);
408 else if(other.m_max == -1)
411 m_max = qMax(m_max, other.m_max);
417 * Computes the intersection of this Cardinality and @p other, and returns
418 * the result. For example, the intersection between zeroOrOne() and
419 * oneOrMore() is exactlyOne().
421 * If no intersection exists, such as the case in empty() and exactlyOne(), then
422 * is a default constructed Cardinality is returned. That is, an invalid Cardinality.
424 inline Cardinality operator&(const Cardinality &other) const
426 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
428 if(m_max < other.m_min) /* No intersection. */
431 const Count min = qMax(m_min, other.m_min);
434 return Cardinality(min, other.m_max);
435 else if(other.m_max == -1)
436 return Cardinality(min, m_max);
438 return Cardinality(min, qMin(m_max, other.m_max));
442 * Adds two cardinalities, as if two sequences represented by them were concatenated.
443 * For example, if this Cardinality allows the range 6-8 and @p other allows
444 * 0-1, the return Cardinality has a range of 6-9.
446 * @returns the result of the comparison.
448 inline Cardinality operator+(const Cardinality &other) const
450 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
451 if(m_max == -1 || other.m_max == -1)
452 return Cardinality(m_min + other.m_min, -1);
454 return Cardinality(m_min + other.m_min, m_max + other.m_max);
458 * Behaves as operator+() but assigns the result to this Cardinality.
460 inline Cardinality &operator+=(const Cardinality &other)
462 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO,
463 "One of the cardinalities are invalid.");
464 m_min += other.m_min;
468 if(other.m_max == -1)
471 m_max += other.m_max;
477 * Multiplies this Cardinality with @p other, and returns the result. The minimum and maximum
478 * of each Cardinality is multiplied such that the new Cardinality represents the possible
479 * range of the two sequences being multiplied, length-wise. For example the Cardinality
480 * 4, 5 multiplied with 2, 3 becomes 8, 15.
482 inline Cardinality operator*(const Cardinality &other) const
484 Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO,
485 "One of the cardinalities are invalid.");
486 if(m_max == -1 || other.m_max == -1)
487 return Cardinality(m_min * other.m_min, -1);
489 return Cardinality(m_min * other.m_min, m_max * other.m_max);
493 * A traditional assignment operator. Behaves as assignment
494 * operators typically do.
496 inline Cardinality &operator=(const Cardinality &other)
498 Q_ASSERT_X(this != &other, Q_FUNC_INFO, "Assigning to oneself makes no sense.");
505 * Determines whether @p other is equal to this Cardinality.
507 * For example, empty() is equal to empty(), but zeroOrOne()
508 * is not equal to exactlyOne().
510 * @returns @c true if @p other is equal to this Cardinality.
512 inline bool operator==(const Cardinality &other) const
514 return m_min == other.m_min &&
515 m_max == other.m_max;
519 * @returns the opposite of operator==()
521 inline bool operator!=(const Cardinality &other) const
523 return m_min != other.m_min ||
524 m_max != other.m_max;
528 inline Cardinality(const Count min, const Count max) : m_min(min),
538 Q_DECLARE_TYPEINFO(QPatternist::Cardinality, Q_MOVABLE_TYPE);