List

Usage

use List;

This module contains the implementation of the list type.

A list is a lightweight container similar to an array that is suitable for building up and iterating over a collection of elements in a structured manner.

The highly parallel nature of Chapel means that great care should be taken when performing operations that may invalidate references to list elements. Inserts and removals into the middle of a list are example operations that may invalidate references. Appending an element to the end of a list will never invalidate references to elements contained in the list.

The following operations may invalidate references to elements contained in a list:

  • insert
  • remove
  • sort
  • pop
  • clear

Additionally, all references to list elements are invalidated when the list is deinitialized.

Lists are not parallel safe by default, but can be made parallel safe by setting the param formal parSafe to true in any list constructor. When constructed from another list, the new list will inherit the parallel safety mode of its originating list.

Inserts and removals into a list are O(n) worst case and should be performed with care. Appends into a list have an amortized speed of O(1). Indexing into a list is O(1).

proc _checkType(type eltType)

Check that element type is supported by list

record list

A list is a lightweight container suitable for building up and iterating over a collection of elements in a structured manner. Unlike a stack, the list type also supports inserts or removals into the middle of the list. The list type is close in spirit to its Python counterpart, with fast O(1) random access and append operations.

The list type is not parallel safe by default. For situations in which such protections are desirable, parallel safety can be enabled by setting parSafe = true in any list constructor.

Unlike an array, the set of indices of a list is always 1..size.

type eltType

The type of the elements contained in this list.

param parSafe = false

If true, this list will perform parallel safe operations.

proc init(type eltType, param parSafe = false)

Initializes an empty list.

Arguments:
  • eltType – The type of the elements of this list.
  • parSafe : param bool – If true, this list will use parallel safe operations.
proc init(other: list(?t), param parSafe = false)

Initializes a list containing elements that are copy initialized from the elements contained in another list.

Used in new expressions.

Arguments:
  • other – The list to initialize from.
  • parSafe : param bool – If true, this list will use parallel safe operations.
proc init(other: [?d] ?t, param parSafe = false)

Initializes a list containing elements that are copy initialized from the elements contained in an array.

Used in new expressions.

Arguments:
  • other – The array to initialize from.
  • parSafe : param bool – If true, this list will use parallel safe operations.
proc init(other: range(?t), param parSafe = false)

Initializes a list containing elements that are copy initialized from the elements yielded by a range.

Used in new expressions.

Note

Attempting to initialize a list from an unbounded range will trigger a compiler error.

Arguments:
  • other – The range to initialize from.
  • parSafe : param bool – If true, this list will use parallel safe operations.
proc init=(other: this.type .eltTypelist?p)

Initializes a list containing elements that are copy initialized from the elements contained in another list.

Arguments:other – The list to initialize from.
proc init=(other: [?d] this.type .eltType)

Initializes a list containing elements that are copy initialized from the elements contained in an array.

Arguments:other – The array to initialize from.
proc init=(other: range(this.type .eltType, ?b, ?d))

Initializes a list containing elements that are copy initialized from the elements yielded by a range.

Note

Attempting to initialize a list from an unbounded range will trigger a compiler error.

Arguments:other : range(this.type.eltType) – The range to initialize from.
proc ref append(in x: eltType)

Add an element to the end of this list.

Arguments:x : eltType – An element to append.
proc contains(x: eltType): bool

Returns true if this list contains an element equal to the value of x, and false otherwise.

Arguments:x : eltType – An element to search for.
Returns:true if this list contains x.
Return type:bool
proc ref first() ref

Returns a reference to the first item in this list.

Warning

Calling this method on an empty list will cause the currently running program to halt. If the –fast flag is used, no safety checks will be performed.

Returns:A reference to the first item in this list.
Return type:ref eltType
proc ref last() ref

Returns a reference to the last item in this list.

Warning

Calling this method on an empty list will cause the currently running program to halt. If the –fast flag is used, no safety checks will be performed.

Returns:A reference to the last item in this list.
Return type:ref eltType
proc ref extend(other: eltTypelist?p)

Extend this list by appending a copy of each element contained in another list.

Arguments:other : list(eltType) – A list containing elements of the same type as those contained in this list.
proc ref extend(other: [?d] eltType)

Extend this list by appending a copy of each element contained in an array.

Arguments:other : [?d] eltType – An array containing elements of the same type as those contained in this list.
proc ref extend(other: range(eltType, ?b, ?d))

Extends this list by appending a copy of each element yielded by a range.

Note

Attempting to initialize a list from an unbounded range will trigger a compiler error.

Arguments:other : range(eltType) – The range to initialize from.
proc ref insert(idx: int, in x: eltType): bool

Insert an element at a given position in this list, shifting all elements currently at and following that index one to the right. The call a.insert(1, x) inserts an element at the front of the list a, and a.insert((a.size + 1), x) is equivalent to a.append(x).

If the insertion is successful, this method returns true. If the given index is out of bounds, this method does nothing and returns false.

Warning

Inserting an element into this list may invalidate existing references to the elements contained in this list.

Arguments:
  • idx : int – The index into this list at which to insert.
  • x : eltType – The element to insert.
Returns:

true if x was inserted, false otherwise.
Return type:

