Top Level

# XMLList - AS3

Package | Top Level
Class | public final dynamic class XMLList
Inheritance | XMLList Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The XMLList class contains methods for working with one or more XML elements. An XMLList object can represent one or more XML objects or elements (including multiple nodes or attributes), so you can call methods on the elements as a group or on the individual elements in the collection.

If an XMLList object has only one XML element, you can use the XML class methods on the XMLList object directly. In the following example, `example.two` is an XMLList object of length 1, so you can call any XML method on it.

Copy

     var example2 = <example><two>2</two></example>;

If you attempt to use XML class methods with an XMLList object containing more than one XML object, an exception is thrown; instead, iterate over the XMLList collection (using a `for each..in` statement, for example) and apply the methods to each XML object in the collection.

View the examples

More examples

Initializing XML variables
Assembling and transforming XML objects
Traversing XML structures
Using XML namespaces
XML type conversion
Converting XML and XMLList objects to strings
Reading external XML documents
XML in ActionScript example: Loading RSS data from the Internet

Learn more

Hierarchical data objects
Working with XML
Basics of XML
The E4X approach to XML processing
XML objects
XMLList objects

Related API Elements

XML
for each..in
Namespace
QName

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | XMLList(value:Object) Creates a new XMLList object. | XMLList
|  | attribute(attributeName:*):XMLList Calls the attribute() method of each XML object and returns an XMLList object of the results. | XMLList
|  | attributes():XMLList Calls the attributes() method of each XML object and returns an XMLList object of attributes for each XML object. | XMLList
|  | child(propertyName:Object):XMLList Calls the child() method of each XML object and returns an XMLList object that contains the results in order. | XMLList
|  | children():XMLList Calls the children() method of each XML object and returns an XMLList object that contains the results. | XMLList
|  | comments():XMLList Calls the comments() method of each XML object and returns an XMLList of comments. | XMLList
|  | contains(value:XML):Boolean Checks whether the XMLList object contains an XML object that is equal to the given value parameter. | XMLList
|  | copy():XMLList Returns a copy of the given XMLList object. | XMLList
|  | descendants(name:Object = *):XMLList Returns all descendants (children, grandchildren, great-grandchildren, and so on) of the XML object that have the given name parameter. | XMLList
|  | elements(name:Object = *):XMLList Calls the elements() method of each XML object. | XMLList
|  | hasComplexContent():Boolean Checks whether the XMLList object contains complex content. | XMLList
|  | hasOwnProperty(p:String):Boolean Checks for the property specified by p. | XMLList
|  | hasSimpleContent():Boolean Checks whether the XMLList object contains simple content. | XMLList
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | length():int Returns the number of properties in the XMLList object. | XMLList
|  | normalize():XMLList Merges adjacent text nodes and eliminates empty text nodes for each of the following: all text nodes in the XMLList, all the XML objects contained in the XMLList, and the descendants of all the XML objects in the XMLList. | XMLList
|  | parent():Object Returns the parent of the XMLList object if all items in the XMLList object have the same parent. | XMLList
|  | processingInstructions(name:String = "*"):XMLList If a name parameter is provided, lists all the children of the XMLList object that contain processing instructions with that name. | XMLList
|  | propertyIsEnumerable(p:String):Boolean Checks whether the property p is in the set of properties that can be iterated in a for..in statement applied to the XMLList object. | XMLList
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | text():XMLList Calls the text() method of each XML object and returns an XMLList object that contains the results. | XMLList
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns a string representation of all the XML objects in an XMLList object. | XMLList
|  | toXMLString():String Returns a string representation of all the XML objects in an XMLList object. | XMLList
|  | valueOf():XMLList Returns the XMLList object. | XMLList

Constructor Detail

### XMLList

()
Constructor

`public function XMLList(value:Object)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Creates a new XMLList object.

Parameters

| `value:Object` — Any object that can be converted to an XMLList object by using the top-level `XMLList()` function.

Related API Elements

top-level XMLList() function
Method Detail

### attribute

()
method

`AS3 function attribute(attributeName:*):XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `attribute()` method of each XML object and returns an XMLList object of the results. The results match the given `attributeName` parameter. If there is no match, the `attribute()` method returns an empty XMLList object.

Parameters

| `attributeName:*` — The name of the attribute that you want to include in an XMLList object.

Returns

| `XMLList` — An XMLList object of matching XML objects or an empty XMLList object.

Learn more

XMLList objects

Related API Elements

XML.attribute()
XML.attributes()

### attributes

()
method

