Standard Library: Collection functions

assoc


[assoc: keys; values]

→ map

Creates a map from a list of keys and a list of values. Each key in keys will be matched with the value at the same index in values.

Parameters

keys ← list
The keys to store in the map.

values ← list
The values to associate with the keys.

Errors

Raises a runtime error if the lengths of keys and values do not match.

Example

# Generate a map of the "Big Five" personality traits
# with random rating values that add up to 50
<$personality = 
  [assoc:
    (ope; con; ext; agr; neu);
    [shred: 50; 5; [rand: 1; 10]] # Use random variance to reduce trait deviation
  ]
>

# Print the values
[whitespace-fmt:verbatim]
"Openness to experience:"   <personality/ope>\n
"Conscientiousness:"        <personality/con>\n
"Extraversion:"             <personality/ext>\n
"Agreeableness:"            <personality/agr>\n
"Neuroticism:"              <personality/neu>\n


##
  EXAMPLE OUTPUT:

  Openness to experience:   7
  Conscientiousness:        11
  Extraversion:             5
  Agreeableness:            12
  Neuroticism:              15
##

augment


[augment: dst-map; src-map]

→ map

Clones dst-map, adds the values from src-map to the values with matching keys on dst-map, then returns the resulting map.

Parameters

dst-map ← map
The map to copy and augment.

src-map ← map
The map containing the values to add to those in dst-map.

augment-self


[augment-self: dst-map; src-map]

Adds the values from src-map to the values with matching keys on dst-map.

Parameters

dst-map ← map
The map to augment.

src-map ← map
The map containing the values to add to those in dst-map.

augment-thru


[augment-thru: dst-map; src-map]

→ map

Adds the values from src-map to the values with matching keys on dst-map, then prints dst-map.

Parameters

dst-map ← map
The map to augment.

src-map ← map
The map containing the values to add to those in dst-map.

chunks


[chunks: collection; count]

→ list

Splits collection into count sub-slices and prints a new list containing the results, making a best-effort to make each chunk the same size.

If the contents of collection don't divide evenly into count chunks, the function will produce larger chunks first, then smaller chunks with the remaining content.

If count is greater than the size of collection, the chunk size will be 1 and the output list will be padded with elements set to <>.

Parameters

collection ← list | string | range
The collection to split into chunks.

count ← int
The number of chunks to produce.

Errors

Raises a runtime error if collection cannot be sliced.

clear


[clear: collection]

Removes all elements from a list or map.

Parameters

collection ← list | map
The collection to clear.

Errors

Causes a runtime error if collection is not a list or map.

fill-self


[fill-self: list; value]

Mutates list in place by replacing every element with value.

fill-thru


[fill-thru: list; value]

Mutates list in place and then prints the same list handle.

list


[list: values*]

→ list

Prints a list containing the arguments.

Parameters

values ← any*
The values to store in the list.

tuple


[tuple: values*]

→ tuple

Prints a tuple containing the arguments.

Parameters

values ← any*
The values to store in the tuple.

nlist


[nlist: values*]

Prints a single-element list whose only value is the list constructed from values.

filter


[filter: list; predicate]

→ list

Runs a predicate function against all items in a list and returns another list containing only the values that the predicate returned @true on.

Parameters

list ← list
The input list.

predicate ← function -> bool
The predicate to run against each element in the input list.

Parameters for predicate

item ← any
The current item to be checked.

Examples

Filter a list of numbers by only those divisible by 3

<$numbers = (: 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12)>
<$multiples-of-three = [filter: <numbers>; [?:x] { [is-factor: <x>; 3] }]>
[join: <multiples-of-three>; ,\s]
# -> 3, 6, 9, 12

Filter a list of numbers by only odd numbers

<$numbers = (: 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; 11; 12)>
# `is-odd` is a function, so we can simply pass it in as the predicate!
<$odd-numbers = [filter: <numbers>; <is-odd>]>
[join: <odd-numbers>; ,\s]
# -> 1, 3, 5, 7, 9, 11

Filter a list of words to only those that are 3 letters or less

