Skip to main content
Pentaho Documentation

Collection

pentaho.lang.Collection

The Collection class is an abstract base class for typed, ordered maps.

Remarks

A collection is a list whose elements can only be contained in one position. If an attempt is made to add a duplicate element to the collection, an error is thrown.

Additionally, collection elements can be accessed by their key, and not only by position.

Elements of a collection must implement the pentaho.lang.ICollectionElement interface.

AMD Module

require(["pentaho/lang/Collection"], function(Collection) { /* code goes here */ });

Extends

Constructor

Name Description
new Collection(keyArgs)
 
Abstract

Initializes a collection instance.

Members

Name Description
elemClass : Class
 
Abstract

Gets the constructor function of the elements held by this collection.

length : number

The length of the list.

missingValue : any

Gets the value returned by pentaho.lang.Collection#get when an element with a given key is not contained in the collection.

Methods

Name Description
_getElemName() : string
 
Protected

Gets a common name for the elements held by this list.

add(elem, keyArgs) : pentaho.lang.IListElement

Appends an element to the list and returns it.

addMany(elems, keyArgs) : number

Appends elements to the list and returns its new length.

get(key, assertExists) : pentaho.lang.ICollectionElement | *

Gets an element by its key.

getExisting(key) : pentaho.lang.ICollectionElement

Gets an existing element by its key.

has(key) : boolean

Tests if an element with a given key belongs to the collection.

includes(elem) : boolean

Checks if a given element belongs to the collection.

push(elems) : number

Appends elements to the list and returns its new length.

toSpec() : Array

Creates a specification of this list.

Constructor Details

new Collection(keyArgs)
 
Abstract

Initializes a collection instance.

Note that because a Collection is a sub-class of Array, the new operator cannot be used to create instances (at least up to ECMAScript version 5). Instead, instances of Collection are actually initial instances of Array whose prototype is then changed to be that of Collection. In other words, Collection is an "initialization" constructor (see pentaho.lang.ISpecifiable for more information on these concepts).

Concrete Collection sub-classes should provide a static to method to help in their construction.

Source: javascript/web/pentaho/lang/Collection.js, line 24

Parameters:
Name Default Value Summary
keyArgs : Object
 
Optional

The keyword arguments.

These are not used directly by the Collection class but are passed-through to the methods that handle the initialization of each list element.

Members Details

elemClass: Class
 
Abstract

Gets the constructor function of the elements held by this collection.

This class must implement the pentaho.lang.ICollectionElement interface.

Source: javascript/web/pentaho/lang/Collection.js, line 87

Overrides: pentaho.lang.List#elemClass

length: number

The length of the list.

Source: javascript/web/pentaho/lang/List.js, line 98

Inherited From: pentaho.lang.List#length

missingValue: any

Gets the value returned by pentaho.lang.Collection#get when an element with a given key is not contained in the collection.

Source: javascript/web/pentaho/lang/Collection.js, line 85

Default Value: null

Methods Details

_getElemName() : string
 
Protected

Gets a common name for the elements held by this list.

The default implementation returns the value of pentaho.lang.IListElement#elemName of pentaho.lang.List#elemClass.

Source: javascript/web/pentaho/lang/List.js, line 94

Inherited From: pentaho.lang.List#_getElemName

Returns:
Name Description
string

The common name of the elements.

add(elem, keyArgs) : pentaho.lang.IListElement

Appends an element to the list and returns it.

The value specified in argument elem is converted to the list elements' class before actually being added to it.

Source: javascript/web/pentaho/lang/List.js, line 163

Inherited From: pentaho.lang.List#add

Parameters:
Name Default Value Summary
elem : *

An element or a value convertible to one.

keyArgs : Object
 
Optional

The keyword arguments.

These are not used directly by the List class but are passed-through to the methods that handle the initialization of list elements.

Returns:
Name Description
pentaho.lang.IListElement

The added list element.

addMany(elems, keyArgs) : number

Appends elements to the list and returns its new length.

The values specified in elems are converted to the list elements' class before actually being added to it.

This method allows adding elements to the list using custom options (keyword arguments). Contrast with method pentaho.lang.List#push which adds elements using default options.

Source: javascript/web/pentaho/lang/List.js, line 144

Inherited From: pentaho.lang.List#addMany

Parameters:
Name Default Value Summary
elems : Array

An array of elements to add to the list.

keyArgs : Object
 
Optional

The keyword arguments.

These are not used directly by the List class but are passed-through to the methods that handle the initialization of each list element.

Returns:
Name Description
number

The new length of the list.

get(key, assertExists) : pentaho.lang.ICollectionElement | *

Gets an element by its key.

Source: javascript/web/pentaho/lang/Collection.js, line 181

Parameters:
Name Default Value Summary
key : string
 
Optional

The element's key.

assertExists : boolean
 
Optional
false

Indicates if an error should be thrown when the collection does not contain an element with the given key.

Returns:
Name Description
pentaho.lang.ICollectionElement | *

The element with the given key, if one is contained by the collection, or pentaho.lang.Collection#missingValue, otherwise.

See also:  pentaho.lang.Collection#getExisting

getExisting(key) : pentaho.lang.ICollectionElement

Gets an existing element by its key.

An error is thrown when the collection does not contain an element with the given key.

Source: javascript/web/pentaho/lang/Collection.js, line 204

Parameters:
Name Default Value Summary
key : string
 
Optional

The element's key.

Returns:
Name Description
pentaho.lang.ICollectionElement

The element with the given key.

See also:  pentaho.lang.Collection#get

has(key) : boolean

Tests if an element with a given key belongs to the collection.

Source: javascript/web/pentaho/lang/Collection.js, line 161

Parameters:
Name Default Value Summary
key : string
 
Optional

The element's key.

Returns:
Name Description
boolean

true if an element with the given key belongs to the collection, false otherwise.

includes(elem) : boolean

Checks if a given element belongs to the collection.

Source: javascript/web/pentaho/lang/Collection.js, line 147

Parameters:
Name Default Value Summary
elem : pentaho.lang.IWithKey
 
Optional

The element to check.

Returns:
Name Description
boolean

true if the element is belongs to the collection, false otherwise.

push(elems) : number

Appends elements to the list and returns its new length.

The values specified in elems are converted to the list elements' class before actually being added to it.

This method adds elements to the list using default options. Use one of pentaho.lang.List#add or pentaho.lang.List#addMany to be able to specify non-default options (keyword arguments).

Source: javascript/web/pentaho/lang/List.js, line 121

Inherited From: pentaho.lang.List#push

Parameters:
Name Default Value Summary
elems : *
 
Repeatable

The elements to add to the list.

Returns:
Name Description
number

The new length of the list.

toSpec() : Array

Creates a specification of this list.

A list specification is an array containing the specifications of each of its elements.

If the element's class does not implement pentaho.lang.ISpecifiable, each element is assumed to be its own specification.

Source: javascript/web/pentaho/lang/List.js, line 249

Inherited From: pentaho.lang.List#toSpec

Returns:
Name Description
Array

The list specification.