Skip to content

luxe API (2025.1.2)

luxe: containers module

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(list: Sequence) returns 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(list: Sequence, callback: Fn) returns 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(list: List, value: Any) returns 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(list: List, value: Any, fn: Fn) returns 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(a: List, b: List) returns 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(a: List, b: List) returns 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(list: List) returns 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(list: List, value: Any) returns 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(into: List, list: List) returns 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(into: List, list: List) returns 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(list: List, value: Any, fn: Fn) returns 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.contains(list: Any, item: Any) returns unknown

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

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

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

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

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

Lists.index_of_where(list: List, fn: Fn) returns 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(list: List, value: Any, fn: Fn) returns 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(list: List, compare: Fn) returns 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(list: List, compare: Fn) returns 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(list: List, low: Num, high: Num, compare: Fn) returns 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 returns 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 returns 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() returns MapOrdered

Create a new ordered map.

var map = MapOrdered.new()

MapOrdered.get(key: Any) returns 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(key: Any, value: Any) returns 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(key: Any) returns 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] returns 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]=(value : Any) returns unknown

MapOrdered.iterate(iterator: Any) returns unknown

Implementation details for the Wren iterator protocol.

MapOrdered.iteratorValue(iterator: Any) returns unknown

Implementation details for the Wren iterator protocol.