<$words = [split: "the quick brown fox jumps over the lazy dog";\s]>
<$short-words = [filter: <words>; [?:word] { [le: [len: <word>]; 3] }]>
[join: <short-words>; ,\s]
# -> the, fox, the, dog

has


[has: collection; value]

→ bool

Returns a boolean indicating whether value occurs in collection.

If collection is a map, this function searches the map's keys. For maps, [has] checks only keys stored directly on the map itself; inherited prototype keys do not count.

Parameters

collection ← list | map
The collection to search.

value ← any
The value to search for.
If collection is of type map, value will be coerced to a string before searching (as map keys can only be strings).

index-of


[index-of: list; value]

→ int | nothing

Returns the index of the first occurrence of value in list. If no match is found, returns <>.

Parameters

list ← list
The list to search.

value ← any
The value to search for.

Examples

<$letters = (: A; A; B; C; C; D; E)>
[index-of: <letters>; A |> assert-eq: 0]
[index-of: <letters>; C |> assert-eq: 3]
[index-of: <letters>; E |> assert-eq: 6]
[index-of: <letters>; F |> assert-eq: <>]

join


[join: list; separator?]

→ any*

Prints the elements of a list in order separated by the separator value.

Parameters

list ← list
The list whose elements to print.

separator ← any (optional)
The separator to print between each element.

last-index-of


[last-index-of: list; value]

→ any

Returns the index of the last occurrence of value in list. If no match is found, returns <>.

Parameters

list ← list
The list to search.

value ← any
The value to search for.

Example

<$letters = (: A; A; B; C; C; D; E)>
[last-index-of: <letters>; A |> assert-eq: 1]
[last-index-of: <letters>; C |> assert-eq: 4]
[last-index-of: <letters>; E |> assert-eq: 6]
[last-index-of: <letters>; F |> assert-eq: <>]

map


[map: list; map-func]

→ list

Calls the supplied function on each item in a list and returns another list with the results in the same order.

Parameters

list ← list
The list whose values to map.

map-func ← function -> any
The function to map the values with.

Parameters for map-func

item ← any
The current item to map.

Example

# Multiple each element of a list by 10
<$numbers = (: 1; 2; 3; 4; 5; 6; 7; 8; 9; 10)>
<$tens = [map: <numbers>; [?:x] { [mul: <x>; 10] }]>
[join: <tens>; ,\s]
# -> 10, 20, 30, 40, 50, 60, 70, 80, 90, 100

oxford-join


[oxford-join: comma; conj; comma-conj; list]

→ any*

A variant of the join function for conveniently formatting comma-separated lists.

Parameters

comma ← any
The comma value. Separates all items except for the last 2. Unused in lists of 2 items or less.

conj ← any
The conjunction value. Only used to separate items in lists of exactly 2 values.

comma-conj ← any
The comma-conjunction value. Separates the final 2 values in lists with more than 2 values.

Remarks

These arguments can be used to configure several aspects of list formatting-- namely, the inclusion of the Oxford comma or the choice of conjunction separating the final two items.

The separator values are applied as follows:

Lists of 1 item use no separators.
Lists of 2 items use conj to separate the two items.
Lists of 3 or more items separate the final two items with comma-conj; all others use comma.

Examples

Print lists with Oxford comma

<$numbers = (:)>
[rep: 5][sep: \n]
{
  [push: <numbers>; [step]]
  [oxford-join: ,\s; \sand\s; ,\sand\s; <numbers>]
}

##
  OUTPUT:

  1
  1 and 2
  1, 2, and 3
  1, 2, 3, and 4
  1, 2, 3, 4, and 5
##

Print lists without Oxford comma

<$numbers = (:)>
[rep: 5][sep: \n]
{
  [push: <numbers>; [step]]
  [oxford-join: ,\s; \sand\s; \sand\s; <numbers>]
}

##
  OUTPUT:

  1
  1 and 2
  1, 2 and 3
  1, 2, 3 and 4
  1, 2, 3, 4 and 5
##

push


[push: list; value]

Appends a value to the end of a list.

Parameters

list ← list
The list to modify.

value ← any
The value to add to the end of list.

pop


[pop: list]

→ any

Removes the last value from a list and prints it.

insert


[insert: collection; value; pos]

