NamedNodeMaps are used to
* represent collections of nodes that can be accessed by name.
*
* Note that NamedNodeMap does not inherit from NodeList;
* NamedNodeMaps are not maintained in any particular order.
* Nodes contained in a NamedNodeMap may
* also be accessed by an ordinal index, but this is simply to allow
* convenient enumeration of the contents, and
* does not imply that the DOM specifies an order to these Nodes.
*/
class CDOM_EXPORT DOM_NamedNodeMap {
private:
void *fImpl;
short flagElem;
static const unsigned short NNM_ELEMENT;
static const unsigned short NNM_OTHER;
public:
/** @name Constructors and assignment operator */
//@{
/**
* Default constructor for DOM_NamedNodeMap. The resulting object does not
* refer to an actual DOM_NamedNodeMap node; it will compare == to 0, and is similar
* to a null object reference variable in Java. NamedNopes are instantiated
* by these methods: DOM_Node::getAttributes, DOM_DocumentType::getEntities
* andDOM_DocumentType::getNotations
*
*/
DOM_NamedNodeMap();
/**
* Copy constructor. Creates a new DOM_NamedNodeMap reference object
* that refers to the same underlying NamedNodeMap as the original.
*
* @param other The object to be copied.
*/
DOM_NamedNodeMap(const DOM_NamedNodeMap &other);
/**
* Assignment operator.
*
* @param other The object to be copied.
*/
DOM_NamedNodeMap & operator = (const DOM_NamedNodeMap &other);
/**
* Assignment operator.
*
* @param other The object to be copied.
*/
DOM_NamedNodeMap & operator = (const DOM_NullPtr *other);
//@}
/** @name Destructor. */
//@{
/**
* Destructor for DOM_NamedNodeMap. The object being destroyed is the reference
* object, not the underlying NamedNodeMap itself.
*
* Like most other DOM types in this implementation, memory management
* of named node maps is automatic. Instances of DOM_NamedNodeMap function
* as references to an underlying heap based implementation object,
* and should never be explicitly new-ed or deleted in application code, but
* should appear only as local variables or function parameters.
*
*/
~DOM_NamedNodeMap();
//@}
/** @Comparisons. */
//@{
/**
* Test whether this NamedNodeMap reference refers to the same underlying
* named node map as the other reference object. This does not
* compare the contents of two different objects.
*
* @param other The value to be compared
* @return Returns true if the underlying named node map is same
*/
bool operator == (const DOM_NamedNodeMap &other) const;
/**
* Test whether this NamedNodeMap reference refers to a different underlying
* named node map as the other reference object. This does not
* compare the contents of two different objects.
*
* @param other The value to be compared
* @return Returns true if the underlying named node map is different
*/
bool operator != (const DOM_NamedNodeMap &other) const;
/**
* Use this comparison operator to test whether a Named Node Map reference
* is null.
*
* @param p The value to be compared, which must be 0 or null.
* @return Returns true if the named node map is null
*/
bool operator == (const DOM_NullPtr *p) const;
/**
* Use this comparison operator to test whether a Named Node Map reference
* is not null.
*
* @param p The value to be compared, which must not be 0 or null.
* @return Returns true if the named node map is not null
*/
bool operator != (const DOM_NullPtr *p) const;
//@}
/** @name Set functions. */
//@{
/**
* Adds a node using its nodeName attribute.
*
*
As the nodeName attribute is used to derive the name
* which the node must be stored under, multiple nodes of certain types
* (those that have a "special" string value) cannot be stored as the names
* would clash. This is seen as preferable to allowing nodes to be aliased.
* @param arg A node to store in a named node map. The node will later be
* accessible using the value of the nodeName attribute of
* the node. If a node with that name is already present in the map, it
* is replaced by the new one.
* @return If the new Node replaces an existing node the
* replaced Node is returned,
* otherwise null is returned.
* @exception DOMException
* WRONG_DOCUMENT_ERR: Raised if arg was created from a
* different document than the one that created the
* NamedNodeMap.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this
* NamedNodeMap is readonly.
*
INUSE_ATTRIBUTE_ERR: Raised if arg is an
* Attr that is already an attribute of another
* Element object. The DOM user must explicitly clone
* Attr nodes to re-use them in other elements.
*/
DOM_Node setNamedItem(DOM_Node arg);
//@}
/** @name Get functions. */
//@{
/**
* Returns the indexth item in the map.
*
* If index
* is greater than or equal to the number of nodes in the map, this returns
* null.
* @param index Index into the map.
* @return The node at the indexth position in the
* NamedNodeMap, or null if that is not a valid
* index.
*/
DOM_Node item(unsigned int index) const;
/**
* Retrieves a node specified by name.
*
* @param name The nodeName of a node to retrieve.
* @return A DOM_Node (of any type) with the specified nodeName, or
* null if it does not identify any node in
* the map.
*/
DOM_Node getNamedItem(const DOMString &name) const;
/**
* The number of nodes in the map.
*
* The range of valid child node indices is
* 0 to length-1 inclusive.
*/
unsigned int getLength() const;
//@}
/** @name Functions to change the node collection. */
//@{
/**
* Removes a node specified by name.
*
* If the removed node is an
* Attr with a default value it is immediately replaced.
* @param name The nodeName of a node to remove.
* @return The node removed from the map or null if no node
* with such a name exists.
* @exception DOMException
* NOT_FOUND_ERR: Raised if there is no node named name in
* the map.
*
* NO_MODIFICATION_ALLOWED_ERR: Raised if this NamedNodeMap
* is readonly.
*/
DOM_Node removeNamedItem(const DOMString &name);
//@}
/** @name Functions introduced in DOM Level 2. */
//@{
/**
* Retrieves a node specified by local name and namespace URI.
*
* @param namespaceURI The namespace URI of
* the node to retrieve.
* @param localName The local name of the node to retrieve.
* @return A DOM_Node (of any type) with the specified
* local name and namespace URI, or null if they do not
* identify any node in the map.
*/
DOM_Node getNamedItemNS(const DOMString &namespaceURI,
const DOMString &localName);
/**
* Adds a node using its namespaceURI and localName.
*
* @param arg A node to store in a named node map. The node will later be
* accessible using the value of the namespaceURI and
* localName attribute of the node. If a node with those
* namespace URI and local name is already present in the map, it is
* replaced by the new one.
* @return If the new DOM_Node replaces an existing node the
* replaced DOM_Node is returned,
* otherwise null is returned.
* @exception DOMException
* WRONG_DOCUMENT_ERR: Raised if arg was created from a
* different document than the one that created the
* DOM_NamedNodeMap.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if this
* vNamedNodeMap is readonly.
*
INUSE_ATTRIBUTE_ERR: Raised if arg is an
* DOM_Attr that is already an attribute of another
* DOM_Element object. The DOM user must explicitly clone
* DOM_Attr nodes to re-use them in other elements.
*/
DOM_Node setNamedItemNS(DOM_Node arg);
/**
* Removes a node specified by local name and namespace URI.
*
* @param namespaceURI The namespace URI of
* the node to remove.
* @param localName The local name of the
* node to remove. When this DOM_NamedNodeMap contains the
* attributes attached to an element, as returned by the attributes
* attribute of the DOM_Node interface, if the removed
* attribute is known to have a default value, an attribute
* immediately appears containing the default value
* as well as the corresponding namespace URI, local name, and prefix.
* @return The node removed from the map if a node with such a local name
* and namespace URI exists.
* @exception DOMException
* NOT_FOUND_ERR: Raised if there is no node named name in
* the map.
*
* NO_MODIFICATION_ALLOWED_ERR: Raised if this DOM_NamedNodeMap
* is readonly.
*/
DOM_Node removeNamedItemNS(const DOMString &namespaceURI,
const DOMString &localName);
//@}
protected:
DOM_NamedNodeMap(NamedNodeMapImpl *impl);
DOM_NamedNodeMap(NodeImpl *impl);
friend class DOM_DocumentType;
friend class DOM_Node;
};
XERCES_CPP_NAMESPACE_END
#endif