`AS3 function attributes():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `attributes()` method of each XML object and returns an XMLList object of attributes for each XML object.

Returns

| `XMLList` — An XMLList object of attributes for each XML object.

Learn more

XMLList objects

Related API Elements

XML.attribute()
XML.attributes()

### child

()
method

`AS3 function child(propertyName:Object):XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `child()` method of each XML object and returns an XMLList object that contains the results in order.

Parameters

| `propertyName:Object` — The element name or integer of the XML child.

Returns

| `XMLList` — An XMLList object of child nodes that match the input parameter.

Learn more

XMLList objects

Related API Elements

XML.child()

### children

()
method

`AS3 function children():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `children()` method of each XML object and returns an XMLList object that contains the results.

Returns

| `XMLList` — An XMLList object of the children in the XML objects.

Learn more

XMLList objects

Related API Elements

XML.children()

### comments

()
method

`AS3 function comments():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `comments()` method of each XML object and returns an XMLList of comments.

Returns

| `XMLList` — An XMLList of the comments in the XML objects.

Learn more

XMLList objects

Related API Elements

XML.comments()

### contains

()
method

`AS3 function contains(value:XML):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Checks whether the XMLList object contains an XML object that is equal to the given `value` parameter.

Parameters

| `value:XML` — An XML object to compare against the current XMLList object.

Returns

| `Boolean` — If the XMLList contains the XML object declared in the `value` parameter, then `true`; otherwise `false`.

Learn more

XMLList objects

### copy

()
method

`AS3 function copy():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns a copy of the given XMLList object. The copy is a duplicate of the entire tree of nodes. The copied XML object has no parent and returns `null` if you attempt to call the `parent()` method.

Returns

| `XMLList` — The copy of the XMLList object.

Learn more

XMLList objects

### descendants

()
method

`AS3 function descendants(name:Object = *):XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns all descendants (children, grandchildren, great-grandchildren, and so on) of the XML object that have the given `name` parameter. The `name` parameter can be a QName object, a String data type, or any other data type that is then converted to a String data type.

To return all descendants, use the asterisk (*) parameter. If no parameter is passed, the string "*" is passed and returns all descendants of the XML object.

Parameters

| `name:Object` (default = `*`)`` — The name of the element to match.

Returns

| `XMLList` — An XMLList object of the matching descendants (children, grandchildren, and so on) of the XML objects in the original list. If there are no descendants, returns an empty XMLList object.

Learn more

XMLList objects

Related API Elements

XML.descendants()

### elements

()
method

`AS3 function elements(name:Object = *):XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `elements()` method of each XML object. The `name` parameter is passed to the `descendants()` method. If no parameter is passed, the string "*" is passed to the `descendants()` method.

Parameters

| `name:Object` (default = `*`)`` — The name of the elements to match.

Returns

| `XMLList` — An XMLList object of the matching child elements of the XML objects.

Related API Elements

XML.elements()

### hasComplexContent

()
method

`AS3 function hasComplexContent():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Checks whether the XMLList object contains complex content. An XMLList object is considered to contain complex content if it is not empty and either of the following conditions is true:

- The XMLList object contains a single XML item with complex content.
- The XMLList object contains elements.

Returns

| `Boolean` — If the XMLList object contains complex content, then `true`; otherwise `false`.

Learn more

XMLList objects

Related API Elements

hasSimpleContent()
XML.hasComplexContent()
XML.hasSimpleContent()

### hasOwnProperty

()
method

`AS3 function hasOwnProperty(p:String):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Checks for the property specified by `p`.

Parameters

| `p:String` — The property to match.

Returns

| `Boolean` — If the parameter exists, then `true`; otherwise `false`.

Learn more

XMLList objects

### hasSimpleContent

()
method

`AS3 function hasSimpleContent():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Checks whether the XMLList object contains simple content. An XMLList object is considered to contain simple content if one or more of the following conditions is true:

- The XMLList object is empty
- The XMLList object contains a single XML item with simple content
- The XMLList object contains no elements

Returns

| `Boolean` — If the XMLList contains simple content, then `true`; otherwise `false`.

Learn more

XMLList objects

Related API Elements

hasComplexContent()
XML.hasComplexContent()
XML.hasSimpleContent()

### length

()
method

`AS3 function length():int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns the number of properties in the XMLList object.

Returns

| `int` — The number of properties in the XMLList object.

Learn more

XMLList objects

### normalize

()
method

`AS3 function normalize():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Merges adjacent text nodes and eliminates empty text nodes for each of the following: all text nodes in the XMLList, all the XML objects contained in the XMLList, and the descendants of all the XML objects in the XMLList.

Returns

| `XMLList` — The normalized XMLList object.

Learn more

XMLList objects

### parent

()
method

`AS3 function parent():Object`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns the parent of the XMLList object if all items in the XMLList object have the same parent. If the XMLList object has no parent or different parents, the method returns `undefined`.

Returns

| `Object` — Returns the parent XML object.

Learn more

XMLList objects

### processingInstructions

()
method

`AS3 function processingInstructions(name:String = "*"):XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

