src/xmlpatterns/type/qcardinality_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   8 **
   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.
  17 **
  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.
  21 **
  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.
  29 **
  30 ** Other Usage
  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.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 //
  43 //  W A R N I N G
  44 //  -------------
  45 //
  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.
  49 //
  50 // We mean it.
  51
  52 #ifndef Patternist_Cardinality_H
  53 #define Patternist_Cardinality_H
  54
  55 #include <QtCore/QtGlobal>
  56
  57 QT_BEGIN_HEADER
  58
  59 QT_BEGIN_NAMESPACE
  60
  61 class QString;
  62
  63 namespace QPatternist
  64 {
  65     /**
  66      * @short Represents a cardinality, a possible , often represented by occurrence indicators.
  67      *
  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.
  72      *
  73      * @ingroup Patternist_types
  74      * @see ItemType
  75      * @see SequenceType
  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>
  79      */
  80     class Cardinality
  81     {
  82     public:
  83         /**
  84          * This integer type, is what Cardinality uses for representing its ranges.
  85          */
  86         typedef qint32 Count;
  87
  88         /**
  89          * Used with displayName(), and specifies
  90          * how a display name for a Cardinality should be.
  91          */
  92         enum CustomizeDisplayName
  93         {
  94             /**
  95              * Includes a describing string in the return value of displayName().
  96              */
  97             IncludeExplanation  = 1,
  98
  99             /**
 100              * Excludes a describing string in the return value of displayName().
 101              */
 102             ExcludeExplanation
 103         };
 104
 105         /**
 106          * A traditional copy constructor. This Cardinality becomes identical
 107          * to @p other.
 108          */
 109         inline Cardinality(const Cardinality &other) : m_min(other.m_min),
 110                                                        m_max(other.m_max)
 111         {
 112         }
 113
 114         /**
 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().
 119          */
 120         inline Cardinality() : m_min(-1), m_max(0)
 121         {
 122         }
 123
 124         /**
 125          * The cardinality assigned to the exprssion <tt>()</tt>, formally speaking. The
 126          * cardinality part of <tt>empty-sequence()</tt>.
 127          */
 128         static inline Cardinality empty()
 129         {
 130             return Cardinality(0, 0);
 131         }
 132
 133         /**
 134          * The cardinality implicitly specified in for example the sequence type
 135          * <tt>item()</tt>. It has no kleene operator.
 136          */
 137         static inline Cardinality exactlyOne()
 138         {
 139             return Cardinality(1, 1);
 140         }
 141
 142         /**
 143          * Allows both no item, as in empty(), and exactlyOne(). Represented
 144          * by the kleene operator <tt>?</tt>.
 145          */
 146         static inline Cardinality zeroOrOne()
 147         {
 148             return Cardinality(0, 1);
 149         }
 150
 151         /**
 152          * Allows any amount. This is therefore the widest, an unconstrained
 153          * cardinality. Represented by the kleene operator <tt>*</tt>.
 154          */
 155         static inline Cardinality zeroOrMore()
 156         {
 157             return Cardinality(0, -1);
 158         }
 159
 160         /**
 161          * Allows one or more. Represented by the kleene operator <tt>+</tt>.
 162          */
 163         static inline Cardinality oneOrMore()
 164         {
 165             return Cardinality(1, -1);
 166         }
 167
 168         /**
 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.
 172          */
 173         static inline Cardinality twoOrMore()
 174         {
 175             return Cardinality(2, -1);
 176         }
 177
 178        /**
 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
 181          * 11 items.
 182          *
 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.
 185          */
 186         static inline Cardinality fromCount(const Count count)
 187         {
 188             Q_ASSERT_X(count > -1, Q_FUNC_INFO,
 189                        "A count smaller than 0 makes no sense.");
 190             return Cardinality(count, count);
 191         }
 192
 193         /**
 194          * Creates a Cardinality that allows @p minimum and @p maximum
 195          * items, inclusive.
 196          *
 197          * If @p maximum is -1, it signals infinity.
 198          *
 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.
 203          */
 204         static inline Cardinality fromRange(const Count minimum, const Count maximum)
 205         {
 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.");
 210
 211             return Cardinality(minimum, maximum);
 212         }
 213
 214         static inline Cardinality fromExact(const Count count)
 215         {
 216             Q_ASSERT(count >= 0);
 217             return Cardinality(count, count);
 218         }
 219
 220         /**
 221          * @returns the minimum amount of items this Cardinality allows. For example,
 222          * for zeroOrOne() is 0 returned.
 223          */
 224         inline Count minimum() const
 225         {
 226             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
 227             return m_min;
 228         }
 229
 230         /**
 231          * @returns the maximum amount of items this Cardinality allows. For example,
 232          * for zeroOrOne() is 1 returned.
 233          */
 234         inline Count maximum() const
 235         {
 236             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
 237             return m_max;
 238         }
 239
 240         /**
 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.
 243          */
 244         inline bool allowsMany() const
 245         {
 246             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
 247             return m_max == -1 || m_max > 1;
 248         }
 249
 250         /**
 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.
 253          */
 254         inline bool allowsEmpty() const
 255         {
 256             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality are invalid.");
 257             return m_min == 0;
 258         }
 259
 260         /**
 261          * Maps directly to Formal Semantics' @c aggregate_quantifier function.
 262          *
 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>
 266          */
 267         inline Cardinality toWithoutMany() const
 268         {
 269             return m_min == 0 ? Cardinality(0, 1)
 270                               : Cardinality(1, 1);
 271         }
 272
 273         /**
 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().
 278          */
 279         inline bool isMatch(const Cardinality &other) const
 280         {
 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)
 283                 return false;
 284             else
 285             { /* Ok, we now know the minimum will always be ok. */
 286                 if(m_max == -1)
 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. */
 290                 else
 291                    return m_max >= other.m_max;
 292             }
 293         }
 294
 295         /**
 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().
 299          */
 300         inline bool canMatch(const Cardinality &other) const
 301         {
 302             Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
 303             if(m_max == -1)
 304                 return m_min <= other.m_min || other.m_max >= m_min || other.m_max == -1;
 305             else
 306             {
 307                 if(m_max == other.m_min)
 308                     return true;
 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 */
 312                     return false;
 313             }
 314         }
 315
 316         /**
 317          * @returns @c true if this Cardinality is empty, the <tt>empty-sequence()</tt>, otherwise
 318          * @c false.
 319          */
 320         inline bool isEmpty() const
 321         {
 322             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
 323             return m_min == 0 && m_max == 0;
 324         }
 325
 326         /**
 327          * @returns @c true if this Cardinality is zero-or-one, <tt>?</tt>, otherwise
 328          * @c false.
 329          */
 330         inline bool isZeroOrOne() const
 331         {
 332             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
 333             return m_min == 0 && m_max == 1;
 334         }
 335
 336         /**
 337          * @returns @c true if this Cardinality only allows exactly one item, otherwise
 338          * @c false.
 339          */
 340         inline bool isExactlyOne() const
 341         {
 342             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
 343             return m_min == 1 && m_max == 1;
 344         }
 345
 346         /**
 347          * @returns @c true if this Cardinality only allows one or more items, otherwise
 348          * @c false.
 349          */
 350         inline bool isOneOrMore() const
 351         {
 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);
 354         }
 355
 356         /**
 357          * Determines whether this Cardinality only allows a specific length. For example,
 358          * empty() and exactlyOne() are exact, but oneOrMore() or zeroOrOne() is not.
 359          */
 360         inline bool isExact() const
 361         {
 362             Q_ASSERT_X(m_min != -1, Q_FUNC_INFO, "The cardinality is invalid.");
 363             return m_min == m_max;
 364         }
 365
 366         /**
 367          * Returns a string representation of this Cardinality.
 368          *
 369          * If @p explain is ExcludeExplanation the kleene operator is returned. For example, if
 370          * the Cardinality is zeroOrOne, is "?" returned.
 371          *
 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.
 375          *
 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.
 379          *
 380          * @returns a string representation for this Cardinality.
 381          */
 382         QString displayName(const CustomizeDisplayName explanation) const;
 383
 384         /**
 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.
 388          */
 389         inline Cardinality operator|(const Cardinality &other) const
 390         {
 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);
 394             else
 395                 return Cardinality(qMin(m_min, other.m_min), qMax(m_max, other.m_max));
 396         }
 397
 398         /**
 399          * Behaves as operator|() but assigns the result to this Cardinality.
 400          */
 401         inline Cardinality &operator|=(const Cardinality &other)
 402         {
 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);
 405
 406             if(m_max == -1)
 407                 return *this;
 408             else if(other.m_max == -1)
 409                 m_max = -1;
 410             else
 411                 m_max = qMax(m_max, other.m_max);
 412
 413             return *this;
 414         }
 415
 416         /**
 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().
 420          *
 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.
 423          */
 424         inline Cardinality operator&(const Cardinality &other) const
 425         {
 426             Q_ASSERT_X(m_min != -1 && other.m_min != -1, Q_FUNC_INFO, "One of the cardinalities are invalid.");
 427
 428             if(m_max < other.m_min) /* No intersection. */
 429                 return empty();
 430
 431             const Count min = qMax(m_min, other.m_min);
 432
 433             if(m_max == -1)
 434                 return Cardinality(min, other.m_max);
 435             else if(other.m_max == -1)
 436                 return Cardinality(min, m_max);
 437             else
 438                 return Cardinality(min, qMin(m_max, other.m_max));
 439         }
 440
 441         /**
 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.
 445          *
 446          * @returns the result of the comparison.
 447          */
 448         inline Cardinality operator+(const Cardinality &other) const
 449         {
 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);
 453             else
 454                 return Cardinality(m_min + other.m_min, m_max + other.m_max);
 455         }
 456
 457         /**
 458          * Behaves as operator+() but assigns the result to this Cardinality.
 459          */
 460         inline Cardinality &operator+=(const Cardinality &other)
 461         {
 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;
 465
 466             if(m_max == -1)
 467                 return *this;
 468             if(other.m_max == -1)
 469                 m_max = -1;
 470             else
 471                 m_max += other.m_max;
 472
 473             return *this;
 474         }
 475
 476         /**
 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.
 481          */
 482         inline Cardinality operator*(const Cardinality &other) const
 483         {
 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);
 488             else
 489                 return Cardinality(m_min * other.m_min, m_max * other.m_max);
 490         }
 491
 492         /**
 493          * A traditional assignment operator. Behaves as assignment
 494          * operators typically do.
 495          */
 496         inline Cardinality &operator=(const Cardinality &other)
 497         {
 498             Q_ASSERT_X(this != &other, Q_FUNC_INFO, "Assigning to oneself makes no sense.");
 499             m_min = other.m_min;
 500             m_max = other.m_max;
 501             return *this;
 502         }
 503
 504         /**
 505          * Determines whether @p other is equal to this Cardinality.
 506          *
 507          * For example, empty() is equal to empty(), but zeroOrOne()
 508          * is not equal to exactlyOne().
 509          *
 510          * @returns @c true if @p other is equal to this Cardinality.
 511          */
 512         inline bool operator==(const Cardinality &other) const
 513         {
 514             return m_min == other.m_min &&
 515                    m_max == other.m_max;
 516         }
 517
 518         /**
 519          * @returns the opposite of operator==()
 520          */
 521         inline bool operator!=(const Cardinality &other) const
 522         {
 523             return m_min != other.m_min ||
 524                    m_max != other.m_max;
 525         }
 526
 527     private:
 528         inline Cardinality(const Count min, const Count max) : m_min(min),
 529                                                                m_max(max)
 530         {
 531         }
 532
 533         Count m_min;
 534         Count m_max;
 535     };
 536 }
 537
 538 Q_DECLARE_TYPEINFO(QPatternist::Cardinality, Q_MOVABLE_TYPE);
 539
 540 QT_END_NAMESPACE
 541
 542 QT_END_HEADER
 543
 544 #endif