Inserts value into a list or map at the position pos.

If collection is a list, pos must be an int.
If collection is a map, pos may be any non-nothing value.

Parameters

collection ← list | map
The collection to modify.

value ← any
The value to add to collection.

pos ← some
The location at which to insert the value.
For lists, this is the index; for maps, this is the key.

Errors

Raises an error if pos is out of range or not the correct type for the provided collection.

remove


[remove: collection; pos]

Removes the value at the pos from a list or map.

If collection is a list, pos must be an int.
If collection is a map, pos may be any non-nothing value.

Parameters

collection ← list | map
The collection to modify.

pos ← some
The location of the value to remove. Must be of type int for lists.

Errors

Raises an error if pos is an unsupported type for the provided collection.

rev


[rev: collection]

→ list | string | block | range

Prints a reversed copy of the input collection.

Parameters

collection ← list | string | block | range
The collection to reverse.

Example

[rev: (foo; bar)]
# -> (bar; foo)

shuffle


[shuffle: list]

→ list

Creates a shuffled copy of a list.

Example

# Shuffle the words in a string
<$message = "the quick brown fox jumps over he lazy dog">
[join: \s; [shuffle: [split: <message>; \s]]]

# ~> jumps fox quick dog lazy the brown the over

shuffle-self


[shuffle-self: list]

Shuffles the elements of a list in-place.

Cost

Where \(n\) = the length of list:

Time complexity
\(O(n)\)

RNG complexity
\(n - 1\)

Example

# Shuffles a list of letters and concatenates them into a single string
<$letters = (:A;B;C;D;E;F;G;H;I;J;K;L)>
[shuffle-self: <letters>]
[join: <letters>]

# ~> GKIBCHLEJADF

shuffle-thru


[shuffle-thru: list]

→ list

Shuffles the elements of a list in-place, then prints the list.

Cost

Where \(n\) = the length of list:

Time complexity
\(O(n)\)

RNG complexity
\(n - 1\)

Returns a copy of a list with random elements removed until the number of elements in the list copy reaches target-size. If the number of elements in the list is less than or equal to target-size, this function simply returns an exact copy of the original list.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list to.

Example

# Create a random subset of abilities for a character

<$char-traits = (:
  berserk;    xray-vision;  speaks-to-bees; 
  vampirism;  flying;       telekinesis; 
  many-legs;  high-jump;    bee-allergy
)>

<$npc = (::
  name = "Foo Bar";
  traits = [sift: <char-traits>; 2];
)>

# Print character info
<npc/name>: `[join: ,\s; <npc/traits>]

# ~> Foo Bar: speaks-to-bees, many-legs

sift-self


[sift-self: list; target-size]

Removes random elements from a list in-place until the number of elements in the list reaches target-size. If the number of elements in the list is less than or equal to target-size, this function does nothing.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list to.

Example

# Remove a random element from a list and print the contents at each iteration
<$list = [split: "Sphinx of black quartz, judge my vow."; \s]>
[rep: [len: <list>]]
[sep: \n]
{
  # Print the current list contents
  [join: \s; <list>]
  # Sift the list to n - 1
  [sift-self: <list>; [sub: [len: <list>]; 1]]
}

##
  EXAMPLE OUTPUT:

  Sphinx of black quartz, judge my vow.
  Sphinx of black quartz, my vow.
  Sphinx of black quartz, vow.
  Sphinx of black vow.
  Sphinx black vow.
  Sphinx vow.
  vow.
##

sift-thru


[sift-thru: list; target-size]

→ list

The input list is printed back to the caller.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list to.

squish


[squish: list; target-size]

→ list

Returns a copy of a list with random adjacent elements merged using addition until the number of elements in the list copy reaches target-size. If the number of elements in the list is less than or equal to target-size, this function simply returns an exact copy of the original list.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list copy to.

squish-self


[squish-self: list; target-size]

Merges random adjacent elements in a list using addition until the number of elements in the list reaches target-size. If the number of elements in the list is less than or equal to target-size, this function does nothing.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list to.

Example

# Merge random items in a number list
<$numbers = (: 100; 100; 100; 100; 100; 100; 100; 100; 100; 100)>

# Print the original list
Before: `[join: ,\s; <numbers>]\n

