NSXMLElement Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.4 and later.
Companion guide
Declared in
NSXMLElement.h
Related sample code

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.

NSXMLElement implements isEqual: 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 because 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

Obtaining Child Elements

Manipulating Child Elements

Handling Attributes

Handling Namespaces

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 replaces the old attribute.

Discussion

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

Availability
  • Available in OS X v10.4 and later.
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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 an empty array if no matching children could be found.

Availability
  • Available in OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
Declared In
NSXMLElement.h

removeAttributeForName:

Removes an attribute node identified by name.

- (void)removeAttributeForName:(NSString *)attrName
Parameters
attrName

A string specifying the name of an attribute.

Availability
  • Available in OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
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 setAttributesWithDictionary:.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSXMLElement.h

setAttributesWithDictionary:

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

- (void)setAttributesWithDictionary:(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 OS X v10.7 and later.
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 OS X v10.4 and later.
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 OS X v10.4 and later.
Declared In
NSXMLElement.h