►Rebellion
▼4 Collections
On this page:
empty-list?
nonempty-list?
list-first
list-rest
list-ref-safe
list-size
list-insert
list-contains?
list-append
list-reverse
empty-list
into-list
into-reversed-list
append-into-list
8.12
  top  contents    up   

4.3 Lists🔗ℹ

 (require rebellion/collection/list) package: rebellion

The rebellion/collection/list library is a small wrapper module designed to provide a more modern and conventional interface to standard Racket lists. Additionally, it provides a few utilities for integrating lists with some of Rebellion’s standard abstractions, such as reducers. No attempt is made to wrap every possible list-related function or rename every export of racket/list, as many of these operations are better expressed in terms of generic sequences, for loops, reducers, and transducers rather than lists specifically.

For the purposes of this library, "list" means "proper list". Improper lists (such as those constructed by list*) are a poor fit for most list-related tasks and should be avoided in favor of other data structures.

procedure

(empty-list? v) → boolean?

  v : any/c
A predicate for empty lists. Implies list?.

procedure

(nonempty-list? v) → boolean?

  v : any/c
A predicate for nonempty, proper lists. Implies list? and is mutually exclusive with empty-list?.

procedure

(list-first lst) → list?

  lst : nonempty-list?
Returns the first element of lst. Unlike list-ref-safe, this function does not return an option and instead requires that lst not be empty.

Examples:
> (list-first (list 1 2 3))

1

> (list-first empty-list)

list-first: contract violation

  expected: nonempty-list?

  given: '()

  in: the 1st argument of

      (-> nonempty-list? any/c)

  contract from:

      <pkgs>/rebellion/collection/list.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/collection/list.rkt:11:3

procedure

(list-rest lst) → list?

  lst : nonempty-list?
Removes the first element from lst and returns the list of remaining elements. If lst is empty, a contract failure is raised.

Examples:
> (list-rest (list 1 2 3))

'(2 3)

> (list-rest empty-list)

list-rest: contract violation

  expected: nonempty-list?

  given: '()

  in: the 1st argument of

      (-> nonempty-list? (listof any/c))

  contract from:

      <pkgs>/rebellion/collection/list.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/rebellion/collection/list.rkt:12:3

procedure

(list-ref-safe lst position) → option?

  lst : list?
  position : natural?
Returns an option containing the value at position in lst, or absent if lst is too small to contain an element at position. This operation takes time linear in the length of the list.

Examples:
> (list-ref-safe (list 'a 'b 'c) 0)

(present 'a)

> (list-ref-safe (list 'a 'b 'c) 2)

(present 'c)

> (list-ref-safe (list 'a 'b 'c) 5)

#<absent>

procedure

(list-size lst) → natural?

  lst : list?
Returns the number of elements in lst. This function calls length from racket/base, which may be faster than linear time in certain cases. Nevertheless, do not assume this is a constant-time operation.

Examples:
> (list-size (list 'a 'b 'c))

3

> (list-size empty-list)

0

procedure

(list-insert lst v) → nonempty-list?

  lst : list?
  v : any/c
Inserts v into the front of lst and returns a new, updated list. This is intended to replace cons, but note that the argument order is different to follow the convention of core operations on a data type taking that type as the first argument.

Example:
> (list-insert (list 2 3 4) 1)

'(1 2 3 4)

procedure

(list-contains? lst v) → boolean?

  lst : list?
  v : any/c
Returns #t if lst contains v, returns #f otherwise. This operation takes time linear in the length of the list. Lists are not designed for efficient membership queries, so if you find yourself using this function consider whether you could use a set or multiset instead.

Examples:
> (list-contains? (list 1 2 3 4 5) 2)

#t

> (list-contains? (list 1 2 3 4 5) 1000)

#f

procedure

(list-append lst ...) → list?

  lst : list?
Appends each lst together into a single, flattened list.

Examples:
> (list-append (list 1 2 3) empty-list (list 4 5) (list 6 7 8 9))

'(1 2 3 4 5 6 7 8 9)

> (list-append (list 1 2 3))

'(1 2 3)

> (list-append)

'()

procedure

(list-reverse lst) → list?

  lst : list?
Reverses the order of elements in lst.

Examples:
> (list-reverse (list 1 2 3 4 5))

'(5 4 3 2 1)

> (list-reverse empty-list)

'()

value

empty-list : empty-list? = (list)

The empty list, provided as a constant. Prefer using this constant over writing (list) or '(). The former obscures that a constant value is intended, and the latter unnecessarily requires the reader to understand the subtleties of quotation.

value

into-list : (reducer/c any/c list?)

A reducer that collects elements into a list, preserving their order.

Example:
> (reduce into-list 1 2 3 4 5)

'(1 2 3 4 5)

value

into-reversed-list : (reducer/c any/c list?)

A reducer that collects elements into a list, in reverse order. This can be more efficient than into-list. This function should be preferred over in-list when the order of the returned list doesn’t matter, but in these cases strongly consider using sets or multisets instead of lists to make the lack of order explicit.

Example:
> (reduce into-reversed-list 1 2 3 4 5)

'(5 4 3 2 1)

value

append-into-list : (reducer/c list? list?)

A reducer that collects a sequence of lists into a single list, in the same manner as list-append.

Example:
> (reduce append-into-list
          (list 1 2 3)
          (list 'a 'b)
          empty-list
          (list 4 5 6 7 8))

'(1 2 3 a b 4 5 6 7 8)

  top  contents    up