modules/list/util.zzm

NAME

list/util - List utility functions.

SYNOPSIS

  from list/util import grep, head, map, sortnum_by, sum, ListUtil;

  say( sum( [ 10, 20, 30 ] ) );

  let users := [
      { name: "Zoe", age: 32, score: 87, active: true },
      { name: "Ada", age: 41, score: 98, active: true },
      { name: "Max", age: 27, score: 91, active: false },
      { name: "Bea", age: 36, score: 93, active: true },
  ];

  let by_name := ListUtil.sortstr_by( users, fn user → user{name} );
  let oldest  := ListUtil.max_by( users, fn user → user{age} );

  let leaderboard := users
      ▷ grep( ^^, fn user → user{active} )
      ▷ sortnum_by( ^^, fn user → user{score} )
      ▷ reverse( ^^ )
      ▷ head( ^^, 3 )
      ▷ map( ^^, fn user → user{name} );

  say( leaderboard );  // Ada, Bea, Zoe

DESCRIPTION

This pure-Zuzu module provides functions inspired by Perl's List::Util, List::MoreUtils, and List::UtilsBy. Functions are exported directly, and the ListUtil class provides static wrappers for code that wants to avoid importing many names.

Most functions take the collection first. Predicate callbacks receive one value. Reducer callbacks receive (accumulator, value). Key callbacks for *_by functions receive one value and are called once per input value. Pair callbacks receive a Zuzu Pair object.

Collection Support

Array is the primary input type.

Bag and Set are accepted by order-insensitive functions. Their iteration order is the order returned by the runtime's to_Array method and should not be treated as stable unless the runtime documents it.

Ordered and position-sensitive functions require Array. Pair helpers which operate on pairs expect an Array of Pair objects.

FUNCTIONS

Reduction

reduce(Array values, Function callback)
Calls callback(accumulator, value) from left to right. Returns null for an empty array.
```
  reduce( [ 1, 2, 3 ], fn ( a, b ) → a + b );  // 6
```
reductions(Array values, Function callback)
Returns every intermediate accumulator value.
```
  reductions( [ 1, 2, 3 ], fn ( a, b ) → a + b );  // [ 1, 3, 6 ]
```

Predicates And Searches

any(Array|Bag|Set values, Function predicate)
Returns true if any value satisfies predicate(value).
```
  any( [ 1, 2, 3 ], fn x → x > 2 );  // true
```
all(Array|Bag|Set values, Function predicate)
Returns true if every value satisfies predicate(value).
```
  all( [ 2, 4, 6 ], fn x → x mod 2 = 0 );  // true
```
none(Array|Bag|Set values, Function predicate)
Returns true if no value satisfies predicate(value).
```
  none( [ 1, 3, 5 ], fn x → x mod 2 = 0 );  // true
```
notall(Array|Bag|Set values, Function predicate)
Returns true if at least one value does not satisfy predicate(value).
```
  notall( [ 2, 4, 5 ], fn x → x mod 2 = 0 );  // true
```
first(Array values, Function predicate)
Returns the first matching value, or null.
```
  first( [ 1, 2, 3 ], fn x → x > 1 );  // 2
```
firstval(Array values, Function predicate)
Alias-style helper equivalent to first.
```
  firstval( [ "a", "bb" ], fn x → length(x) > 1 );  // "bb"
```
firstidx(Array values, Function predicate)
Returns the first matching index, or -1.
```
  firstidx( [ 1, 4, 9 ], fn x → x > 3 );  // 1
```
lastval(Array values, Function predicate)
Returns the last matching value, or null.
```
  lastval( [ 1, 4, 9 ], fn x → x > 3 );  // 9
```
lastidx(Array values, Function predicate)
Returns the last matching index, or -1.
```
  lastidx( [ 1, 4, 9 ], fn x → x > 3 );  // 2
```
onlyval(Array|Bag|Set values, Function predicate)
Returns the value if exactly one value matches, otherwise null.
```
  onlyval( [ 1, 2, 3 ], fn x → x = 2 );  // 2
```
onlyidx(Array values, Function predicate)
Returns the index if exactly one value matches, otherwise -1.
```
  onlyidx( [ 1, 2, 3 ], fn x → x = 2 );  // 1
```

Numeric And String Values

max(Array|Bag|Set values)
Returns the numerically greatest value, or null.
```
  max( [ 7, 2, 10 ] );  // 10
```
min(Array|Bag|Set values)
Returns the numerically smallest value, or null.
```
  min( [ 7, 2, 10 ] );  // 2
```
maxstr(Array|Bag|Set values)
Returns the string-greatest value, or null.
```
  maxstr( [ "b", "aa" ] );  // "b"
```
minstr(Array|Bag|Set values)
Returns the string-smallest value, or null.
```
  minstr( [ "b", "aa" ] );  // "aa"
```
sum(Array|Bag|Set values)
Returns the numeric sum, or null for an empty collection.
```
  sum( [ 1, "2", 3 ] );  // 6
```
sum0(Array|Bag|Set values)
Returns the numeric sum, using 0 for an empty collection.
```
  sum0( [] );  // 0
```
product(Array|Bag|Set values)
Returns the numeric product, using 1 for an empty collection.
```
  product( [ 2, "3", 4 ] );  // 24
```

Pairs

pairs(Array flat)
Converts a flat key/value array into an array of Pair objects.
```
  pairs( [ "a", 1, "b", 2 ] );
```
unpairs(Array pair_objects)
Converts an array of Pair objects into a flat key/value array.
```
  unpairs( pairs( [ "a", 1 ] ) );  // [ "a", 1 ]
```

pairkeys(Array pair_objects)

Returns pair keys.

  pairkeys( pairs( [ "a", 1, "b", 2 ] ) );  // [ "a", "b" ]