If a `name` parameter is provided, lists all the children of the XMLList object that contain processing instructions with that name. With no parameters, the method lists all the children of the XMLList object that contain any processing instructions.

Parameters

| `name:String` (default = "`*`")`` — The name of the processing instructions to match.

Returns

| `XMLList` — An XMLList object that contains the processing instructions for each XML object.

Learn more

XMLList objects

Related API Elements

XML.processingInstructions()

### propertyIsEnumerable

()
method

`AS3 function propertyIsEnumerable(p:String):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Checks whether the property `p` is in the set of properties that can be iterated in a `for..in` statement applied to the XMLList object. This is `true` only if `toNumber(p)` is greater than or equal to 0 and less than the length of the XMLList object.

Parameters

| `p:String` — The index of a property to check.

Returns

| `Boolean` — If the property can be iterated in a `for..in` statement, then `true`; otherwise `false`.

Learn more

XMLList objects

### text

()
method

`AS3 function text():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Calls the `text()` method of each XML object and returns an XMLList object that contains the results.

Returns

| `XMLList` — An XMLList object of all XML properties of the XMLList object that represent XML text nodes.

Learn more

XMLList objects

Related API Elements

XML.text()

### toString

()
method

`AS3 function toString():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns a string representation of all the XML objects in an XMLList object. The rules for this conversion depend on whether the XML object has simple content or complex content:

- If the XML object has simple content, `toString()` returns the string contents of the XML object with the following stripped out: the start tag, attributes, namespace declarations, and end tag.

- If the XML object has complex content, `toString()` returns an XML encoded string representing the entire XML object, including the start tag, attributes, namespace declarations, and end tag.

To return the entire XML object every time, use the `toXMLString()` method.

Returns

| `String` — The string representation of the XML object.

More examples

XML type conversion

Learn more

XMLList objects

Related API Elements

hasComplexContent()
hasSimpleContent()
toXMLString()
Example ( How to use this example )
The following example shows what the `toString()` method returns when the XML object has simple content:
Copy

    var test:XML = <type name="Joe">example</type>;
    trace(test.toString()); //example

The following example shows what the `toString()` method returns when the XML object has complex content:
Copy

    var test:XML =
    <type name="Joe">
        <base name="Bob"></base>
        example
    </type>;
    trace(test.toString());
      // <type name="Joe">
      // <base name="Bob"/>
      // example
      // </type>

### toXMLString

()
method

`AS3 function toXMLString():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns a string representation of all the XML objects in an XMLList object. Unlike the `toString()` method, the `toXMLString()` method always returns the start tag, attributes, and end tag of the XML object, regardless of whether the XML object has simple content or complex content. (The `toString()` method strips out these items for XML objects that contain simple content.)

Returns

| `String` — The string representation of the XML object.

More examples

XML type conversion

Learn more

XMLList objects

Related API Elements

toString()

### valueOf

()
method

`AS3 function valueOf():XMLList`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9

Returns the XMLList object.

Returns

| `XMLList` — Returns the current XMLList object.

Learn more

XMLList objects
Examples How to use this example
XMLListExample.as
The following example creates an XML property named `books` and adds several items with `book publisher` and `name` tags to a node named `books`. Then the `showBooksByPublisher()` method is called, which takes the XMLList and returns each item matching the publisher, "Addison-Wesley."
Copy

    package {
        import flash.display.Sprite;

        public class XMLListExample extends Sprite {
            private var books:XML;

            public function XMLListExample() {
                books =    <books>
                            <book publisher="Addison-Wesley" name="Design Patterns" />
                            <book publisher="Addison-Wesley" name="The Pragmatic Programmer" />
                            <book publisher="Addison-Wesley" name="Test Driven Development" />
                            <book publisher="Addison-Wesley" name="Refactoring to Patterns" />
                            <book publisher="O'Reilly Media" name="The Cathedral & the Bazaar" />
                            <book publisher="O'Reilly Media" name="Unit Test Frameworks" />
                        </books>;

                showBooksByPublisher("Addison-Wesley");
            }

            private function showBooksByPublisher(name:String):void {
                var results:XMLList = books.book.(@publisher == name);
                showList(results);
            }

            private function showList(list:XMLList):void {
                var item:XML;
                for each(item in list) {
                    trace("item: " + item.toXMLString());
                }
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00