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 55 QT_BEGIN_NAMESPACE 56 57 class QString; 58 59 namespace 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 */ Cardinality(const Cardinality & other)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 */ Cardinality()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 */ empty()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 */ exactlyOne()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 */ zeroOrOne()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 */ zeroOrMore()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 */ oneOrMore()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 */ twoOrMore()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 */ fromCount(const Count count)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 */ fromRange(const Count minimum,const Count maximum)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 fromExact(const Count count)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 */ minimum()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 */ maximum()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 */ allowsMany()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 */ allowsEmpty()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 */ toWithoutMany()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 */ isMatch(const Cardinality & other)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 */ canMatch(const Cardinality & other)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 */ isEmpty()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 */ isZeroOrOne()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 */ isExactlyOne()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 */ isOneOrMore()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 */ isExact()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(m_min, other.m_min), -1); 390 else 391 return Cardinality(qMin(m_min, other.m_min), qMax(m_max, 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(m_min, 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(m_max, 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(m_min, 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(m_max, 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: Cardinality(const Count min,const Count max)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 534 Q_DECLARE_TYPEINFO(QPatternist::Cardinality, Q_MOVABLE_TYPE); 535 536 QT_END_NAMESPACE 537 538 #endif 539