luxe: containers

• Lists
• MapOrdered

---

Lists

import "luxe: containers" for Lists

The Lists API works with the built in Wren List type, offering more tools to operate on them.

Lists.first(.)

Lists.first(list : Sequence) : Any

Returns the first element of a Sequence, null if the sequence is empty.

  var list = ["twig", 2, null, "tree", "petals", "faeries", 9]
  Lists.first(list) //"twig"

Lists.first(..)

Lists.first(list : Sequence, callback : Fn) : Any

Searches for the first element in a sequence that fulfills a requirement and returns it. If no element fulfills the requirement, null is returned.

  var list = ["twig", 2, null, "tree", "petals", "faeries", 9]
  Lists.first(list){|elem| elem is String && elem.count > 4} //"petals"

Lists.binary_search(..)

Lists.binary_search(list : List, value : Any) : Num

Searches for value in list using a binary search. Binary searches can be more efficient for finding items when there are many. This requires the list to be sorted, and values in the list to be comparable with >/<.

Returns the index in the list, or -1 if not found.

var to_find = 9
var list = [1,3,7,9,23,54]
var index = Lists.binary_search(list, to_find) //index is 3

Lists.binary_search_first(…)

Lists.binary_search_first(list : List, value : Any, fn : Fn) : Num

Similar to binary_search but handles comparison via a callback. The callback should return 0 for equal, -1 for lower and 1 for higher. The callback puts the input value in the first argument.

Returns the index in the list, or -1 if not found.

var list = [1,3,7,9,23,54]
var index = Lists.binary_search_first(list, 9) {|value, other|
  if(value == to_find) return 0
  if(value < to_find)  return -1
  return 1
}

Lists.equal(..)

Lists.equal(a : List, b : List) : Bool

Compares two flat lists, returning true if the contents are the same and in the same order. Does not recurse nested lists. Uses a[i] != b[i] to compare.

var listA = [1,9,7]
var listB = [1,7,9]
var equalA = Lists.equal(listA, [1,7,9]) //false
var equalB = Lists.equal(listB, [1,7,9]) //true

Lists.equalish(..)

Lists.equalish(a : List, b : List) : Bool

Similar to equal but values don’t need to be in the same order.

var listA = [1,9,7]
var listB = [1,7,9]
var equalA = Lists.equal(listA, [1,7,9]) //true
var equalB = Lists.equal(listB, [1,7,9]) //true

Lists.flatten(.)

Lists.flatten(list : List) : List

Converts a nested list of lists to a single flat list of values.

var list = [1,[2,3,[4,[5]]]]
var flat = Lists.flatten(list) //[1,2,3,4,5]

Lists.add_unique(..)

Lists.add_unique(list : List, value : Any) : Bool

Add an item to a list if the value doesn’t already exist in the list. Uses list.indexOf to check.

Returns true if the value was unique and added to the list.

var list = [1,2,3]
Lists.add_unique(list, 0) //true
Lists.add_unique(list, 1) //false, already found

Lists.append(..)

Lists.append(into : List, list : List) : None

Append list at the end of into without allocating a new list. This function modifies into.

Note that in Wren, List implements +, which is append too, but that makes a new list with the two combined. [1] + [2] = [1, 2]

var list = [1,2]
Lists.append(list, [3,4,5])
Log.print(list) //[1,2,3,4,5]

Lists.prepend(..)

Lists.prepend(into : List, list : List) : None

Similar to append, but adds the items from list to the front of into. This function modifies into.

var list = [1,2]
Lists.prepend(list, [3,4,5])
Log.print(list) //[3,4,5,1,2]

Lists.remove_where(…)

Lists.remove_where(list : List, value : Any, fn : Fn) : Any

Similar to list.remove but uses a function for the find/equality check. Uses Lists.index_of_where to find the index, so the callback msut return true if the values are equal or false if not.

Returns the value if it was removed, or null if it wasn’t found.

var list = [1,2,3]
var fn = Fn.new {|value, other| value == other }
Lists.remove_where(list, 3, fn)  //3
Lists.remove_where(list, 6, fn)  //null
Log.print(list)               //[1,2]

Lists.remove_where(..)

Lists.remove_where(list : List, fn : Fn) : Any

Similar to list.remove but uses a function for the find/equality check. Uses Lists.index_of_where to find the index, so the callback msut return true if the values are equal or false if not.

Returns the value if it was removed, or null if it wasn’t found.

var list = [1,2,3]
var fn = Fn.new {|value, other| value == other }
Lists.remove_where(list, fn)  //3
Lists.remove_where(list, fn)  //null
Log.print(list)               //[1,2]

Lists.contains(..)

