Playground
(Lispex)
ENRUKO

List Operations

Built-in functions for creating, reading, and transforming lists in Lispex.

This is an earlier edition of the documentation. To look up how to create and read lists, open the current List and Aggregate Procedures.

This page provides a reference for built-in functions that create or manipulate lists in Lispex. These complement the functions found in the Core Functions reference.

cons

Constructs a new list by adding an element to the front of an existing list. "Cons" is short for "construct".

  • Syntax: (cons ELEMENT LIST)
  • Arguments:
    • ELEMENT: The new element to add to the front.
    • LIST: The existing list to which the element will be added.
  • Returns: A new list.
  • Throws: A RuntimeError if the second argument is not a list.

Example:

LISPEX
(cons 1 (list 2 3 4))
;; Result: (list 1 2 3 4)

(cons (list "a") (list "b" "c"))
;; Result: (list (list "a") "b" "c")

append

Appends two lists together to create a new, single list.

  • Syntax: (append LIST_1 LIST_2)
  • Arguments:
    • LIST_1: The first list.
    • LIST_2: The second list.
  • Returns: A new list containing all elements from LIST_1 followed by all elements from LIST_2.
  • Throws: A RuntimeError if either argument is not a list.

Example:

LISPEX
(append (list 1 2) (list 3 4))
;; Result: (list 1 2 3 4)

(append (list) (list 1 2))
;; Result: (list 1 2)

nth

Returns the element at a specific zero-based index in a list.

  • Syntax: (nth LIST INDEX)
  • Arguments:
    • LIST: The list from which to retrieve an element.
    • INDEX: The integer index of the element to retrieve (starting from 0).
  • Returns: The element at the specified index.
  • Throws:
    • A RuntimeError if LIST is not a list or INDEX is not an integer.
    • A RuntimeError if INDEX is out of bounds (less than 0 or greater than or equal to the list's length).

Example:

LISPEX
(define my-list (list "a" "b" "c"))

(nth my-list 0)
;; Result: "a"

(nth my-list 2)
;; Result: "c"

(nth my-list 3)
;; Throws RuntimeError: Index 3 out of bounds

member

Searches a list for an element equal to a given object and returns the sublist that begins at the first match, or #f if none is found. memv and memq perform the same search using eqv? identity instead of deep equal? (in this version eqv? and eq? coincide, so memq behaves like memv).

  • Syntax: (member OBJ LIST)
  • Arguments:
    • OBJ: The object to search for (compared with equal?; memv/memq use eqv?).
    • LIST: The list to search.
  • Returns: The sublist (tail) starting at the first matching element, or #f if absent.
  • Throws: A RuntimeError if LIST is not a proper list.

Example:

LISPEX
(member 2 (list 1 2 3))
;; Result: (list 2 3)

(member 5 (list 1 2 3))
;; Result: #f

assoc

Searches an association list (a list of pairs) for the first pair whose key (its car) equals a given object, and returns that pair, or #f if none is found. assv and assq perform the same lookup using eqv? instead of equal?.

  • Syntax: (assoc OBJ ALIST)
  • Arguments:
    • OBJ: The key to look up (compared with equal?; assv/assq use eqv?).
    • ALIST: An association list whose every entry is a pair.
  • Returns: The first entry pair whose car matches, or #f if absent.
  • Throws: A RuntimeError if ALIST is not a proper list of pairs.

Example:

LISPEX
(assoc 2 (list (list 1 "one") (list 2 "two")))
;; Result: (list 2 "two")

(assoc 9 (list (list 1 "one")))
;; Result: #f

list-tail

Returns the sublist obtained by dropping the first K elements of LST. That is the K-th cdr. The result shares structure with LST rather than copying it. It is an error if LST has fewer than K elements.

  • Syntax: (list-tail LST K)
  • Arguments:
    • LST: A list.
    • K: A non-negative integer no greater than the length of LST.
  • Returns: The sublist after the first K elements (LST itself when K is 0).
  • Throws: A RuntimeError if K is negative or greater than the length of LST.

Example:

LISPEX
(list-tail (list 1 2 3 4) 2)
;; Result: (list 3 4)

list-copy

Returns a shallow copy of LST, a fresh chain of pairs holding the same elements. The copy is not eq? to the original, but its elements are shared rather than duplicated. A non-list object is returned unchanged.

  • Syntax: (list-copy LST)
  • Arguments:
    • LST: A list (or any object).
  • Returns: A newly allocated copy of the list, sharing its elements.

Example:

LISPEX
(list-copy (list 1 2 3))
;; Result: (list 1 2 3)