1 //! Contains namespace manipulation types and functions.
10 /// Designates prefix for namespace definitions.
12 /// See [Namespaces in XML][namespace] spec for more information.
14 ///   [namespace]: http://www.w3.org/TR/xml-names/#ns-decl
19 /// See [A Namespace Name for xmlns Attributes][namespace] for more information.
21 ///   [namespace]: http://www.w3.org/2000/xmlns/
24 /// Designates prefix for a namespace containing several special predefined attributes.
38 pub const NS_XML_URI: &str = "http://www.w3.org/XML/1998/namespace";
42 /// This constant should be used to define or query default namespace which should be used
43 /// for element or attribute names without prefix. For example, if a namespace mapping
47 ///   NS_NO_PREFIX  -->  urn:some:namespace
50 /// then all names declared without an explicit prefix `urn:some:namespace` is assumed as
51 /// a namespace URI.
53 /// By default empty prefix corresponds to absence of namespace, but this can change either
54 /// when writing an XML document (manually) or when reading an XML document (based on namespace
58 /// Designates an empty namespace URI, which is equivalent to absence of namespace.
61 /// empty prefix corresponds to absent namespace in `NamespaceStack` instances created with
63 /// in a namespace back to its default value.
66 /// Namespace is a map from prefixes to namespace URIs.
68 /// No prefix (i.e. default namespace) is designated by `NS_NO_PREFIX` constant.
70 pub struct Namespace(pub BTreeMap<String, String>);  struct
72 impl Namespace {  impl
73     /// Returns an empty namespace.
76     pub fn empty() -> Namespace {  in empty()
77         Namespace(BTreeMap::new())  in empty()
80     /// Checks whether this namespace is empty.
87     /// Checks whether this namespace is essentially empty, that is, it does not contain
91         // a shortcut for a namespace which is definitely not empty  in is_essentially_empty()
102     /// Checks whether this namespace mapping contains the given prefix.
105     /// * `prefix`  --- namespace prefix.
108     /// `true` if this namespace contains the given prefix, `false` otherwise.
114     /// Puts a mapping into this namespace.
122     /// * `prefix` --- namespace prefix;
123     /// * `uri`    --- namespace URI.
127     /// was already present in the namespace.
140     /// Puts a mapping into this namespace forcefully.
147     /// * `prefix` --- namespace prefix;
148     /// * `uri`    --- namespace URI.
152     /// `None` if such prefix was not present in the namespace before.
159     /// Queries the namespace for the given prefix.
162     /// * `prefix` --- namespace prefix.
165     /// Namespace URI corresponding to the given prefix, if it is present.
170     /// Borrowed namespace for the writer
177 /// An alias for iterator type for namespace mappings contained in a namespace.
183 impl<'a> IntoIterator for &'a Namespace {  implementation
195 /// Namespace stack is a sequence of namespaces.
197 /// Namespace stack is used to represent cumulative namespace consisting of
200 pub struct NamespaceStack(pub Vec<Namespace>);
203     /// Returns an empty namespace stack.
210     /// Returns a namespace stack with default items in it.
214     /// * `xml` → `http://www.w3.org/XML/1998/namespace`;
221         // xml namespace  in default()
223         // xmlns namespace  in default()
225         // empty namespace  in default()
230     /// Adds an empty namespace to the top of this stack.
233         self.0.push(Namespace::empty());  in push_empty()
237     /// Removes the topmost namespace in this stack.
241     pub fn pop(&mut self) -> Namespace {  in pop()  argument
245     /// Removes the topmost namespace in this stack.
247     /// Returns `Some(namespace)` if this stack is not empty and `None` otherwise.
249     pub fn try_pop(&mut self) -> Option<Namespace> {  in try_pop()  argument
253     /// Borrows the topmost namespace mutably, leaving the stack intact.
257     pub fn peek_mut(&mut self) -> &mut Namespace {  in peek_mut()  argument
261     /// Borrows the topmost namespace immutably, leaving the stack intact.
266     pub fn peek(&self) -> &Namespace {  in peek()  argument
270     /// Puts a mapping into the topmost namespace if this stack does not already contain one.
274     /// namespace prefix is not already mapped, or if it is mapped, but to a different URI.
277     /// * `prefix` --- namespace prefix;
278     /// * `uri`    --- namespace URI.
282     /// was already present in the namespace stack.
295     /// Puts a mapping into the topmost namespace in this stack.
297     /// This method does not override a mapping in the topmost namespace if it is
304     /// * `prefix` --- namespace prefix;
305     /// * `uri`    --- namespace URI.
309     /// was already present in the namespace.
323     /// This method walks the stack from top to bottom, querying each namespace
328     /// * `prefix` --- namespace prefix.
341     /// Combines this stack of namespaces into a single namespace.
343     /// Namespaces are combined in left-to-right order, that is, rightmost namespace
346     pub fn squash(&self) -> Namespace {  in squash()  argument
351         Namespace(result)  in squash()
362     /// Returns an iterator over all mappings in this namespace stack.
370 /// An iterator over mappings from prefixes to URIs in a namespace stack.
374 /// # use xml::namespace::NamespaceStack;
385     namespaces: Rev<Iter<'a, Namespace>>,
401         // If there is no current namespace and no next namespace, we're finished  in next()
408             // There is an element in the current namespace  in next()
418             // Current namespace is exhausted  in next()
420                 // If there is next namespace, continue from it  in next()
423                 // No next namespace, exiting  in next()
443 /// A type alias for a pair of `(prefix, uri)` values returned by namespace iterators.
446 impl<'a> Extend<UriMapping<'a>> for Namespace {  implementation
467 /// # use xml::namespace::NamespaceStack;
486 /// # use xml::namespace::NamespaceStack;