---

NSXMLElement Class Reference

Overview

Instances of the NSXMLElement class represent element nodes in an XML tree structure. An NSXMLElement object may have child nodes, specifically comment nodes, processing-instruction nodes, text nodes, and other NSXMLElement nodes. It may also have attribute nodes and namespace nodes associated with it (however, namespace and attribute nodes are not considered children). Any attempt to add a NSXMLDocument node, NSXMLDTD node, namespace node, or attribute node as a child raises an exception. If you add a child node to an NSXMLElement object and that child already has a parent, NSXMLElement raises an exception; the child must be detached or copied first.

Subclassing Notes

You can subclass NSXMLElement if you want element nodes with more specialized attributes or behavior, for example, paragraph and font attributes that specify how the string value of the element should appear.

Methods to Override

To subclass NSXMLElement you need to override the primary initializer, initWithName:URI:, and the methods listed below. In most cases, you need only invoke the superclass implementation, adding any subclass-specific code before or after the invocation, as necessary.

By default NSXMLElement implements the NSObject isEqual: method to perform a deep comparison: two NSXMLDocument objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. If you want a different standard of comparison, override isEqual:.

Special Considerations

Because of the architecture and data model of NSXML, when it parses and processes a source of XML it cannot know about your subclass unless you override the class method replacementClassForClass: to return your custom class in place of an NSXML class. If your custom class has no direct NSXML counterpart—for example, it is a subclass of NSXMLNode that represents CDATA sections—then you can walk the tree after it has been created and insert the new node where appropriate.

Note that you can safely set the root element of the XML document (using the NSXMLDocument setRootElement:method) to be an instance of your subclass since this method only checks to see if the added node is of an element kind (NSXMLElementKind). These precautions do not apply, of course, if you are creating an XML tree programmatically.

Tasks

Initializing NSXMLElement Objects

• – initWithName:
• – initWithName:stringValue:
• – initWithXMLString:error:
• – initWithName:URI:

Obtaining Child Elements

• – elementsForName:
• – elementsForLocalName:URI:

Manipulating Child Elements

• – addChild:
• – insertChild:atIndex:
• – insertChildren:atIndex:
• – removeChildAtIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:
• – normalizeAdjacentTextNodesPreservingCDATA:

Handling Attributes

• – addAttribute:
• – attributeForName:
• – attributeForLocalName:URI:
• – attributes
• – removeAttributeForName:
• – setAttributes:
• – setAttributesAsDictionary:

Handling Namespaces

• – addNamespace:
• – namespaces
• – namespaceForPrefix:
• – removeNamespaceForPrefix:
• – resolveNamespaceForName:
• – resolvePrefixForNamespaceURI:
• – setNamespaces:

Instance Methods

addAttribute:

Adds an attribute node to the receiver.

- (void)addAttribute:(NSXMLNode *)anAttribute

Parameters

anAttribute

An XML node object representing an attribute. If the receiver already has an attribute with the same name, anAttribute is not added.

Discussion

The order of multiple attributes is preserved if the NSXMLPreserveAttributeOrder option is specified when the element is created.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – attributeForName:
• – attributes
• – removeAttributeForName:
• – setAttributes:

Related Sample Code

• AlbumToSlideshow
• Core Data HTML Store

Declared In

NSXMLElement.h

addChild:

Adds a child node at the end of the receiver’s current list of children.

- (void)addChild:(NSXMLNode *)child

Parameters

child

An XML node object to add to the receiver's children.

Discussion

The new node has an index value that is one greater than the last of the current children.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – insertChild:atIndex:
• – removeChildAtIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:

Related Sample Code

• AlbumToSlideshow
• Core Data HTML Store

Declared In

NSXMLElement.h

addNamespace:

Adds a namespace node to the receiver.

- (void)addNamespace:(NSXMLNode *)aNamespace

Parameters

aNamespace

An XML node object of kind NSXMLNamespaceKind. If the receiver already has a namespace with the same name, aNamespace is not added.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – namespaces
• – namespaceForPrefix:
• – removeNamespaceForPrefix:
• – resolveNamespaceForName:
• – resolvePrefixForNamespaceURI:
• – setNamespaces:

Declared In