pairvalues(Array pair_objects)

Returns pair values.

  pairvalues( pairs( [ "a", 1, "b", 2 ] ) );  // [ 1, 2 ]

pairfirst(Array pair_objects, Function predicate)
Returns the first Pair where predicate(pair) is true, or null.
```
  pairfirst( pairs( [ "a", 1 ] ), fn p → p.key eq "a" );
```
pairgrep(Array pair_objects, Function predicate)
Returns all Pair objects where predicate(pair) is true.
```
  pairgrep( pairs( [ "a", 1, "b", 2 ] ), fn p → p.value > 1 );
```
pairmap(Array pair_objects, Function mapper)
Maps each Pair using mapper(pair).
```
  pairmap( pairs( [ "a", 1 ] ), fn p → p.key _ "=" _ p.value );
```

Ordering And Uniqueness

sort(Array values, Function comparator)
Returns a sorted array using comparator(left, right).
```
  sort( [ 1, 3, 2 ], fn ( a, b ) → a ≶ b );  // [ 1, 2, 3 ]
```
sortnum(Array|Bag|Set values)
Returns values sorted numerically.
```
  sortnum( [ "2", "10", "1" ] );  // [ "1", "2", "10" ]
```
sortstr(Array|Bag|Set values)
Returns values sorted stringwise.
```
  sortstr( [ "b", "aa" ] );  // [ "aa", "b" ]
```
reverse(Array|Bag|Set values)
Returns values in reverse order.
```
  reverse( [ 1, 2, 3 ] );  // [ 3, 2, 1 ]
```
map(Array|Bag|Set values, Function mapper)
Returns mapper(value) for each value.
```
  map( [ 1, 2, 3 ], fn x → x × 2 );  // [ 2, 4, 6 ]
```
grep(Array|Bag|Set values, Function predicate)
Returns values where predicate(value) is true.
```
  grep( [ 1, 2, 3 ], fn x → x > 1 );  // [ 2, 3 ]
```
shuffle(Array|Bag|Set values)
Returns the values in random order.
```
  shuffle( [ 1, 2, 3 ] );
```
sample(Array|Bag|Set values, Number count)
Returns up to count random values in random order, without replacement. If count is larger than the input collection, all values are returned in random order.
```
  sample( [ 1, 2, 3 ], 2 );
```
uniq(Array|Bag|Set values)
Returns first-seen unique values using Zuzu equality.
```
  uniq( [ 1, 1, 2 ] );  // [ 1, 2 ]
```
uniqint(Array|Bag|Set values)
Returns first-seen values unique by integer value.
```
  uniqint( [ 1.1, 1.9, 2.1 ] );  // [ 1.1, 2.1 ]
```
uniqnum(Array|Bag|Set values)
Returns first-seen values unique by numeric value.
```
  uniqnum( [ "1", 1, 2 ] );  // [ "1", 2 ]
```
uniqstr(Array|Bag|Set values)
Returns first-seen values unique by string value.
```
  uniqstr( [ 1, "1", 2 ] );  // [ 1, 2 ]
```
head(Array values, Number count := 1)
Returns the first count values.
```
  head( [ 1, 2, 3 ], 2 );  // [ 1, 2 ]
```
tail(Array values, Number count := 1)
Returns the last count values.
```
  tail( [ 1, 2, 3 ], 2 );  // [ 2, 3 ]
```
zip(Array first, Array second, ...)
Returns rows formed from the given arrays, using null where an input array is short.
```
  zip( [ "a", "b" ], [ 1, 2 ] );  // [ [ "a", 1 ], [ "b", 2 ] ]
```
mesh(Array first, Array second, ...)
Returns the same values as zip, flattened.
```
  mesh( [ "a", "b" ], [ 1, 2 ] );  // [ "a", 1, "b", 2 ]
```

Keyed Helpers

sort_by(Array|Bag|Set values, Function key_function)
Sorts values numerically by key_function(value). The key function is called once per value, using a Schwartzian transform.
```
  sort_by( users, fn user → user{age} );
```
sortnum_by(Array|Bag|Set values, Function key_function)
Alias for sort_by.
```
  sortnum_by( users, fn user → user{age} );
```
sortstr_by(Array|Bag|Set values, Function key_function)
Sorts values stringwise by key_function(value).
```
  sortstr_by( users, fn user → user{name} );
```
max_by(Array|Bag|Set values, Function key_function)
Returns the value with the greatest numeric key. The key function is called once per value.
```
  max_by( users, fn user → user{age} );
```
maxnum_by(Array|Bag|Set values, Function key_function)
Alias for max_by.
```
  maxnum_by( users, fn user → user{age} );
```
maxstr_by(Array|Bag|Set values, Function key_function)
Returns the value with the greatest string key.
```
  maxstr_by( users, fn user → user{name} );
```
min_by(Array|Bag|Set values, Function key_function)
Returns the value with the smallest numeric key. The key function is called once per value.
```
  min_by( users, fn user → user{age} );
```
minnum_by(Array|Bag|Set values, Function key_function)
Alias for min_by.
```
  minnum_by( users, fn user → user{age} );
```
minstr_by(Array|Bag|Set values, Function key_function)
Returns the value with the smallest string key.
```
  minstr_by( users, fn user → user{name} );
```
uniq_by(Array|Bag|Set values, Function key_function)
Returns first-seen values unique by string key. The key function is called once per value.
```
  uniq_by( users, fn user → user{name} );
```

CLASS

`ListUtil`

ListUtil provides every exported function as a static method with the same signature.

  from list/util import ListUtil;
  say( ListUtil.sum( [ 1, 2, 3 ] ) );

COPYRIGHT AND LICENCE

list/util is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.