libzeep

PrevUpHomeNext

Class element

zeep::xml::element — the element class modelling a XML element

Synopsis

// In header: <zeep/xml/node.hpp>


class element : public zeep::xml::node {
public:
  // types
  typedef element                              value_type;         
  typedef std::allocator< element >            allocator_type;     
  typedef size_t                               size_type;          
  typedef ptrdiff_t                            difference_type;    
  typedef element &                            reference;          
  typedef const element &                      const_reference;    
  typedef element *                            pointer;            
  typedef const element *                      const_pointer;      
  typedef iterator_impl< element, node >       iterator;           
  typedef iterator_impl< const element, node > const_iterator;     
  typedef node_list::iterator                  node_iterator;      
  typedef node_list::const_iterator            const_node_iterator;

  // construct/copy/destruct
  element();
  element(const std::string &);
  element(const std::string &, std::initializer_list< attribute >);
  element(const element &);
  element(element &&);
  element & operator=(const element &);
  element & operator=(element &&);
  ~element();

  // friend functions
  friend std::ostream & operator<<(std::ostream &, const element &);

  // public member functions
  virtual std::string get_qname() const;
  virtual void set_qname(const std::string &);
  virtual std::string lang() const;
  std::string id() const;
  bool operator==(const element &) const;
  bool operator!=(const element &) const;
  virtual bool equals(const node *) const;
  void swap(element &) noexcept;
  node_list & nodes();
  const node_list & nodes() const;
  iterator begin();
  iterator end();
  const_iterator begin() const;
  const_iterator end() const;
  const_iterator cbegin();
  const_iterator cend();
  element & front();
  const element & front() const;
  element & back();
  const element & back() const;
  void insert(const_iterator, const element &);
  void insert(const_iterator, element &&);
  template<typename InputIter> 
    iterator insert(const_iterator, InputIter, InputIter);
  iterator insert(const_iterator, std::initializer_list< element >);
  template<typename N, 
           std::enable_if_t< std::is_same_v< std::remove_reference_t< N >, text > or std::is_same_v< std::remove_reference_t< N >, cdata > or std::is_same_v< std::remove_reference_t< N >, comment > or std::is_same_v< std::remove_reference_t< N >, processing_instruction >, int >  = 0> 
    iterator emplace(const_iterator, N &&);
  template<typename Arg> iterator emplace(const_iterator, Arg &&);
  template<typename... Args> iterator emplace(const_iterator, Args &&...);
  iterator emplace(const_iterator, const std::string &, 
                   std::initializer_list< attribute >);
  template<typename... Args> element & emplace_front(Args &&...);
  element & emplace_front(const std::string &, 
                          std::initializer_list< attribute >);
  template<typename... Args> element & emplace_back(Args &&...);
  element & emplace_back(const std::string &, 
                         std::initializer_list< attribute >);
  iterator erase(const_node_iterator);
  iterator erase(iterator, iterator);
  void pop_front();
  void pop_back();
  void push_front(element &&);
  void push_front(const element &);
  void push_back(element &&);
  void push_back(const element &);
  void clear();
  size_t size() const;
  bool empty() const;
  attribute_set & attributes();
  const attribute_set & attributes() const;
  virtual std::string str() const;
  virtual std::string namespace_for_prefix(const std::string &) const;
  virtual std::pair< std::string, bool > 
  prefix_for_namespace(const std::string &) const;
  void move_to_name_space(const std::string &, const std::string &, bool, 
                          bool);
  std::string get_content() const;
  void set_content(const std::string &);
  std::string get_attribute(const std::string &) const;
  void set_attribute(const std::string &, const std::string &);
  virtual void set_text(const std::string &);
  void add_text(const std::string &);
  void flatten_text();
  element_set find(const std::string &) const;
  element * find_first(const std::string &) const;
  element_set find(const char *) const;
  element * find_first(const char *) const;
  virtual void validate();
  void set_qname(const std::string &);
  void set_qname(const std::string &, const std::string &);