NSXMLElement.h

attributeForLocalName:URI:

Returns the attribute node of the receiver that is identified by a local name and URI.

- (NSXMLNode *)attributeForLocalName:(NSString *)localName URI:(NSString *)URI

Parameters

localName

A string specifying the local name of an attribute.

URI

A sting identifying the URI associated with an attribute.

Return Value

An XML node object representing a matching attribute or nil if no such node was found.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – attributeForName:
• – attributes
• – removeAttributeForName:
• – setAttributes:

Declared In

NSXMLElement.h

attributeForName:

Returns the attribute node of the receiver with the specified name.

- (NSXMLNode *)attributeForName:(NSString *)name

Parameters

name

A string specifying the name of an attribute.

Return Value

An XML node object representing a matching attribute or nil if no such node was found.

Discussion

If name is a qualified name, then this method invokes attributeForLocalName:URI: with the URI parameter set to the URI associated with the prefix. Otherwise comparison is based on string equality of the qualified or non-qualified name.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – attributes
• – removeAttributeForName:
• – setAttributes:

Related Sample Code

• Core Data HTML Store

Declared In

NSXMLElement.h

attributes

Returns the receiver’s attributes

- (NSArray *)attributes

Return Value

An array of NSXMLNode objects of kind NSXMLAttributeKind or nil if the receiver has no attribute nodes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – attributeForLocalName:URI:
• – attributeForName:
• – removeAttributeForName:
• – setAttributes:

Declared In

NSXMLElement.h

elementsForLocalName:URI:

Returns the child element nodes (as NSXMLElement objects) of the receiver that are matched with the specified local name and URI.

- (NSArray *)elementsForLocalName:(NSString *)localName URI:(NSString *)URI

Parameters

localName

A string specifying a local name of an element.

URI

A string specifying a URI associated with an element.

Return Value

An array of NSXMLElement objects or nil if no matching children could be found.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – elementsForName:

Declared In

NSXMLElement.h

elementsForName:

Returns the child element nodes (as NSXMLElement objects) of the receiver that have a specified name.

- (NSArray *)elementsForName:(NSString *)name

Parameters

name

A string specifying the name of the child element nodes to find and return. If name is a qualified name, then this method invokes elementsForLocalName:URI: with the URI parameter set to the URI associated with the prefix. Otherwise comparison is based on string equality of the qualified or non-qualified name.

Return Value

An array of of NSXMLElement objects or an empty array if no matching children can be found.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• Core Data HTML Store
• NewsReader

Declared In

NSXMLElement.h

initWithName:

Returns an NSXMLElement object initialized with the specified name.

- (id)initWithName:(NSString *)name

Parameters

name

A string specifying the name of the element.

Return Value

The initialized NSXMLElement object or nil if initialization did not succeed.

Discussion

The XML string representation of this object is <name></name>. This method invokes initWithName:URI: with the URI parameter set to nil.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – initWithName:stringValue:
• – initWithXMLString:error:

Declared In

NSXMLElement.h

initWithName:stringValue:

Returns an NSXMLElement object initialized with a specified name and a single text-node child containing a specified value.

- (id)initWithName:(NSString *)name stringValue:(NSString *)string

Parameters

name

A string specifying the name of the element.

string

The string value of the receiver's text node.

Return Value

The initialized NSXMLElement object or nil if initialization did not succeed.

Discussion

The string representation of this object is <name>string</name>.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – initWithName:URI:
• – initWithName:
• – initWithXMLString:error:

Declared In

NSXMLElement.h

initWithName:URI:

Returns an NSXMLElement object initialized with the specified name and URI.

- (id)initWithName:(NSString *)name URI:(NSString *)URI

Parameters

name

A string that specifies the qualified name of the element.

URI

A string that specifies the namespace URI associated with the element.

Return Value

The initialized NSXMLElement object or nil if initialization did not succeed.

Discussion

You can look up the namespace prefix for this element node based on its URI using resolvePrefixForNamespaceURI:. This method is the primary initializer for the NSXMLElement class.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – initWithName:
• – initWithName:stringValue:
• – initWithXMLString:error:

Declared In

NSXMLElement.h

initWithXMLString:error:

