►Rebellion
▼4 Collections
On this page:
association-list?
association-list
association-list-size
association-list-ref
association-list-keys
association-list-unique-keys
association-list-values
association-list-entries
association-list-contains-key?
association-list-contains-value?
association-list-contains-entry?
association-list->hash
empty-association-list
empty-association-list?
nonempty-association-list?
8.16.0.1
  top  contents    up   

4.11 Association Lists🔗ℹ

 (require rebellion/collection/association-list)
  package: rebellion

An association list is a collection of key-value mappings, where multiple values for the same key are allowed. Distinct key-value mappings are unordered, but order is preserved for mappings with the same key. The implementation of association lists behaves similarly to a hash mapping keys to nonempty lists, but the interface is based on a single flattened collection of key-value pairs.

procedure

(association-list? v) → boolean?

  v : any/c
A predicate for association lists.

procedure

(association-list k v ... ...) → association-list?

  k : any/c
  v : any/c
Constructs an association list containing a mapping from each k to each v. Duplicate keys are allowed, and their relative order determines the order of the values in the association list. The relative order of mappings for distinct keys is insignificant. Two association lists are equal if they contain the same key-value mappings and if their values for each key are in the same order.

Examples:
> (define assoc
    (association-list 'weasley 'fred
                      'weasley 'george
                      'potter 'harry
                      'granger 'hermione
                      'weasley 'ron
                      'potter 'lily))
> (association-list-ref assoc 'weasley)

'#(fred george ron)

> (association-list-keys assoc)

(multiset 'granger 'weasley 'weasley 'weasley 'potter 'potter)

> (association-list-contains-value? assoc 'harry)

#t

procedure

(association-list-size assoc) → natural?

  assoc : association-list?
Returns the number of key-value mappings in assoc. Note that this does not return the number of distinct keys in assoc — mappings for the same key and duplicate mappings both contribute to the returned size.

Examples:
> (association-list-size (association-list 'a 1 'b 2))

2

> (association-list-size (association-list 'a 1 'a 2 'a 3))

3

> (association-list-size (association-list 'a 1 'a 1 'a 1))

3

procedure

(association-list-ref assoc k) → immutable-vector?

  assoc : association-list?
  k : any/c
Returns the values mapped by k in assoc. The order of the mappings in assoc is reflected in the order of the returned values, and duplicate mappings are preserved. If assoc does not contain k, returns an empty vector.

Examples:
> (association-list-ref (association-list 'a 1 'b 2) 'a)

'#(1)

> (association-list-ref (association-list 'a 1 'b 2 'a 3) 'a)

'#(1 3)

> (association-list-ref (association-list 'a 1 'b 2 'b 2) 'b)

'#(2 2)

> (association-list-ref (association-list 'a 1 'a 1) 'a)

'#(1 1)

procedure

(association-list-keys assoc) → multiset?

  assoc : association-list?
Returns a multiset containing the keys in assoc. Duplicates are preserved, so the size of the returned multiset is equal to the size of assoc.

Examples:
> (association-list-keys (association-list 'a 1 'b 2 'c 3))

(multiset 'a 'b 'c)

> (association-list-keys (association-list 'a 1 'a 2 'a 3))

(multiset 'a 'a 'a)

> (association-list-keys (association-list 'a 1 'a 1 'b 2 'b 2 'c 3))

(multiset 'a 'a 'b 'b 'c)

procedure

(association-list-unique-keys assoc) → set?

  assoc : association-list?
Returns a set containing the keys in assoc, without duplicates.

Examples:
> (association-list-unique-keys (association-list 'a 1 'b 2 'c 3))

(set 'c 'b 'a)

> (association-list-unique-keys (association-list 'a 1 'b 2 'a 3))

(set 'b 'a)

procedure

(association-list-values assoc) → immutable-vector?

  assoc : association-list?
Returns a vector containing the values in assoc in a partially unspecified order. Values mapped by the same key occur next to each other in the returned vector and their relative order is preserved, but no order is preserved between values mapped by different keys. Duplicates are preserved as well, so the length of the returned vector is equal to the size of assoc.

Examples:
> (association-list-values (association-list 'a 1 'b 2 'c 3 'a 1 'a 3 'c 2))

'#(3 2 2 1 1 3)

> (association-list-values (association-list 'a 1 'a 1 'a 1))

'#(1 1 1)

> (association-list-values (association-list 'a 1 'b 2 'a 3 'b 4))

'#(2 4 1 3)

procedure

(association-list-entries assoc)

 → (vectorof entry? #:immutable #true)
  assoc : association-list?
Returns all key-value mappings in assoc, as an immutable vector of entries. The same ordering guarantees as association-list-values apply to the returned entries.

Example:
> (association-list-entries (association-list 'a 1 'b 2 'a 3 'c 4))

(vector (entry 'c 4) (entry 'b 2) (entry 'a 1) (entry 'a 3))

procedure

(association-list-contains-key? assoc k) → boolean?

  assoc : association-list?
  k : any/c
Returns #true if assoc contains any mappings for the key k, returns #false otherwise.

Examples:
> (define assoc (association-list 'a 1 'b 2 'c 3 'a 4))
> (association-list-contains-key? assoc 'a)

#t

> (association-list-contains-key? assoc 'banana)

#f

procedure

(association-list-contains-value? assoc v) → boolean?

  assoc : association-list?
  v : any/c
Returns #true if assoc contains any mappings with the value v, returns #false otherwise.

Examples:
> (define assoc (association-list 'a 1 'b 2 'c 3 'a 4))
> (association-list-contains-key? assoc 3)

#f

> (association-list-contains-key? assoc 10)

#f

procedure

(association-list-contains-entry? assoc e) → boolean?

  assoc : association-list?
  e : entry?
Returns #true if assoc contains a mapping equal to e, returns #false otherwise.

Examples:
> (define assoc (association-list 'a 1 'b 2 'c 3 'a 4))
> (association-list-contains-entry? assoc (entry 'a 4))

#t

> (association-list-contains-entry? assoc (entry 'a 2))

#f

> (association-list-contains-entry? assoc (entry 'c 1))

#f

procedure

(association-list->hash assoc)

 → 
(hash/c any/c nonempty-immutable-vector?
        #:immutable #true)
  assoc : association-list?
Converts assoc into a hash table mapping keys to immutable vectors of their values.

Example:
> (association-list->hash
   (association-list 'a 1
                     'b 2
                     'c 3
                     'b 4
                     'b 5
                     'c 6
                     'a 7))

'#hash((a . #(1 7)) (b . #(2 4 5)) (c . #(3 6)))

value

empty-association-list : empty-association-list?

The empty association list, which contains no key-value mappings.

procedure

(empty-association-list? v) → boolean?

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

procedure

(nonempty-association-list? v) → boolean?

  v : any/c
A predicate for nonempty association lists. Implies association-list?.

  top  contents    up