Lists.contains(list : Any, item : Any) : unknown

Deprecated. Use list.contains(item) Returns true if the list contains the item.

Lists.remove(..)

Lists.remove(list : Any, to_remove : Any) : unknown

Deprecated. Use list.remove(item) Returns the item if removed, or null.

Lists.index_of(..)

Lists.index_of(list : Any, item : Any) : unknown

Deprecated. Use list.indexOf(item) Returns the index, or -1 if the item isn’t found.

Lists.index_of_where(..)

Lists.index_of_where(list : List, fn : Fn) : Num

Returns the index of value in list or -1 if not found, where comparison is handled by a callback function.

var list = [1,2,3]
Lists.index_of_where(list, 3) {|value, other| value == other } //2

Lists.index_of_where(…)

Lists.index_of_where(list : List, value : Any, fn : Fn) : Num

Returns the index of item in list or -1 if not found, where comparison is handled by a callback function.

var list = [1,2,3]
Lists.index_of_where(list, 3) {|value, other| value == other } //2

Lists.bubble_sort(..)

Lists.bubble_sort(list : List, compare : Fn) : None

In-place sorting of list using the compare function. Modifies list. Uses bubble sort. The compare function should return 0 for equal, -1 for lower values and 1 for higher values.

var list = [5,2,67,23]
Lists.bubble_sort(list) {|a, b| b - a }
Log.print(list) // [67, 23, 5, 2]

Lists.bubble_sort(list) {|a, b| a - b }
Log.print(list) // [2, 5, 23, 67]

Lists.quicksort(..)

Lists.quicksort(list : List, compare : Fn) : List

In-place sorting of list using the compare function. Modifies list. Uses quick sort. The compare function should return 0 for equal, -1 for lower values and 1 for higher values.

var list = [5,2,67,23]
Lists.quicksort(list) {|a, b| b - a }
Log.print(list) // [67, 23, 5, 2]

Lists.quicksort(list) {|a, b| a - b }
Log.print(list) // [2, 5, 23, 67]

Lists.quicksort(…)

Lists.quicksort(list : List, low : Num, high : Num, compare : Fn) : List

Same as quicksort but a low and high index can be specified to sort just a portion of a list. The default for quicksort(list, compare) is low = 0, high = list.count-1.

var list = [5,2,34,89,11,60,45]
Lists.quicksort(list, 2, 5) {|a, b| a - b }
Log.print(list) // [5, 2, |11, 34, 60, 89|, 45]
//note only the range between | was sorted

MapOrdered

import "luxe: containers" for MapOrdered

A Map wrapper that keeps the order of the keys the same in which they’re added. Note: The Wren Map class doesn’t guarantee order of keys.

MapOrdered.keys

MapOrdered.keys : List

Returns the list of keys in the Map. Don’t modify this.

var map = MapOrdered.new()
map["one"] = 1
map["two"] = 2
Log.print(map.keys) //["one", "two"]

MapOrdered.map

MapOrdered.map : Map

Access to the underlying Wren Map data. Normally you don’t modify this directly.

var map = MapOrdered.new()
map["one"] = 1
map["two"] = 2
Log.print(map.map) //{two: 2, one: 1}

MapOrdered.new(.)

MapOrdered.new() : MapOrdered

Create a new ordered map.

var map = MapOrdered.new()

MapOrdered.get(.)

MapOrdered.get(key : Any) : unknown

Return the value associated with key, or null if not found. You can also use map[key] as an alternative.

var map = MapOrdered.new()
map["one"] = 1
Log.print(map.get("one"))  //1
Log.print(map.get("two"))  //null

MapOrdered.set(..)

MapOrdered.set(key : Any, value : Any) : unknown

Set a value for a given key. You can also use map[key] = value as an alternative.

var map = MapOrdered.new()
map.set("one", 1)

MapOrdered.containsKey(.)

MapOrdered.containsKey(key : Any) : unknown

Returns true if key is found in the map.

var map = MapOrdered.new()
map["one"] = 1
Log.print(map.containsKey("one"))  //true
Log.print(map.containsKey("two"))  //false

MapOrdered key : Any

MapOrdered [key : Any] : unknown

Return the value associated with key, or null if not found.

var map = MapOrdered.new()
map["one"] = 1
Log.print(map["one"])  //1
Log.print(map["two"])  //null

MapOrdered key : Any

MapOrdered [key : Any]=(value : Any) : unknown

MapOrdered.iterate(.)

MapOrdered.iterate(iterator : Any) : unknown

Implementation details for the Wren iterator protocol.

MapOrdered.iteratorValue(.)

MapOrdered.iteratorValue(iterator : Any) : unknown

Implementation details for the Wren iterator protocol.