Returns an NSXMLElement object created from a specified string containing XML markup.

- (id)initWithXMLString:(NSString *)string error:(NSError **)error

Parameters

string

A string containing XML markup for an element.

error

On return, an NSError object that describes any errors or warnings resulting from the parsing of the markup.

Return Value

The initialized NSXMLElement object or nil if initialization did not succeed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – initWithName:URI:
• – initWithName:
• – initWithName:stringValue:

Declared In

NSXMLElement.h

insertChild:atIndex:

Inserts a new child node at a specified location in the receiver’s list of child nodes.

- (void)insertChild:(NSXMLNode *)child atIndex:(NSUInteger)index

Parameters

child

An XML node object to be inserted as a child of the receiver.

index

An integer identifying a position in the receiver's list of children. An exception is raised if index is out of bounds.

Discussion

Insertion of the node increments the indexes of sibling nodes after it.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addChild:
• – insertChildren:atIndex:
• – removeChildAtIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:

Declared In

NSXMLElement.h

insertChildren:atIndex:

Inserts an array of child nodes at a specified location in the receiver’s list of children.

- (void)insertChildren:(NSArray *)children atIndex:(NSUInteger)index

Parameters

children

An array of XML node objects to add as children of the receiver.

index

An integer identifying a position in the receiver's list of children. An exception is raised if index is out of bounds.

Discussion

Insertion of the node increases the indexes of sibling nodes after it by the count of children.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addChild:
• – insertChild:atIndex:
• – removeChildAtIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:

Declared In

NSXMLElement.h

namespaceForPrefix:

Returns the namespace node with a specified prefix.

- (NSXMLNode *)namespaceForPrefix:(NSString *)name

Parameters

name

A string specifying a namespace prefix.

Return Value

An NSXMLNode object of kind NSXMLNamespaceKind or nil if there is no namespace node with that prefix.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaces
• – removeNamespaceForPrefix:
• – resolveNamespaceForName:
• – resolvePrefixForNamespaceURI:
• – setNamespaces:

Declared In

NSXMLElement.h

namespaces

Returns the namespace nodes of the receiver.

- (NSArray *)namespaces

Return Value

An array of NSXMLNode objects of kind NSXMLNamespaceKind. Returns nil if the receiver has no namespace nodes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaceForPrefix:
• – removeNamespaceForPrefix:
• – resolveNamespaceForName:
• – resolvePrefixForNamespaceURI:
• – setNamespaces:

Declared In

NSXMLElement.h

normalizeAdjacentTextNodesPreservingCDATA:

Coalesces adjacent text nodes of the receiver that you have explicitly added, optionally including CDATA sections.

- (void)normalizeAdjacentTextNodesPreservingCDATA:(BOOL)preserve

Parameters

preserve

YES if CDATA sections are left alone as text nodes, NO otherwise.

Discussion

A text node with a value of an empty string is removed. When you process an input source of XML, adjacent text nodes are automatically normalized. You should invoke this method (with preserve as NO) before using the NSXMLNode methods objectsForXQuery:constants:error: or nodesForXPath:error:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setChildren:

Declared In

NSXMLElement.h

removeAttributeForName:

Removes an attribute node that is identified by its name.

- (void)removeAttributeForName:(NSString *)attrName

Parameters

attrName

A string specifying the name of an attribute.

Discussion

The removed XML node object is released.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addAttribute:
• – attributeForName:
• – attributes
• – removeAttributeForName:
• – setAttributes:

Declared In

NSXMLElement.h

removeChildAtIndex:

Removes the child node of the receiver identified by a given index.

- (void)removeChildAtIndex:(NSUInteger)nodeIndex

Parameters

nodeIndex

An integer identifying the node in the receiver's list of children to remove. An exception is raised if index is out of bounds.

Discussion

The XML node object is released upon removal. The indices of subsequent children are decremented by one.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addChild:
• – insertChild:atIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:

Related Sample Code

• Core Data HTML Store

Declared In

NSXMLElement.h

removeNamespaceForPrefix:

Removes a namespace node that is identified by a given prefix.

- (void)removeNamespaceForPrefix:(NSString *)name

Parameters

name

A string that is the prefix for a namespace.

Discussion