  // protected member functions
  virtual node * clone() const;
  virtual node * move();
  virtual void write(std::ostream &, format_info) const;
  virtual node_iterator insert_impl(const_iterator, node *);
};

Description

element is the most important zeep::xml::node object. It encapsulates a XML element as found in the XML document. It has a qname, can have children, attributes and a namespace.

element public construct/copy/destruct

  1. element();
  2. element(const std::string & qname);
  3. element(const std::string & qname, 
            std::initializer_list< attribute > attributes);
    constructor taking a qname and a list of attributes
  4. element(const element & e);
  5. element(element && e);
  6. element & operator=(const element & e);
  7. element & operator=(element && e);
  8. ~element();

element friend functions

  1. friend std::ostream & operator<<(std::ostream & os, const element & e);
    write the element to os

element public member functions

  1. virtual std::string get_qname() const;

    Nodes can have a name, and the XPath specification requires that a node can have a so-called expanded-name. This name consists of a local-name and a namespace which is a URI. And we can have a QName which is a concatenation of a prefix (that points to a namespace URI) and a local-name separated by a colon.

    To reduce storage requirements, names are stored in nodes as qnames, if at all.

  2. virtual void set_qname(const std::string & qn);
  3. virtual std::string lang() const;
    content of a xml:lang attribute of this element, or its nearest ancestor
  4. std::string id() const;

    content of the xml:id attribute, or the attribute that was defined to be of type ID by the DOCTYPE.

  5. bool operator==(const element & e) const;
  6. bool operator!=(const element & e) const;
  7. virtual bool equals(const node * n) const;
    Compare the node with n.
  8. void swap(element & e) noexcept;
  9. node_list & nodes();
  10. const node_list & nodes() const;
  11. iterator begin();
  12. iterator end();
  13. const_iterator begin() const;
  14. const_iterator end() const;
  15. const_iterator cbegin();
  16. const_iterator cend();
  17. element & front();
  18. const element & front() const;
  19. element & back();
  20. const element & back() const;
  21. void insert(const_iterator pos, const element & e);
    insert a copy of e
  22. void insert(const_iterator pos, element && e);
    insert a copy of e at position pos, moving its data
  23. template<typename InputIter> 
      iterator insert(const_iterator pos, InputIter first, InputIter last);
    insert copies of the nodes from first to last at position pos
  24. iterator insert(const_iterator pos, std::initializer_list< element > nodes);
    insert copies of the nodes in nodes at position pos
  25. template<typename N, 
             std::enable_if_t< std::is_same_v< std::remove_reference_t< N >, text > or std::is_same_v< std::remove_reference_t< N >, cdata > or std::is_same_v< std::remove_reference_t< N >, comment > or std::is_same_v< std::remove_reference_t< N >, processing_instruction >, int >  = 0> 
      iterator emplace(const_iterator pos, N && n);
    insert the data of node n at position pos, using move semantics
  26. template<typename Arg> iterator emplace(const_iterator pos, Arg && arg);
    emplace a newly constructed element at pos using argument arg
  27. template<typename... Args> 
      iterator emplace(const_iterator pos, Args &&... args);
    emplace a newly constructed element at pos using arguments args
  28. iterator emplace(const_iterator pos, const std::string & name, 
                     std::initializer_list< attribute > attrs);
    emplace a newly constructed element at pos using name name and attributes attrs
  29. template<typename... Args> element & emplace_front(Args &&... args);
    emplace an element at the front using arguments args
  30. element & emplace_front(const std::string & name, 
                            std::initializer_list< attribute > attrs);
    emplace a newly constructed element at the front using name name and attributes attrs
  31. template<typename... Args> element & emplace_back(Args &&... args);
    emplace an element at the back using arguments args
  32. element & emplace_back(const std::string & name, 
                           std::initializer_list< attribute > attrs);
    emplace a newly constructed element at the back using name name and attributes attrs
  33. iterator erase(const_node_iterator pos);
    erase the node at pos
  34. iterator erase(iterator first, iterator last);
    erase the nodes from first to last
  35. void pop_front();
    erase the first node
  36. void pop_back();
    erase the last node
  37. void push_front(element && e);
    move the element e to the front of this element.
  38. void push_front(const element & e);
    copy the element e to the front of this element.
  39. void push_back(element && e);
    move the element e to the back of this element.
  40. void push_back(const element & e);
    copy the element e to the back of this element.
  41. void clear();
    remove all nodes
  42. size_t size() const;
  43. bool empty() const;
  44. attribute_set & attributes();
    return the set of attributes for this element
  45. const attribute_set & attributes() const;
    return the set of attributes for this element
  46. virtual std::string str() const;
    will return the concatenation of str() from all child nodes
  47. virtual std::string namespace_for_prefix(const std::string & prefix) const;
    return the URI of the namespace for prefix
  48. virtual std::pair< std::string, bool > 
    prefix_for_namespace(const std::string & uri) const;
    return the prefix for the XML namespace with uri uri.

    Returns:

    The result is a pair of a std::string containing the actual prefix value and a boolean indicating if the namespace was found at all, needed since empty prefixes are allowed.

  49. void move_to_name_space(const std::string & prefix, const std::string & uri, 
                            bool recursive, bool including_attributes);
    move this element and optionally everyting beneath it to the specified namespace/prefix

    Parameters:

    including_attributes

    Move the attributes to this new namespace as well

    prefix

    The new prefix name

    recursive

    Apply this to the child nodes as well

    uri

    The new namespace uri

  50. std::string get_content() const;
    return the concatenation of the content of all enclosed zeep::xml::text nodes
  51. void set_content(const std::string & content);
    replace all existing child text nodes with a new single text node containing content
  52. std::string get_attribute(const std::string & qname) const;
    return the value of attribute name qname or the empty string if not found
  53. void set_attribute(const std::string & qname, const std::string & value);
    set the value of attribute named qname to the value value
  54. virtual void set_text(const std::string & s);
    The set_text method replaces any text node with the new text (call set_content)
  55. void add_text(const std::string & s);

    The add_text method checks if the last added child is a text node, and if so, it appends the string to this node's value. Otherwise, it adds a new text node child with the new text.

  56. void flatten_text();
    To combine all adjecent child text nodes into one.
  57. element_set find(const std::string & path) const;
    return the elements that match XPath path.

    xpath wrappers TODO: create recursive iterator and use it as return type here

    If you need to find other classes than xml::element, of if your XPath contains variables, you should create a zeep::xml::xpath object and use its evaluate method.

  58. element * find_first(const std::string & path) const;
    return the first element that matches XPath path.

    If you need to find other classes than xml::element, of if your XPath contains variables, you should create a zeep::xml::xpath object and use its evaluate method.

  59. element_set find(const char * path) const;
    return the elements that match XPath path.

    If you need to find other classes than xml::element, of if your XPath contains variables, you should create a zeep::xml::xpath object and use its evaluate method.

  60. element * find_first(const char * path) const;
    return the first element that matches XPath path.

    If you need to find other classes than xml::element, of if your XPath contains variables, you should create a zeep::xml::xpath object and use its evaluate method.

  61. virtual void validate();
    debug routine
  62. void set_qname(const std::string & qn);
  63. void set_qname(const std::string & prefix, const std::string & name);
    set the qname with two parameters, if prefix is empty the qname will be simply name otherwise the name will be prefix:name

    Parameters:

    name

    The actual name to use

    prefix

    The namespace prefix to use

element protected member functions

  1. virtual node * clone() const;
    return an exact copy of this node, including all data in sub nodes
  2. virtual node * move();

    return a copy of this node, including all data in sub nodes, but in contrast with clone the data is moved from this node to the cloned node. This node will be empty afterwards.

  3. virtual void write(std::ostream & os, format_info fmt) const;
    low level routine for writing out XML

    This method is usually called by operator<<(std::ostream&, zeep::xml::document&)

  4. virtual node_iterator insert_impl(const_iterator pos, node * n);

PrevUpHomeNext