Sequences Basic types Collections

A tuple is a typed linked list. Each instance of `Tuple` represents the value and type of a single link. The attributes `first` and `rest` allow us to retrieve a value from the list without losing its static type information.

    value point = Tuple(0.0, Tuple(0.0, Tuple("origin", [])));
    Float x = point.first;
    Float y = point.rest.first;
    String label = point.rest.rest.first;

Usually, we abbreviate code involving tuples.

    [Float,Float,String] point = [0.0, 0.0, "origin"];
    Float x = point[0];
    Float y = point[1];
    String label = point[2];

A list of types enclosed in brackets is an abbreviated tuple type. An instance of `Tuple` may be constructed by surrounding a value list in brackets:

    [String,String] words = ["hello", "world"];

The index operator with a literal integer argument is a shortcut for a chain of evaluations of `rest` and `first`. For example, `point[1]` means `point.rest.first`.

A terminated tuple type is a tuple where the type of the last link in the chain is `Empty`. An unterminated tuple type is a tuple where the type of the last link in the chain is `Sequence` or `Sequential`. Thus, a terminated tuple type has a length that is known statically. For an unterminated tuple type only a lower bound on its length is known statically.

Here, `point` is an unterminated tuple:

    String[] labels = ... ;
    [Float,Float,String*] point = [0.0, 0.0, *labels];
    Float x = point[0];
    Float y = point[1];
    String? firstLabel = point[2];
    String[] allLabels = point[2...];

By: Gavin

- `Anything`
  - `Object`
    - `Tuple` ...and other supertypes

- `Tuple`
  - `Object`
    - `Anything`
  - `Sequence`
    - `Iterable`
      - `Category`
    - `Sequential`
      - `List`
        - `Collection`
          - `Iterable`
            - `Category`
        - `Correspondence`
        - `Ranged`
          - `Iterable`
            - `Category`
      - `Ranged`
        - `Iterable`
          - `Category`

no subtypes hierarchy

Initializer
`Tuple(First first, Rest rest)` Parameters: `first` The first element of this tuple. (The head of the linked list.) `rest` A tuple with the elements of this tuple, except for the first element. (The tail of the linked list.)

