1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
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 doc/src/snippets/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 doc/src/snippets/patternist/svgDocumentElement.xml
128 \quotefile doc/src/snippets/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 doc/src/snippets/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}
402 QString QXmlName::toClarkName(const QXmlNamePool &namePool) const
404 return namePool.d->toClarkName(*this);
408 Assigns \a other to \e this and returns \e this.
410 QXmlName &QXmlName::operator=(const QXmlName &other)
412 m_qNameCode = other.m_qNameCode;
417 Returns true if \a candidate is an \c NCName. An \c NCName
418 is a string that can be used as a name in XML and XQuery,
419 e.g., the prefix or local name in an element or attribute,
420 or the name of a variable.
422 \sa {http://www.w3.org/TR/REC-xml-names/#NT-NCName} {Namespaces in XML 1.0 (Second Edition), [4] NCName}
424 bool QXmlName::isNCName(const QString &candidate)
426 return QXmlUtils::isNCName(candidate);
430 Converts \a clarkName into a QXmlName, inserts into \a namePool, and
433 A clark name is a way to present a full QName with only one string, where
434 the namespace cannot contain braces. Here are a couple of examples:
442 \li The local name \c html, in no namespace
444 \li \c {http://www.w3.org/1999/xhtml}html
445 \li The local name \c html, in the XHTML namespace
447 \li \c {http://www.w3.org/1999/xhtml}my:html
448 \li The local name \c html, in the XHTML namespace, with the prefix \c my
451 If the namespace contains braces, the returned value is either invalid or
452 has undefined content.
454 If \a clarkName is an invalid name, a default constructed QXmlName is
460 QXmlName QXmlName::fromClarkName(const QString &clarkName,
461 const QXmlNamePool &namePool)
463 return namePool.d->fromClarkName(clarkName);
467 \typedef QXmlName::LocalNameCode
472 \typedef QXmlName::PrefixCode
477 \typedef QXmlName::NamespaceCode
482 \fn void QXmlName::setLocalName(const LocalNameCode c)
487 \fn LocalNameCode QXmlName::localName() const
492 \fn PrefixCode QXmlName::prefix() const
497 \fn NamespaceCode QXmlName::namespaceURI() const
502 \fn void QXmlName::setNamespaceURI(const NamespaceCode c)
507 \fn void QXmlName::setPrefix(const PrefixCode c)