src/xmlpatterns/type/qitemtype_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  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_ItemType_H
  53 #define Patternist_ItemType_H
  54
  55 #include <QSharedData>
  56
  57 #include <QtXmlPatterns/private/qnamepool_p.h>
  58
  59 QT_BEGIN_HEADER
  60
  61 QT_BEGIN_NAMESPACE
  62
  63 template<typename T> class QList;
  64
  65 namespace QPatternist
  66 {
  67     class Item;
  68
  69     /**
  70      * @short Base class for the XPath Data Model's type hierarchy.
  71      *
  72      * It can not be instantiated, but it's possible via ItemType's two subtypes:
  73      * Nodes, represented by QXmlNodeModelIndex, and atom types, represented by AtomicType.
  74      *
  75      * ItemType tries to by its design stay close to the notation used in Formal Semantics.
  76      * The operator|() is a good example, it allow typing code to be written
  77      * similar to how inference rules in the specification are written.
  78      *
  79      * @ingroup Patternist_types
  80      * @author Frans Englich <frans.englich@nokia.com>
  81      */
  82     class ItemType : public virtual QSharedData
  83     {
  84     public:
  85         /**
  86          * A smart pointer wrapping ItemType instances.
  87          */
  88         typedef QExplicitlySharedDataPointer<ItemType> Ptr;
  89         /**
  90          * A list of ItemType instances, each wrapped in a smart pointer.
  91          */
  92         typedef QList<ItemType::Ptr> List;
  93
  94         virtual ~ItemType();
  95
  96         enum Category
  97         {
  98             NodeNameTest = 1,
  99             Other        = 2
 100         };
 101
 102         /**
 103          * Determines whether this ItemType is equal to @p other.
 104          *
 105          * Many types are represented by singleton instances. For example, there
 106          * exists only one instance of IntegerType. This operator==() takes advantage
 107          * of that and uses equalness of object addresses for determining semantic
 108          * equalness. This function is as a result fast.
 109          *
 110          * However, it's overridden in some cases, such as for name tests, where
 111          * it's not guaranteed that there exists two types.
 112          *
 113          * @returns @c true if this ItemType is equal to @p other, otherwise @c false.
 114          */
 115         virtual bool operator==(const ItemType &other) const;
 116
 117         /**
 118          * @returns the result of operator==() negated.
 119          */
 120         inline bool operator!=(const ItemType &other) const;
 121
 122         /**
 123          * @returns a string representing the type. Used for diagnostic purposes. For a
 124          * type whose name is a QName, a lexical representation should be returned
 125          * with the prefix being a conventional one. Examples of a display names
 126          * are "item()" and "xs:nonPositiveInteger".
 127          */
 128         virtual QString displayName(const NamePool::Ptr &np) const = 0;
 129
 130         /**
 131          * @param item the item that is to be matched. This is guaranteed by the caller
 132          * to never be @c null.
 133          */
 134         virtual bool itemMatches(const Item &item) const = 0;
 135
 136         /**
 137          * @short Returns @c true if @p other matches this type. That is, if @p
 138          * other is equal to this type or a subtype of this type.
 139          *
 140          * For instance this statements evaluates to @c true:
 141          *
 142          * @code
 143          * BuiltinTypes::xsAnyAtomicType->xdtTypeMatches(BuiltinTypes::xsString);
 144          * @endcode
 145          *
 146          * but this evaluates to @c false:
 147          *
 148          * @code
 149          * BuiltinTypes::attribute->xdtTypeMatches(BuiltinTypes::node);
 150          * @endcode
 151          *
 152          * @param other the other ItemType that is to be matched. This is guaranteed by the caller
 153          * to never be @c null.
 154          */
 155         virtual bool xdtTypeMatches(const ItemType::Ptr &other) const = 0;
 156
 157         virtual bool isNodeType() const = 0;
 158         virtual bool isAtomicType() const = 0;
 159
 160         /**
 161          * Determines the type's parent type in the XPath Data Model hierarchy. For example,
 162          * for the type xs:anyAtomicType, the super type in the XPath Data Model is item(), not
 163          * xs:anySimpleType. SchemaType::xdtSuperType navigates the schema hierarchy.
 164          *
 165          * @see SchemaType::wxsSuperType()
 166          * @returns the type's super type.
 167          */
 168         virtual ItemType::Ptr xdtSuperType() const = 0;
 169
 170         /**
 171          * @todo docs mention union, give if-expression example.
 172          *
 173          * Determines the super type that is closest to this ItemType and @p other. That is,
 174          * the parent type of them both. For example, for the type xs:integer and xs:string
 175          * the parent type is xs:anyAtomicType. For xs:NOTATION and processing-instruction(), it
 176          * is item(), to name another example.
 177          *
 178          * This function can be seen as the type function prime(Type), defined in Formal Semantics.
 179          *
 180          * This walks the XPath Data Model type hierarchy, not the W3C XML Schema hierarchy.
 181          * @param other the item type 'this' object, should be compared with. Invoking xdtSuperType
 182          * on 'this' object with @p other as argument yields the same result as invoking the
 183          * function on @p other with 'this'
 184          * as argument.
 185          * @returns the parent type of 'this' and @p other
 186          * @see <a href="http://www.w3.org/TR/xquery-semantics/\#jd_prime">XQuery 1.0 and XPath 2.0
 187          * Formal Semantics, Prime Types, type function prime(Type)</a>
 188          */
 189         virtual const ItemType &operator|(const ItemType &other) const;
 190
 191         /**
 192          * Determines the atomic type that the resulting sequence after
 193          * atomization of this node would be an instance of. For example, for document node,
 194          * xs:untypedAtomic is returned. Phrased differently, the returned type is the
 195          * type of the result of the typed-value accessor.
 196          *
 197          * If the type cannot be atomized, it returns @c null.
 198          *
 199          * This function is also defined on SchemaType, because some schema types can also be
 200          * atomized.
 201          *
 202          * @see SchemaType::atomizedType()
 203          * @see <a href="http://www.w3.org/TR/xpath-datamodel/\#dm-typed-value">XQuery 1.0
 204          * and XPath 2.0 Data Model, 5.15 typed-value Accessor</a>
 205          * @see <a href="http://www.w3.org/TR/xquery-semantics/#jd_data">XQuery 1.0
 206          * and XPath 2.0 Formal Semantics, data on auxiliary judgment</a>
 207          * @returns the atomic type that the resulting sequence
 208          * when performing atomization is an instance of.
 209          */
 210         virtual ItemType::Ptr atomizedType() const = 0;
 211
 212         /**
 213          * @returns always Other
 214          */
 215         virtual Category itemTypeCategory() const;
 216
 217         enum InstanceOf
 218         {
 219             ClassLocalNameTest,
 220             ClassNamespaceNameTest,
 221             ClassQNameTest,
 222             ClassOther
 223         };
 224
 225         /**
 226          * Determines what class this ItemType is an instance of. This
 227          * is in needed in some implementations of operator operator==(). By
 228          * default, Other is returned.
 229          */
 230         virtual InstanceOf instanceOf() const;
 231
 232         inline ItemType()
 233         {
 234         }
 235
 236     private:
 237         Q_DISABLE_COPY(ItemType)
 238     };
 239
 240     /**
 241      * This operator exists for making it easier to use the ItemType class, which
 242      * always are wrapped in ItemType::Ptr, by taking care of the dereferencing
 243      * of ItemType::Ptr instances. Semantically, it performs the same as
 244      * ItemType's operator of the same name.
 245      *
 246      * @relates ItemType
 247      * @see ItemType::operator|()
 248      * @see operator|=(ItemType::Ptr &, const ItemType::Ptr &)
 249      */
 250     inline ItemType::Ptr operator|(const ItemType::Ptr &op1,
 251                                    const ItemType::Ptr &op2)
 252     {
 253         return ItemType::Ptr(const_cast<ItemType *>(&(*op1 | *op2)));
 254     }
 255
 256     bool ItemType::operator!=(const ItemType &other) const
 257     {
 258         return this != &other;
 259     }
 260
 261     /**
 262      * @short Computes the union type of @p op1 and @p op2, and assigns it to @p op1.
 263      *
 264      * This operator exists for making it easier to use the ItemType class, which
 265      * always are wrapped in ItemType::Ptr, by taking care of the dereferencing
 266      * of the ItemType::Ptr instances.
 267      *
 268      * @relates ItemType
 269      * @see operator|(const ItemType::Ptr &, const ItemType::Ptr &)
 270      * @param op1 if @c null, @p op2 is returned unchanged
 271      * @param op2 the other operand
 272      */
 273     inline void operator|=(ItemType::Ptr &op1, const ItemType::Ptr &op2)
 274     {
 275         op1 = op1 | op2;
 276     }
 277
 278 }
 279
 280 Q_DECLARE_TYPEINFO(QPatternist::ItemType::Ptr, Q_MOVABLE_TYPE);
 281
 282 QT_END_NAMESPACE
 283
 284 QT_END_HEADER
 285
 286 #endif