Attributes
`first` | Source Code `shared actual First first` The first element of this tuple. (The head of the linked list.) Refines `Sequence.first` ultimately refines `Iterable.first`
`last` | Source Code `shared actual Element last` The last element of this tuple. Refines `Sequence.last` ultimately refines `Iterable.last`
`lastIndex` | Source Code `shared actual Integer lastIndex` The index of the last element of the list, or `null` if the list is empty. Always `size>0 then size-1`. Refines `Sequence.lastIndex` ultimately refines `List.lastIndex`
`rest` | Source Code `shared actual Rest rest` A tuple with the elements of this tuple, except for the first element. (The tail of the linked list.) Refines `Sequence.rest` ultimately refines `Iterable.rest`
`size` | Source Code `shared actual Integer size` The number of elements returned by the `Iterable.iterator()` of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates. Refines `Sequence.size` ultimately refines `Iterable.size`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`
Attributes inherited from: `Collection<Element>` `empty`, `permutations`, `string`
Attributes inherited from: `Correspondence<Key,Item>` `keys`
Attributes inherited from: `Iterable<Element,Absent>` `coalesced`, `cycled`, `distinct`, `empty`, `exceptLast`, `first`, `indexed`, `last`, `paired`, `rest`, `size`, `string`
Attributes inherited from: `List<Element>` `first`, `hash`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`
Attributes inherited from: `[Element+]` `empty`, `exceptLast`, `first`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`, `string`
Attributes inherited from: `Element[]` `exceptLast`, `keys`, `rest`, `reversed`, `size`, `string`

Methods
`append` | Source Code `shared actual [First, <Element|Other>*] append<Other>(Other[] elements)` Return a tuple containing the elements of this tuple, followed by the given `elements`. Parameters: `elements` The list of elements to be appended. Refines `Sequence.append` ultimately refines `Sequential.append`
`clone` | Source Code `shared actual Tuple<Element,First,Rest> clone()` This tuple. Refines `Sequence.clone` ultimately refines `Collection.clone`
`contains` | Source Code `shared actual Boolean contains(Object element)` Determine if the given value is an element of this tuple. Refines `Sequence.contains` ultimately refines `Category.contains`
`getFromFirst` | Source Code `shared actual Element? getFromFirst(Integer index)` The `index`th element returned by an iterator of this stream, or `null` if there are fewer than `index+1` elements in the stream. For a stream with an unstable iteration order, a different value might be produced each time `getFromFirst(index)` is called for a given integer `index`. Refines `List.getFromFirst` ultimately refines `Iterable.getFromFirst`
`iterator` | Source Code `shared actual Iterator<Element> iterator()` An iterator for the elements belonging to this stream. If this is a nonempty stream with type `{Element+}`, the iterator must produce at least one element. Refines `List.iterator` ultimately refines `Iterable.iterator`
`measure` | Source Code `shared actual Element[] measure(Integer from, Integer length)` Obtain a measure containing the mapped values starting from the given starting index, with the given `length`. If `length<=0`, the resulting measure is empty. For any ranged stream `r`, `r.measure(from, length)` may be written using the measure operator:
    r[from:length]
The measure should contain the given number of elements of this stream, starting from the element at the given starting index, in the same order as they are produced by the `Iterable.iterator()` of the stream. In the case where the iterator would be exhausted before `length` elements are produced, the resulting measure contains only those elements which were produced before the iterator was exhausted, and the length of the measure is less then the given `length`. When the given index does not belong to this ranged object, the behavior is implementation dependent. Refines `Sequence.measure` ultimately refines `Ranged.measure`
`span` | Source Code `shared actual Element[] span(Integer from, Integer end)` Obtain a span containing the elements between the two given indices. For any ranged stream `r`, `r.span(from, to)` may be written using the span operator:
    r[from..to]
The span should contain elements of this stream, starting from the element at the given starting index, and ending with the element at the given ending index, in the same order as they are produced by the `Iterable.iterator()` of the stream, except when the ending index occurs earlier than the starting index, in which case they occur in the opposite order. When one or both of the given indices does not belong to this ranged stream, the behavior is implementation dependent. Refines `Sequence.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual Element[] spanFrom(Integer from)` Obtain a span containing the elements between the given starting index and the last index of this ranged object. For any ranged stream `r`, `r.spanFrom(from)` may be written using the span operator:
    r[from...]
The span should contain elements of this stream, starting from the element at the given starting index, in the same order as they are produced by the `Iterable.iterator()` of the stream. When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines `Sequence.spanFrom` ultimately refines `Ranged.spanFrom`
`spanTo` | Source Code `shared actual Element[] spanTo(Integer to)` Obtain a span containing the elements between the first index of this ranged stream and given end index. For any ranged stream `r`, `r.spanTo(to)` may be written using the span operator:
    r[...to]
The span should contain elements of this stream, up to the element at the given ending index, in the same order as they are produced by the `Iterable.iterator()` of the stream. When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines `Sequence.spanTo` ultimately refines `Ranged.spanTo`
`tuple` | Source Code `shared actual Tuple<Element,First,Rest> tuple()` A `Tuple` with the same elements as this sequence. This operation makes it possible to narrow this sequence to a given static length, for example:
    assert (is String[3] bits
               = string.split('/'.equals)
                       .sequence()
                       .tuple);
    value [prefix, middle, postfix] = bits;
Since 1.3.3 Refines `Sequence.tuple` ultimately refines `Sequential.tuple`
`withLeading` | Source Code `shared actual Tuple<Element|Other,Other,Tuple<Element,First,Rest>> withLeading<Other>(Other element)` Return a new tuple that starts with the specified `element`, followed by the elements of this tuple. Parameters: `element` The first element of the resulting tuple. Refines `Sequence.withLeading` ultimately refines `Sequential.withLeading`
`withTrailing` | Source Code `shared actual [First, <Element|Other>+] withTrailing<Other>(Other element)` Return a new tuple containing the elements of this tuple, followed by the given `element`. Parameters: `element` The last element of the resulting tuple. Refines `Sequence.withTrailing` ultimately refines `Sequential.withTrailing`

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Collection<Element>` `clone()`, `combinations()`, `contains()`
Methods inherited from: `Correspondence<Key,Item>` `defines()`, `definesAny()`, `definesEvery()`, `get()`, `getAll()`
Methods inherited from: `Iterable<Element,Absent>` `any()`, `by()`, `chain()`, `collect()`, `contains()`, `count()`, `defaultNullElements()`, `each()`, `every()`, `filter()`, `find()`, `findLast()`, `flatMap()`, `fold()`, `follow()`, `frequencies()`, `getFromFirst()`, `group()`, `indexes()`, `interpose()`, `iterator()`, `locate()`, `locateLast()`, `locations()`, `longerThan()`, `map()`, `max()`, `narrow()`, `partition()`, `product()`, `reduce()`, `repeat()`, `scan()`, `select()`, `sequence()`, `shorterThan()`, `skip()`, `skipWhile()`, `sort()`, `spread()`, `summarize()`, `tabulate()`, `take()`, `takeWhile()`
Methods inherited from: `List<Element>` `clone()`, `collect()`, `contains()`, `defines()`, `endsWith()`, `equals()`, `find()`, `findLast()`, `firstIndexWhere()`, `get()`, `getFromFirst()`, `getFromLast()`, `indexesWhere()`, `initial()`, `iterator()`, `lastIndexWhere()`, `longerThan()`, `mapElements()`, `measure()`, `patch()`, `repeat()`, `shorterThan()`, `slice()`, `span()`, `spanFrom()`, `spanTo()`, `startsWith()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`
Methods inherited from: `Ranged<Index,Element,Subrange>` `measure()`, `span()`, `spanFrom()`, `spanTo()`
Methods inherited from: `[Element+]` `append()`, `clone()`, `collect()`, `contains()`, `find()`, `findLast()`, `indexes()`, `longerThan()`, `measure()`, `prepend()`, `repeat()`, `sequence()`, `shorterThan()`, `slice()`, `sort()`, `span()`, `spanFrom()`, `spanTo()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `tuple()`, `withLeading()`, `withTrailing()`
Methods inherited from: `Element[]` `append()`, `clone()`, `initial()`, `prepend()`, `repeat()`, `sequence()`, `slice()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`, `tuple()`, `withLeading()`, `withTrailing()`