1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
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.
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.
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.
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.
40 ****************************************************************************/
43 * QXmlName is conceptually identical to QPatternist::QName. The
44 * difference is that the latter is elegant, powerful and fast.
46 * However, it is too powerful and too open and not at all designed
47 * for being public. QXmlName, in contrast, is only a public marker,
48 * that for instance uses a qint64 instead of qint32, such that we in
49 * the future can use that, if needed.
52 #include "qnamepool_p.h"
54 #include "qxmlnamepool.h"
55 #include "qxpathhelper_p.h"
56 #include "private/qxmlutils_p.h"
62 \brief The QXmlName class represents the name of an XML node, in an efficient, namespace-aware way.
66 \inmodule QtXmlPatterns
67 QXmlName represents the name of an XML node in a way that
68 is both efficient and safe for comparing names. Normally,
69 an XML node represents an XML element or attribute, but
70 QXmlName can also represent the names of other kinds of
71 nodes, e.g., QAbstractXmlReceiver::processingInstruction()
72 and QAbstractXmlReceiver::namespaceBinding().
74 The name of an XML node has three components: The \e {namespace
75 URI}, the \e {local name}, and the \e {prefix}. To see what these
76 refer to in XML, consider the following snippet.
78 \quotefile patternist/mobeyDick.xml
80 For the element named \e book, localName() returns \e book,
81 namespaceUri() returns \e http://example.com/MyDefault,
82 and prefix() returns an empty string. For the element named
83 \e title, localName() returns \e title, namespaceUri() returns
84 \e http://purl.org/dc/elements/1.1, and prefix() returns \e dc.
86 To ensure that operations with QXmlName are efficient, e.g.,
87 copying names and comparing them, each instance of QXmlName is
88 associated with a \l {QXmlNamePool} {name pool}, which must be
89 specified at QXmlName construction time. The three components
90 of the QXmlName, i.e., the namespace URI, the local name, and
91 the prefix, are stored in the name pool mapped to identifiers
92 so they can be shared. For this reason, the only way to create
93 a valid instance of QXmlName is to use the class constructor,
94 where the \l {QXmlNamePool} {name pool}, local name, namespace
95 URI, and prefix must all be specified.
97 Note that QXmlName's default constructor constructs a null
98 instance. It is typically used for allocating unused entries
99 in collections of QXmlName.
101 A side effect of associating each instance of QXmlName with
102 a \l {QXmlNamePool} {name pool} is that each instance of
103 QXmlName is tied to the QXmlNamePool with which it was created.
104 However, the QXmlName class does not keep track of the name pool,
105 so all the accessor functions, e.g., namespaceUri(), prefix(),
106 localName(), and toClarkName() require that the correct name
107 pool be passed to them. Failure to provide the correct name
108 pool to these accessor functions results in undefined behavior.
110 Note that a \l {QXmlNamePool} {name pool} is \e not an XML
111 namespace. One \l {QXmlNamePool} {name pool} can represent
112 instances of QXmlName from different XML namespaces, and the
113 instances of QXmlName from one XML namespace can be distributed
114 over multiple \l {QXmlNamePool} {name pools}.
116 \target Comparing QXmlNames
117 \section1 Comparing QXmlNames
119 To determine what a QXmlName refers to, the \e {namespace URI}
120 and the \e {local name} are used. The \e prefix is not used
121 because the prefix is simply a shorthand name for use in place
122 of the normally much longer namespace URI. Nor is the prefix
123 used in name comparisons. For example, the following two element
124 nodes represent the same element and compare equal.
126 \quotefile patternist/svgDocumentElement.xml
128 \quotefile patternist/xsvgDocumentElement.xml
130 Although the second name has the prefix \e x, the two names compare
131 equal as instances of QXmlName, because the prefix is not used in
134 A local name can never be an empty string, although the prefix and
135 namespace URI can. If the prefix is not empty, the namespace URI
136 cannot be empty. Local names and prefixes must be valid
137 \l {http://www.w3.org/TR/REC-xml-names/#NT-NCName} {NCNames},
138 e.g., \e abc.def or \e abc123.
140 QXmlName represents what is sometimes called an \e {expanded QName},
143 \sa {http://www.w3.org/TR/REC-xml-names/#NT-NCName}{Namespaces in XML 1.0 (Second Edition), [4] NCName}
147 \enum QXmlName::Constant
149 Various constants used in the QPatternist::NamePool and QXmlName.
151 Setting of the mask enums use essentially this:
153 \quotefile code/src_xmlpatterns_api_qxmlname.cpp
155 The masks, such as LocalNameMask, are positive. That is, for the
156 area which the name resides, the bits are set.
160 Constructs a QXmlName instance that inserts \a localName,
161 \a namespaceURI and \a prefix into \a namePool if they aren't
162 already there. The accessor functions namespaceUri(), prefix(),
163 localName(), and toClarkName() must be passed the \a namePool
164 used here, so the \a namePool must remain in scope while the
165 accessor functions might be used. However, two instances can
166 be compared with \e {==} or \e {!=} and copied without the
169 The user guarantees that the string components are valid for a
170 QName. In particular, the local name, and the prefix (if present),
171 must be valid \l {http://www.w3.org/TR/REC-xml-names/#NT-NCName}
172 {NCNames}. The function isNCName() can be used to test validity
173 of these names. The namespace URI should be an absolute URI.
174 QUrl::isRelative() can be used to test whether the namespace URI
175 is relative or absolute. Finally, providing a prefix is not valid
176 when no namespace URI is provided.
178 \a namePool is not copied. Nor is the reference to it retained
179 in this instance. This constructor inserts the three strings
182 QXmlName::QXmlName(QXmlNamePool &namePool,
183 const QString &localName,
184 const QString &namespaceURI,
185 const QString &prefix)
187 Q_ASSERT_X(prefix.isEmpty() || QXmlUtils::isNCName(prefix), Q_FUNC_INFO,
188 "The prefix is invalid, maybe the arguments were mixed up?");
189 Q_ASSERT_X(QXmlUtils::isNCName(localName), Q_FUNC_INFO,
190 "The local name is invalid, maybe the arguments were mixed up?");
192 m_qNameCode = namePool.d->allocateQName(namespaceURI, localName, prefix).code();
196 \typedef QXmlName::Code
199 Stores the \l {QXmlNamePool} {name pool} identifiers for
200 the namespace URI, local name, and prefix.
204 Returns true if this QXmlName is not initialized with a
205 valid combination of \e {namespace URI}, \e {local name},
208 A valid local name is always required. The prefix and
209 namespace URI can be empty, but if the prefix is not empty,
210 the namespace URI must not be empty. Local names and
211 prefixes must be valid
212 \l {http://www.w3.org/TR/REC-xml-names/#NT-NCName} {NCNames},
213 e.g., \e abc.def or \e abc123.
215 bool QXmlName::isNull() const
217 return m_qNameCode == InvalidCode;
221 Constructs an uninitialized QXmlName. To build
222 a valid QXmlName, you normally use the other constructor, which
223 takes a \l {QXmlNamePool} {name pool}, namespace URI, local name,
224 and prefix as parameters. But you can also use this constructor
225 to build a null QXmlName and then assign an existing QXmlName
230 QXmlName::QXmlName() : m_qNameCode(InvalidCode)
235 \fn QXmlName::QXmlName(const NamespaceCode uri,
236 const LocalNameCode ln,
237 const PrefixCode p = 0)
242 \fn QXmlName::hasPrefix() const
245 Returns true if this QXmlName has a non-empty prefix. If this
246 function returns true, hasNamespace() will also return true,
247 because a QXmlName can't have a prefix if it doesn't have a
252 \fn bool QXmlName::hasNamespace() const
255 Returns true if this QXmlName has a non-empty namespace URI.
259 \fn Code QXmlName::code() const
262 Returns the internal code that contains the id codes for the
263 local name, prefix and namespace URI. It is opaque when used
264 outside QXmlName, but it can be useful when one wants to put
265 a QXmlName in a hash, and the prefix is significant.
269 Returns true if this QXmlName is equal to \a other; otherwise false.
270 Two QXmlNames are equal if their namespace URIs are the same \e and
271 their local names are the same. The prefixes are ignored.
273 Note that it is meaningless to compare two instances of QXmlName
274 that were created with different \l {QXmlNamePool} {name pools},
275 but the attempt is not detected and the behavior is undefined.
279 bool QXmlName::operator==(const QXmlName &other) const
281 return (m_qNameCode & ExpandedNameMask) == (other.m_qNameCode & ExpandedNameMask);
285 Returns true if this QXmlName is \e not equal to \a other;
286 otherwise false. Two QXmlNames are equal if their namespace
287 URIs are the same \e and their local names are the same. They
288 are not equal if either their namespace URIs differ or their
289 local names differ. Their prefixes are ignored.
291 Note that it is meaningless to compare two instances of QXmlName
292 that were created with different \l {QXmlNamePool} {name pools},
293 but the attempt is not detected and the behavior is undefined.
297 bool QXmlName::operator!=(const QXmlName &other) const
299 return !operator==(other);
303 \fn bool QXmlName::isLexicallyEqual(const QXmlName &other) const
306 Returns true if this and \a other are lexically equal. Two
307 QXmlNames are lexically equal if their local names are equal
308 \e and their prefixes are equal.
312 \fn uint qHash(const QXmlName &name)
316 Computes a hash key from the local name and the namespace
317 URI in \a name. The prefix in \a name is not used in the computation.
319 uint qHash(const QXmlName &name)
321 return name.m_qNameCode & QXmlName::ExpandedNameMask;
325 Returns the namespace URI.
327 Note that for efficiency, the namespace URI string is not
328 stored in the QXmlName but in the \l {QXmlNamePool} that was
329 passed to the constructor. Hence, that same \a namePool must
330 be passed to this function, so it can be used for looking up
333 QString QXmlName::namespaceUri(const QXmlNamePool &namePool) const
338 return namePool.d->stringForNamespace(namespaceURI());
344 Note that for efficiency, the prefix string is not stored in
345 the QXmlName but in the \l {QXmlNamePool} that was passed to
346 the constructor. Hence, that same \a namePool must be passed
347 to this function, so it can be used for looking up the prefix.
349 QString QXmlName::prefix(const QXmlNamePool &namePool) const
354 return namePool.d->stringForPrefix(prefix());
358 Returns the local name.
360 Note that for efficiency, the local name string is not stored
361 in the QXmlName but in the \l {QXmlNamePool} that was passed to
362 the constructor. Hence, that same \a namePool must be passed
363 to this function, so it can be used for looking up the
366 QString QXmlName::localName(const QXmlNamePool &namePool) const
371 return namePool.d->stringForLocalName(localName());
375 Returns this QXmlName formatted as a Clark Name. For example,
376 if the local name is \c html, the prefix is \c x, and the
377 namespace URI is \c {http://www.w3.org/1999/xhtml/},
378 then the Clark Name returned is:
381 {http://www.w3.org/1999/xhtml/}x:html.
384 If the local name is \e {MyWidget} and the namespace is empty,
385 the Clark Name returned is:
391 Note that for efficiency, the namespace URI, local name, and
392 prefix strings are not stored in the QXmlName but in the
393 \l {QXmlNamePool} that was passed to the constructor. Hence,
394 that same \a namePool must be passed to this function, so it
395 can be used for looking up the three string components.
397 This function can be useful for debugging.
399 \sa {http://www.jclark.com/xml/xmlns.htm}{XML Namespaces, James Clark}, fromClarkName()
401 QString QXmlName::toClarkName(const QXmlNamePool &namePool) const
403 return namePool.d->toClarkName(*this);
407 Assigns \a other to \e this and returns \e this.
409 QXmlName &QXmlName::operator=(const QXmlName &other)
411 m_qNameCode = other.m_qNameCode;
416 Returns true if \a candidate is an \c NCName. An \c NCName
417 is a string that can be used as a name in XML and XQuery,
418 e.g., the prefix or local name in an element or attribute,
419 or the name of a variable.
421 \sa {http://www.w3.org/TR/REC-xml-names/#NT-NCName}{Namespaces in XML 1.0 (Second Edition), [4] NCName}
423 bool QXmlName::isNCName(const QString &candidate)
425 return QXmlUtils::isNCName(candidate);
429 Converts \a clarkName into a QXmlName, inserts into \a namePool, and
432 A clark name is a way to present a full QName with only one string, where
433 the namespace cannot contain braces. Here are a couple of examples:
441 \li The local name \c html, in no namespace
443 \li \c {http://www.w3.org/1999/xhtml}html
444 \li The local name \c html, in the XHTML namespace
446 \li \c {http://www.w3.org/1999/xhtml}my:html
447 \li The local name \c html, in the XHTML namespace, with the prefix \c my
450 If the namespace contains braces, the returned value is either invalid or
451 has undefined content.
453 If \a clarkName is an invalid name, a default constructed QXmlName is
459 QXmlName QXmlName::fromClarkName(const QString &clarkName,
460 const QXmlNamePool &namePool)
462 return namePool.d->fromClarkName(clarkName);
466 \typedef QXmlName::LocalNameCode
471 \typedef QXmlName::PrefixCode
476 \typedef QXmlName::NamespaceCode
481 \fn void QXmlName::setLocalName(const LocalNameCode c)
486 \fn LocalNameCode QXmlName::localName() const
491 \fn PrefixCode QXmlName::prefix() const
496 \fn NamespaceCode QXmlName::namespaceURI() const
501 \fn void QXmlName::setNamespaceURI(const NamespaceCode c)
506 \fn void QXmlName::setPrefix(const PrefixCode c)