The removed XML node object is removed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaces
• – namespaceForPrefix:
• – setNamespaces:

Declared In

NSXMLElement.h

replaceChildAtIndex:withNode:

Replaces a child node at a specified location with another child node.

- (void)replaceChildAtIndex:(NSUInteger)index withNode:(NSXMLNode *)node

Parameters

index

An integer identifying a position in the receiver's list of children. An exception is raised if index is out of bounds.

node

An XML node object that will replace the current child.

Discussion

The replaced XML node object is released upon removal.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addChild:
• – insertChild:atIndex:
• – insertChildren:atIndex:
• – removeChildAtIndex:
• – setChildren:

Declared In

NSXMLElement.h

resolveNamespaceForName:

Returns the namespace node with the prefix matching the given qualified name.

- (NSXMLNode *)resolveNamespaceForName:(NSString *)name

Parameters

name

A string that is the qualified name for a namespace (a qualified name is prefix plus local name).

Return Value

An NSXMLNode object of kind NSXMLNamespaceKind or nil if there is no matching namespace node.

Discussion

The method looks in the entire namespace chain for the prefix.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaces
• – namespaceForPrefix:
• – resolvePrefixForNamespaceURI:
• – setNamespaces:

Declared In

NSXMLElement.h

resolvePrefixForNamespaceURI:

Returns the prefix associated with the specified URI.

- (NSString *)resolvePrefixForNamespaceURI:(NSString *)namespaceURI

Parameters

namespaceURI

A string identifying the URI associated with the namespace.

Return Value

A string that is the matching prefix or nil if it finds no matching prefix.

Discussion

The method looks in the entire namespace chain for the URI.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaces
• – namespaceForPrefix:
• – resolveNamespaceForName:
• – setNamespaces:

Declared In

NSXMLElement.h

setAttributes:

Sets all attributes of the receiver at once, replacing any existing attribute nodes.

- (void)setAttributes:(NSArray *)attributes

Parameters

attributes

An array of NSXMLNode objects of kind NSXMLAttributeKind. If there are attribute nodes with the same name, the first attribute with that name is used. Send this message with attributes as nil to remove all attributes.

Discussion

To set attributes in an element node using an NSDictionary object as the input parameter, see setAttributesAsDictionary:.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addAttribute:
• – attributeForName:
• – attributes
• – removeAttributeForName:

Declared In

NSXMLElement.h

setAttributesAsDictionary:

Sets the attributes of the receiver based on the key-value pairs specified in the passed-in dictionary.

- (void)setAttributesAsDictionary:(NSDictionary *)attributes

Parameters

attributes

A dictionary of key-value pairs where the attribute name is the key and the object value of the attribute is the dictionary value.

Discussion

The method uses these names and object values to create NSXMLNode objects of kind NSXMLAttributeKind. Existing attributes are removed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addAttribute:
• – attributes
• – removeAttributeForName:
• – setAttributes:

Declared In

NSXMLElement.h

setChildren:

Sets all child nodes of the receiver at once, replacing any existing children.

- (void)setChildren:(NSArray *)children

Parameters

children

An array of NSXMLElement objects or NSXMLNode objects of kinds NSXMLElementKind, NSXMLProcessingInstructionKind, NSXMLTextKind, or NSXMLCommentKind.

Discussion

Send this message with children as nil to remove all child nodes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – insertChild:atIndex:
• – insertChildren:atIndex:
• – removeChildAtIndex:
• – replaceChildAtIndex:withNode:
• – setChildren:

Related Sample Code

• Core Data HTML Store

Declared In

NSXMLElement.h

setNamespaces:

Sets all of the namespace nodes of the receiver at once, replacing any existing namespace nodes.

- (void)setNamespaces:(NSArray *)namespaces

Parameters

namespaces

An array of NSXMLNode objects of kind NSXMLNamespaceKind. If there are namespace nodes with the same prefix, the first attribute with that prefix is used. Send this message with namespaces as nil to remove all namespace nodes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addNamespace:
• – namespaces
• – namespaceForPrefix:
• – removeNamespaceForPrefix:
• – resolveNamespaceForName:
• – resolvePrefixForNamespaceURI:

Declared In

NSXMLElement.h

---