namednodemap(3)

NAME

XML::DOM::NamedNodeMap - A hash table interface for
XML::DOM

DESCRIPTION

Objects implementing the NamedNodeMap interface 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 particu
lar order. Objects contained in an object implementing
NamedNodeMap may also be accessed by an ordinal index, but
this is simply to allow convenient enumeration of the con
tents of a NamedNodeMap, and does not imply that the DOM
specifies an order to these Nodes.

Note that in this implementation, the objects added to a
NamedNodeMap are kept in order.

METHODS

getNamedItem (name)

Retrieves a node specified by name.

Return Value: A Node (of any type) with the specified
name, or undef if the specified name did not identify
any node in the map.

setNamedItem (arg)

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.

Parameters:

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 Value: If the new Node replaces an existing
node with the same name the previously existing Node
is returned, otherwise undef is returned.

DOMExceptions:

· WRONG_DOCUMENT_ERR

Raised if arg was created from a different docu
ment 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.

removeNamedItem (name)

Removes a node specified by name. If the removed node
is an Attr with a default value it is immediately
replaced.

Return Value: The node removed from the map or undef
if no node with such a name exists.

DOMException:

· NOT_FOUND_ERR

Raised if there is no node named name in the map.

item (index)

Returns the indexth item in the map. If index is
greater than or equal to the number of nodes in the
map, this returns undef.

Return Value: The node at the indexth position in the
NamedNodeMap, or undef if that is not a valid index.

getLength

Returns the number of nodes in the map. The range of
valid child node indices is 0 to length-1 inclusive.

Additional methods not in the DOM Spec

getValues

Returns a NodeList with the nodes contained in the
NamedNodeMap. The NodeList is "live", in that it
reflects changes made to the NamedNodeMap.

When this method is called in a list context, it
returns a regular perl list containing the values.
Note that this list is not "live". E.g.

@list = $map->getValues; # returns a perl list
$nodelist = $map->getValues; # returns a NodeList

(object ref.)
for my $val ($map->getValues) # iterate over the

values

getChildIndex (node)

Returns the index of the node in the NodeList as
returned by getValues, or -1 if the node is not in the
NamedNodeMap.

dispose

Removes all circular references in this NamedNodeMap
and its descendants so the objects can be claimed for
garbage collection. The objects should not be used
afterwards.

perl v5.8.0 2000-01-31 NAMEDNODEMAP(1)