List

List

An R-style list with optional names. Callers can get/set individual elements by positional index or name. Operations like slicing and combining will apply to both the values and names.

The List defines methods for the following generics:

We explicitly allow duplicates in the names to avoid errors when slicing or combining. Otherwise, it would be impossible to construct a slice with duplicate indices or to combine multiple List instances with shared names.

Constructors of List subclasses should be callable with no arguments, possibly creating an empty object with no properties. This will be used by the _bioconductor_CLONE, _bioconductor_SLICE and _bioconductor_COMBINE methods to return an instance of the subclass.

Constructor

new List(values, optionsopt)

Source:
Parameters:
Name Type Attributes Default Description
values Array | Map | Object

Elements of the List. For Maps or objects, the values (in order of iteration) are used as the List elements. If no argument is supplied, it defaults to an empty Array.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
names Array <optional>
<nullable>
 null

An array of strings containing the names of the List elements. If provided, this should be of the same length as values. If values is a Map or object, names should have the same keys. If values is an array, the names may contain duplicate strings. If null and values is an array, the List will be unnamed.

Classes

List

Methods

delete(i, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
i string | number

Index or name of the List element to delete. Numbers are passed to deleteByIndex and strings are passed to deleteByName.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after deleting the i-th element. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

deleteByIndex(i, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
i number

Index of the List element to delete. This should be non-negative and no less than length.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
name string <optional>
<nullable>
 null

See the argument of the same name in setByName.
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after deleting the i-th element. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

deleteByName(name) → {List}

Source:
Parameters:
Name Type Attributes Default Description
name string

Name of the List element to delete. This should already exist in names.
options.name string <optional>
<nullable>
 null

See the argument of the same name in setByName.
options.inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after deleting the named element. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

get(i)

Source:
Parameters:
Name Type Description
i string | number

Index or name of the List element to retrieve. Numbers are passed to getByIndex and strings are passed to getByName.
Returns:

The List element at/for i.

getByIndex(i)

Source:
Parameters:
Name Type Description
i number

Index of the List element to retrieve. This should be non-negative and less than length.
Returns:

The i-th List element.

getByName(name)

Source:
Parameters:
Name Type Description
name string

Name of the List element to retrieve. This should be present in names.
Returns:

The List element corresponding to name. If duplicates of name are present in the list, the first occurrence is returned.

has(name) → {boolean}

Source:
Parameters:
Name Type Description
name string

Name of a List element.
Returns:

Whether the name exists in this List.

Type
boolean

length() → {number}

Source:
Returns:

Length of the list.

Type
number

names() → (nullable) {Array}

Source:
Returns:

Array of names of the List elements, or null if the List is unnamed.

Type
Array

nameToIndex(name) → {number}

Source:
Parameters:
Name Type Description
name string

Name of a List element.
Returns:

Index of the name in names. If duplicate names are present, the first occurrence is returned. If the name is not present, -1 is returned.

Type
number

set(i, x, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
i string | number

Index or name of the list element to set. Numbers are passed to setByIndex and strings are passed to setByName.
x *

Value of a List element.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
name string <optional>
<nullable>
 null

See the argument of the same name in setByName. Only used if i is a number.
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after setting the i-th element to x. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

setByIndex(i, x, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
i number

Index of the List element to set. This should be non-negative and no greater than length. If i is less than length, the i-th element is replaced by x. If i is equal to length, x is appended to the end of the list.
x *

Value of a List element.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
name string <optional>
<nullable>
 null

Name for the List element at i. If i is less than length, the name of the i-th element is replaced by name. If i is equal to length, the name of the newly-appended element is set to name. If the List did not previously have any names, the names of all other elements are set to an empty string.
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after setting the i-th element to x. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

setByName(name, x, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
name string

Name of the List element to set. If this already exists in names, the corresponding element is replaced by x. Otherwise, x is appended to the List with the name name. If the List did not previously have any names, the names of all other elements are set to an empty string.
x *

Value of a List element.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after setting the named entry to x. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

setNames(namesnullable, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
names Array <nullable>

Array of strings of length equal to length. This may contain duplicates. Alternatively null, to remove existing names.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

The List after replacing the names with names. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

sliceIndices(indices, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
indices Array

Array of numbers or strings specifying the List elements to retain in the slice. Numbers are interpreted as positional indices while strings are interpreted as names.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

A List containing the specified elements in indices. If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

sliceRange(start, end, optionsopt) → {List}

Source:
Parameters:
Name Type Attributes Default Description
start number

Index of the first element in the slice.
end number

Index past the last element in the slice.
options Object <optional>
 {}

Further options.

Properties
Name Type Attributes Default Description
inPlace boolean <optional>
 false

Whether to modify this List instance in place. If false, a new instance is returned.
Returns:

A List that is sliced to [start, end). If inPlace = true, this is a reference to the current instance, otherwise a new instance is created and returned.

Type
List

toArray() → {Array}

Source:
Returns:

Array of values, equivalent to values.

Type
Array

toMap() → {Map}

Source:
Returns:

Map of name-value pairs. If duplicate names are present, only the value for the first occurrence is reported. If the List is unnamed, an error is thrown.

Type
Map

toObject() → {Object}

Source:
Returns:

Object of name-value pairs. If duplicate names are present, only the value for the first occurrence is reported. If the List is unnamed, an error is thrown.

Type
Object

values() → {Array}

Source:
Returns:

Array containing the List elements.

Type
Array