Pair Type

Pairs are the primary compound type. A pair is a value with references to two other values called the head and tail.

A pair is printed as (head & tail).

If the tail references another pair then you can envisage a chain forming, more commonly called a list.

Lists

Lists are an emergent property of chained pairs and are commonly written and printed without superfluous chaining punctuation so:

(e1 & (e2 & (e3 & #n)))

is the more convenient:

(e1 e2 e3)

If the tail of the last element of the list is not #n then the list is an improper list and is printed as:

(e1 e2 & e3)

This form is commonly used in the formals of a function definition to denote a varargs parameter, that is, bundle any remaining arguments up into a list.

When the evaluator sees a list it interprets it as a function call. However, if you simply want to create a list variable you need to quote the list to prevent the evaluator processing it as a function call:

my-list := '(1 2 3)

Superficially, with “only the head to play with”, lists seem relatively limited. However, the structure pointed to by the head can be arbitrarily complex.

Association Lists

One simple form of that complexity is if the head is itself a list.

This is called an association list where there are a number of functions that will walk over the (top-level) list looking for a key matching the first element of one of the sub-lists which it will return:

al := '((#\a "apple" 'fruit)
        (#\b "banana" 'fruit)
        (#\c "carrot" 'vegetable))

assq #\b al          ; '(#\b "banana" 'fruit)

Pair Predicates

function pair? o

test if o is a pair

Param o:

object to test

Return:

#t if o is a pair, #f otherwise

function list? v

Is v a list?

Param v:

value to test

Return:

any

Rtype:

boolean

Pair Constructors

function pair h t

create a pair from h and t

function list args

return args as a list

Param args:

arguments to convert

Return:

list of args

Rtype:

list

function string->list s

return a list of the Unicode code points in s

Param s:

string

Type s:

string

Return:

list of Unicode code points

Rtype:

list

function array->list a

convert a to a list

Param a:

the array

Type a:

array

Return:

list

Rtype:

list

Pair Attributes

function ph p

return the head of pair p

Param p:

pair to query

Type p:

pair

Return:

head of p

function pt p

return the tail of pair p

Param p:

pair to query

Type p:

pair

Return:

tail of p

function set-ph! p v

set the head of pair p to v

Param p:

pair to modify

Type p:

pair

Param v:

value

Type v:

any

Return:

#<unspec>

function set-pt! p v

set the tail of pair p to v

Param p:

pair to modify

Type p:

pair

Param v:

value

Type v:

any

Return:

#<unspec>

function list-ref x n

return the element of x at position n

Param x:

list to examine

Type x:

list

Param n:

index of element to access

Type n:

integer

function list-tail list pos

Return the list after pos pairs of list

Param list:

list to be examined

Type list:

list

Param pos:

pos

Type pos:

fixnum

Return:

list after pos pairs of list

Rtype:

list

function last-pair list

Return the last pair of list

Param list:

list to be examined

Type list:

list

Return:

last pair of list

Rtype:

pair

function nth l n [default]

return the nth (n) element from list l

Param l:

list

Type orig:

list

Param n:

nth element

Type n:

integer

Param default:

value to return if not found, defaults to #n

Type default:

value, optional

Return:

the element or default

Rtype:

any

nth uses 0-based indexing.

n can be negative to access the n^th from the end of the list with -1 being the last element.

function set-nth! l n val

set the nth (n) element in list l

Param l:

list

Type orig:

list

Param n:

nth element

Type n:

integer

Param val:

value to assign

Type val:

any

Return:

#<unspec>

set-nth! uses 0-based indexing.

n can be negative to set the n^th from the end of the list with -1 being the last element.

Pair Accessors

Following are a number of variations on a theme of accessing elements in a chain of pairs.

The order of hs and ts in the function names reflects the left-to-right ordering of the function calls. For some pXY x you can read as the pX of the pY of x.

function phh p

return (ph (ph p))

Param p:

pair to query

Type p:

pair

Return:

head of the head of p

function phhh p

return (ph (ph (ph p)))

Param p:

pair to query

Type p:

pair

Return:

head of the head of the head of p

function phhhh x

function phhht x

function phht x

function phhth x

function phhtt x

function pht p

return (ph (pt p))

Param p:

pair to query

Type p:

pair

Return:

head of the tail of p

function phth p

return (ph (pt (ph p)))

Param p:

pair to query

Type p:

pair

Return:

head of the tail of the head of p

function phthh x

function phtht x

function phtt p

return (ph (pt (pt p)))

Param p:

pair to query

Type p:

pair

Return:

head of the tail of the tail of p

function phtth p

return (ph (pt (pt (ph p))))

Param p:

pair to query

Type p:

pair

Return:

head of the tail of the tail of the head of p

function phttt x

function pth p

return (pt (ph p))

Param p:

pair to query

Type p:

pair

Return:

tail of the head of p

function pthh x

function pthhh x

function pthht x

function ptht x

function pthth x

function pthtt x

function ptt p

return (pt (pt p))

Param p:

pair to query

Type p:

pair

Return:

tail of the tail of p

function ptth p

return (pt (pt (ph p)))

Param p:

pair to query

Type p:

pair

Return:

tail of the tail of the head of p

function ptthh x

function pttht x

function pttt p

return (pt (pt (pt p)))

Param p:

pair to query

Type p:

pair

Return:

tail of the tail of the tail of p

function pttth x

function ptttt x

Pair Functions

function reverse l

reverse the list l

Param l:

list to reverse

Type l:

list

Return:

reversed list

function reverse! l

reverse the list l destructively

Param l:

list to reverse

Type l:

list

Return:

reversed list

Calling reverse! on a list that others are referencing may have undesired effects:

Idio> lst := '(1 2 3)
(1 2 3)
Idio> reverse! lst
(3 2 1)
Idio> lst
(1)

function length l

return the number of elements in list l

Param l:

list to count

Type l:

list

Return:

number of elements in l

Rtype:

integer

function append [a]

append the lists of a

Param a:

list of lists

Return:

combined list

Rtype:

list

function append! lists

Destructively append lists

Param lists:

lists to be appended

Type lists:

lists

Return:

combined lists

Rtype:

list

function memq k l

return the remainder of the list l from the first incidence of an element eq? k or #f if k is not in l

Param k:

object to search for

Type k:

any

Param l:

list to search in

Type l:

list

Return:

a list starting from k, #f if k is not in l

function memv k l

return the remainder of the list l from the first incidence of an element eqv? k or #f if k is not in l

Param k:

object to search for

Type k:

any

Param l:

list to search in

Type l:

list

Return:

a list starting from k, #f if k is not in l

function member k l

return the remainder of the list l from the first incidence of an element equal? k or #f if k is not in l

Param k:

object to search for

Type k:

any

Param l:

list to search in

Type l:

list

Return:

a list starting from k, #f if k is not in l

function assq k l

return the first entry of association list l with a key eq? k or #f if k is not a key in l

Param k:

object to search for

Type k:

any

Param l:

association list to search in

Type l:

list

Return:

the list (k & value), #f if k is not a key in l

function assv k l

return the first entry of association list l with a key eqv? k or #f if k is not a key in l

Param k:

object to search for

Type k:

any

Param l:

association list to search in

Type l:

list

Return:

the list (k & value), #f if k is not a key in l

function assoc k l

return the first entry of association list l with a key equal? k or #f if k is not a key in l

Param k:

object to search for

Type k:

any

Param l:

association list to search in

Type l:

list

Return:

the list (k & value), #f if k is not a key in l

Last built at 2024-05-17T06:10:56Z+0000 from 62cca4c (dev) for Idio 0.3.b.6