Collections

Abstract supertype of objects that contain other values, called elements, where it is possible to efficiently determine if a given value is an element. A `Category` may not be finite, and its elements may not even be countable. Thus, unlike streams, the elements of a generic `Category` are not iterable.

`Category` models a mathematical set, but is distinct from the `Set` collection type which represents finite sets.

The `in` operator may be used to determine if a value belongs to a `Category`:

    if (69 in 0..100) { ... }
    assert (key->item in { for (n in 0..100) n.string->n**2 });

An object may be a `Category` of two different disjoint element types. For example, `String` is a `Category` of its `Character`s and of its substrings.

    if ("hello" in "hello world") { ... }
    assert ('.' in string);

Every meaningful `Category` is formed from elements with some equivalence relation. Ordinarily, that equivalence relation is value equality. Thus, ordinarily, `x==y` implies that `x in cat == y in cat`. But this contract is not required since it is possible to form a meaningful `Category` using a different equivalence relation. For example, an `IdentitySet` is a meaningful `Category`, where the equivalence relation is identity equality.

Since `Null` is not considered to have any meaningful equivalence relation, a `Category` may not contain the null value.

Note that even though `Category<Element>` is declared contravariant in its Element, most types that inherit `Category` are covariant in their element type, and therefore satisfy `Category<Object>`, resulting in some loss of typesafety. For such types, `contains()` should return `false` for any value that is not an instance of the element type. For example, `String` is a `Category<Object>`, not a `Category<Character|String>`, and `x in string` evaluates to `false` for every `x` that is not a `String` or `Character`.

By: Gavin

no type hierarchy

no supertypes hierarchy

- `Category`
  - `Iterable`
    - `Collection`
      - `List`
        - `SearchableList`
          - `Array`
          - `String`
          - `StringBuilder`
        - `Sequential`
          - `Empty`
            - `empty`
          - `Sequence`
            - `ArraySequence`
            - `Range`
            - `Singleton`
            - `Tuple`
      - `Map`
        - `emptyMap`
      - `Set`
        - `emptySet`
    - `Ranged`
      - `Array`
      - `Empty`
        - `empty`
      - `List`
        - `SearchableList`
          - `Array`
          - `String`
          - `StringBuilder`
        - `Sequential`
          - `Empty`
            - `empty`
          - `Sequence`
            - `ArraySequence`
            - `Range`
            - `Singleton`
            - `Tuple`
      - `Sequential`
        - `Empty`
          - `empty`
        - `Sequence`
          - `ArraySequence`
          - `Range`
          - `Singleton`
          - `Tuple`
      - `String`
      - `StringBuilder`
    - `References`
    - `Sequence`
      - `ArraySequence`
      - `Range`
      - `Singleton`
      - `Tuple`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`

Methods
`contains` | Source Code `shared formal Boolean contains(Element element)` Returns `true` if the given value belongs to this `Category`, that is, if it is an element of this `Category`, or `false` otherwise. For any instance `c` of `Category`, `c.contains(element)` may be written using the `in` operator:
    element in c
For most `Category`s, the following relationship is satisfied by every pair of elements `x` and `y`: if `x==y`, then `x in category == y in category` However, it is possible to form a useful `Category` consistent with some other equivalence relation, for example `===`. Therefore implementations of `contains()` which do not satisfy this relationship are tolerated. See also `containsEvery()`, `containsAny()`
`containsAny` | Source Code `shared default Boolean containsAny({Element*} elements)` Returns `true` if any one of the given values belongs to this `Category`, or `false` otherwise. See also `contains()`, `containsEvery()`
`containsEvery` | Source Code `shared default Boolean containsEvery({Element*} elements)` Returns `true` if every one of the given values belongs to this `Category`, or `false` otherwise. See also `contains()`, `containsAny()`

Inherited Methods
Methods inherited from: `Object` `equals()`