1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
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_ItemType_H
53 #define Patternist_ItemType_H
55 #include <QSharedData>
57 #include <QtXmlPatterns/private/qnamepool_p.h>
63 template<typename T> class QList;
70 * @short Base class for the XPath Data Model's type hierarchy.
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.
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.
79 * @ingroup Patternist_types
80 * @author Frans Englich <frans.englich@nokia.com>
82 class ItemType : public virtual QSharedData
86 * A smart pointer wrapping ItemType instances.
88 typedef QExplicitlySharedDataPointer<ItemType> Ptr;
90 * A list of ItemType instances, each wrapped in a smart pointer.
92 typedef QList<ItemType::Ptr> List;
103 * Determines whether this ItemType is equal to @p other.
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.
110 * However, it's overridden in some cases, such as for name tests, where
111 * it's not guaranteed that there exists two types.
113 * @returns @c true if this ItemType is equal to @p other, otherwise @c false.
115 virtual bool operator==(const ItemType &other) const;
118 * @returns the result of operator==() negated.
120 inline bool operator!=(const ItemType &other) const;
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".
128 virtual QString displayName(const NamePool::Ptr &np) const = 0;
131 * @param item the item that is to be matched. This is guaranteed by the caller
132 * to never be @c null.
134 virtual bool itemMatches(const Item &item) const = 0;
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.
140 * For instance this statements evaluates to @c true:
143 * BuiltinTypes::xsAnyAtomicType->xdtTypeMatches(BuiltinTypes::xsString);
146 * but this evaluates to @c false:
149 * BuiltinTypes::attribute->xdtTypeMatches(BuiltinTypes::node);
152 * @param other the other ItemType that is to be matched. This is guaranteed by the caller
153 * to never be @c null.
155 virtual bool xdtTypeMatches(const ItemType::Ptr &other) const = 0;
157 virtual bool isNodeType() const = 0;
158 virtual bool isAtomicType() const = 0;
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.
165 * @see SchemaType::wxsSuperType()
166 * @returns the type's super type.
168 virtual ItemType::Ptr xdtSuperType() const = 0;
171 * @todo docs mention union, give if-expression example.
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.
178 * This function can be seen as the type function prime(Type), defined in Formal Semantics.
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'
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>
189 virtual const ItemType &operator|(const ItemType &other) const;
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.
197 * If the type cannot be atomized, it returns @c null.
199 * This function is also defined on SchemaType, because some schema types can also be
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.
210 virtual ItemType::Ptr atomizedType() const = 0;
213 * @returns always Other
215 virtual Category itemTypeCategory() const;
220 ClassNamespaceNameTest,
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.
230 virtual InstanceOf instanceOf() const;
237 Q_DISABLE_COPY(ItemType)
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.
247 * @see ItemType::operator|()
248 * @see operator|=(ItemType::Ptr &, const ItemType::Ptr &)
250 inline ItemType::Ptr operator|(const ItemType::Ptr &op1,
251 const ItemType::Ptr &op2)
253 return ItemType::Ptr(const_cast<ItemType *>(&(*op1 | *op2)));
256 bool ItemType::operator!=(const ItemType &other) const
258 return this != &other;
262 * @short Computes the union type of @p op1 and @p op2, and assigns it to @p op1.
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.
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
273 inline void operator|=(ItemType::Ptr &op1, const ItemType::Ptr &op2)
280 Q_DECLARE_TYPEINFO(QPatternist::ItemType::Ptr, Q_MOVABLE_TYPE);