bool
proc ref insert(idx: int, arr: [?d] eltType): bool

Insert an array of elements arr into this list at index idx, shifting all elements at and following the index arr.size positions to the right.

If the insertion is successful, this method returns true. If the given index is out of bounds, this method does nothing and returns false.

Warning

Inserting elements into this list may invalidate existing references to the elements contained in this list.

Arguments:
  • idx : int – The index into this list at which to insert.
  • arr – An array of elements to insert.
Returns:

true if arr was inserted, false otherwise.
Return type:

bool
proc ref insert(idx: int, lst: list(eltType)): bool

Insert a list of elements lst into this list at index idx, shifting all elements at and following the index lst.size positions to the right.

If the insertion is successful, this method returns true. If the given index is out of bounds, this method does nothing and returns false.

Warning

Inserting elements into this list may invalidate existing references to the elements contained in this list.

Arguments:
  • idx : int – The index into this list at which to insert.
  • lst : list(eltType) – A list of elements to insert.
Returns:

true if lst was inserted, false otherwise.
Return type:

bool
proc ref remove(x: eltType, count: int = 1): int

Remove the first count elements from this list with values equal to x, shifting all elements following the removed item left.

If the count of elements to remove is less than or equal to zero, then all elements from this list equal to the value of x will be removed.

Warning

Removing elements from this list may invalidate existing references to the elements contained in this list.

Arguments:
  • x : eltType – The value of the element to remove.
  • count : int – The number of elements to remove.
Returns:

The number of elements removed.
Return type:

int
proc ref pop(): eltType

Remove the element at the end of this list and return it.

Warning

Popping an element from this list will invalidate any reference to the element taken while it was contained in this list.

Warning

Calling this method on an empty list will cause the currently running program to halt. If the –fast flag is used, no safety checks will be performed.

Returns:The element popped.
Return type:eltType
proc ref pop(idx: int): eltType

Remove the element at the index idx from this list and return it. The elements at indices after idx are shifted one to the left in memory, making this operation O(n).

Warning

Popping an element from this list will invalidate any reference to the element taken while it was contained in this list.

Warning

Calling this method on an empty list or with values of idx that are out of bounds will cause the currently running program to halt. If the –fast flag is used, no safety checks will be performed.

Arguments:idx : int – The index of the element to remove.
Returns:The element popped.
Return type:eltType
proc ref clear()

Clear the contents of this list.

Warning

Clearing the contents of this list will invalidate all existing references to the elements contained in this list.

proc indexOf(x: eltType, start: int = 1, end: int = 0): int

Return a one-based index into this list of the first item whose value is equal to x. If no such element can be found this method returns the value -1.

Warning

Calling this method on an empty list or with values of start or end that are out of bounds will cause the currently running program to halt. If the –fast flag is used, no safety checks will be performed.

Arguments:
  • x : eltType – An element to search for.
  • start : int – The start index to start searching from.
  • end : int – The end index to stop searching at. A value less than or equal to 0 will search the entire list.
Returns:

The index of the element to search for, or -1 on error.
Return type:

int
proc count(x: eltType): int

Return the number of times a given element is found in this list.

Arguments:x : eltType – An element to count.
Returns:The number of times a given element is found in this list.
Return type:int
proc ref sort(comparator: ?rec = Sort.defaultComparator)

Sort the items of this list in place using a comparator. If no comparator is provided, sort this list using the default sort order of its elements.

Warning

Sorting the elements of this list may invalidate existing references to the elements contained in this list.

Arguments:comparator – A comparator used to sort this list.
proc ref this(i: int) ref

Index this list via subscript. Returns a reference to the element at a given index in this list.

Arguments:i – The index of the element to access.

Warning

Use of the this method with an out of bounds index (while bounds checking is on) will cause the currently running program to halt.

Returns:An element from this list.
proc this(i: int) const ref
iter these() ref

Iterate over the elements of this list.

Yields:A reference to one of the elements contained in this list.
proc readWriteThis(ch: channel) throws

Write the contents of this list to a channel.

Arguments:ch – A channel to write to.
proc isEmpty(): bool

Returns true if this list contains zero elements.

Returns:true if this list is empty.
Return type:bool
proc size

The current number of elements contained in this list.

proc indices

Returns the list’s legal indices as the range 1..this.size.

Returns:1..this.size
Return type:range
proc toArray(): [] eltType

Returns a new DefaultRectangular array containing a copy of each of the elements contained in this list.

Returns:A new DefaultRectangular array.
proc =(ref lhs: ?tlist?, rhs: tlist?)

Clear the contents of this list, then extend this now empty list with the elements contained in another list.

Warning

This will invalidate any references to elements previously contained in lhs.

Arguments:
  • lhs – The list to assign to.
  • rhs – The list to assign from.
proc ==(a: ?tlist?, b: tlist?): bool

Returns true if the contents of two lists are the same.

Arguments:
  • a – A list to compare.
  • b – A list to compare.
Returns:

true if the contents of two lists are equal.
Return type:

bool
proc !=(a: ?tlist?, b: tlist?): bool

Return true if the contents of two lists are not the same.

Arguments:
  • a – A list to compare.
  • b – A list to compare.
Returns:

true if the contents of two lists are not equal.
Return type:

bool