# Squish the list down to 5 elements
[squish-self: <numbers>; 5]

# Print the modified list
After: `[join: ,\s; <numbers>]\n

##
  EXAMPLE OUTPUT:

  Before: 100, 100, 100, 100, 100, 100, 100, 100, 100, 100
  After: 100, 200, 100, 400, 200
##

squish-thru


[squish-thru: list; target-size]

→ list

Merges random adjacent elements in a list using addition until the number of elements in the list reaches target-size, then prints the list. If the number of elements in the list is less than or equal to target-size, this function does nothing.

Parameters

list ← list
The input list.

target-size ← int
The maximum number of elements to reduce the list to.

sort


[sort: list]

→ list

Creates a copy of a list with its elements sorted in ascending order.

Parameters

list ← list
The input list.

sort-self


[sort-self: list]

Sorts the elements of a list in-place in ascending order.

Parameters

list ← list
The input list.

sort-thru


[sort-thru: list]

→ list

Sorts the elements of a list in-place in ascending order, then prints the list.

Parameters

list ← list
The input list.

sum


[sum: list]

→ any

Adds the elements of a list together from left to right and prints the result.

take


[take: collection; pos]

→ any

Removes the value at pos from a list or map and prints it.

Parameters

collection ← list | map
The input collection.

pos ← some
The location of the value to take. If collection is a list, this argument must be an int.

Errors

Raises an error if pos is not a valid location in the collection.

translate


[translate: list; map]

→ list

Matches each item in a list to a map and returns a list with the corresponding map values. Values that have no corresponding key in the map are passed through as-is. For maps with prototypes, [translate] uses only keys stored directly on the provided map.

Parameters

list ← list
The input list.

map ← map
A map associating items in list with their replacements.

Example

# Constructs a substitution cipher function
[$make-cipher: alphabet] {
  <
    $letters = [split: <alphabet>];
    $sub-letters = [shuffle: <letters>];
    $cipher = [assoc: <letters>; <sub-letters>];
    $cipher-rev = [assoc: <sub-letters>; <letters>];
  >
  # Return cipher functions
  (::
    encode = [?: message] {
      [sum: [translate: [split: <message>]; <cipher>]]
    };
    decode = [?: message] {
      [sum: [translate: [split: <message>]; <cipher-rev>]]
    };
  )
}

# Create a cipher and encode/decode a message
<$cipher = [make-cipher: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"]>
<$secret-message = "The quick brown fox jumps over the lazy dog.">
<$encoded-message = [cipher/encode: <secret-message>]>
<$decoded-message = [cipher/decode: <encoded-message>]>

# Finally, print the result
Original: \"<secret-message>\"\n
Encoded: \"<encoded-message>\"\n
Decoded: \"<decoded-message>\"\n

##
  EXAMPLE OUTPUT:

  Original: "The quick brown fox jumps over the lazy dog."
  Encoded: "kWj KGvaF QcDiq HDx CGpMJ DOjc AWj Tsyt fDN."
  Decoded: "The quick brown fox jumps over the lazy dog."
##

keys


[keys: map]

Prints a list of the keys stored in map.

This function lists only keys physically stored in map. Inherited prototype keys are not included.

values


[values: map]

Prints a list of the values stored in map.

This function lists only values physically stored in map. Inherited prototype values are not included.

zip


[zip: list-a; list-b; zip-func]

→ list

Returns a new list that combines each pair of items from the two input lists using the specified function. The lists do not need to be the same length; if there is a difference, it will be made up with empties.

Parameters

list-a ← list
A list containing the left-hand values of the zip.

list-b ← list
A list containing the right-hand values of the zip.

zip-func ← function -> any
A function that prints a new value for each corresponding pair of values from list-a and list-b.

Parameters for zip-func

a ← any
The current value from list-a.

b ← any
The current value from list-b.

Examples

# Dot product
[$dot: a; b] {
  [zip: <a>; <b>; <mul> |> sum]
}

[dot: (1; 2; 3); (4; 5; 6)] # 32

Keyboard shortcuts

Ranty Reference