Sprites.Array
Reactive helpers over lists. Each reads a list and derives a fact from it, so a length, an item, a slice or an emptiness follows the list. Resize crops or pads a list, and SizeBinding is a two way view of its length. Every reader is a read only calculation; only SizeBinding writes back.
- Sprites.Array.Append
- Sprites.Array.At
- Sprites.Array.Build
- Sprites.Array.Choose
- Sprites.Array.Fill
- Sprites.Array.FindIndex
- Sprites.Array.FromBits
- Sprites.Array.IndexOf
- Sprites.Array.InsertAt
- Sprites.Array.IsEmpty
- Sprites.Array.Length
- Sprites.Array.Lookup
- Sprites.Array.Map
- Sprites.Array.RemoveAt
- Sprites.Array.Resize
- Sprites.Array.Set
- Sprites.Array.SizeBinding
- Sprites.Array.Slice
- Sprites.Array.Some
- Sprites.Array.Concat
- Sprites.Array.KeyBy
Sprites.Array.Append Sprites.Reactive.Value
Sprites.Array.Append(list, item)
A new list with item added at the end. A missing list counts as empty. Each argument may be a constant or a reactive value, so the result follows both.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to add to. |
item | Any or Sprites.Reactive.Value | The value added at the end. |
Returns a read-only Sprites.Reactive.Value holding the new list with the item at the end.
const list = Sprites.Reactive.Value(['a', 'b']);
const item = Sprites.Reactive.Value('c');
const longer = Sprites.Array.Append(list, item);
Sprites.Ui.Input.Dropdown(item, () => {
Sprites.Ui.Input.Option('c', 'c');
Sprites.Ui.Input.Option('d', 'd');
});
const joined = Sprites.Text.Join(longer, ', ');
Sprites.Ui.Dom.Text(' list = ', joined);Sprites.Array.At Sprites.Reactive.Value
Sprites.Array.At(list, index)
The item of a list at an index, or undefined past the ends. Both may be a constant or a reactive value. It is read only; to change one element build the new list with Sprites.Object.With and set the list.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to read. |
index | Number or Sprites.Reactive.Value | The position to read. |
Returns a read-only Sprites.Reactive.Value holding the item at the index.
const list = Sprites.Reactive.Value(['red', 'green', 'blue']);
const index = Sprites.Reactive.Value(0);
const item = Sprites.Array.At(list, index);
Sprites.Ui.Input.Number(index, 0, 2);
Sprites.Ui.Dom.Text(' item = ', item);Sprites.Array.Build Sprites.Reactive.Value
Sprites.Array.Build(count, map)
A list of count items, each the value that map returns for its index. map is a plain function of an index, run for each position. count may be a constant or a reactive value, so the list follows it.
| Input | Type | Description |
|---|---|---|
count | Number or Sprites.Reactive.Value | How many items to build. |
map | Function | A plain function of an index, returning the item at that position. |
Returns a read-only Sprites.Reactive.Value holding the built list.
const count = Sprites.Reactive.Value(4);
const squares = Sprites.Array.Build(count, (i) => {
return i * i;
});
Sprites.Ui.Input.Number(count, 0, 8);
const joined = Sprites.Text.Join(squares, ', ');
Sprites.Ui.Dom.Text(' squares = ', joined);Sprites.Array.Emit Void
Sprites.Array.Emit(value)
Emit one value to the nearest Sprites.Array.Gather. Call it inside a Gather build, on its own or within an If, an Each or a Repeat, and the value joins the gathered list in tree order.
| Input | Type | Description |
|---|---|---|
value | Any or Sprites.Reactive.Value | The value to add. A reactive value follows its source; a pending value pends the whole list. |
Returns nothing.
const items = Sprites.Array.Gather(() => {
Sprites.Array.Emit('one');
Sprites.Array.Emit('two');
});
const joined = Sprites.Text.Join(items, ', ');
Sprites.Ui.Dom.Text(joined);Sprites.Array.Fill Sprites.Reactive.Value
Sprites.Array.Fill(count, value)
A list of count copies of a value. Each argument may be a constant or a reactive value, so the list follows both.
| Input | Type | Description |
|---|---|---|
count | Number or Sprites.Reactive.Value | How many copies to make. |
value | Any or Sprites.Reactive.Value | The value to repeat. |
Returns a read-only Sprites.Reactive.Value holding the filled list.
const count = Sprites.Reactive.Value(3);
const dots = Sprites.Array.Fill(count, '.');
Sprites.Ui.Input.Number(count, 0, 8);
const joined = Sprites.Text.Join(dots, '');
Sprites.Ui.Dom.Text(' dots = ', joined);Sprites.Array.FindIndex Sprites.Reactive.Value
Sprites.Array.FindIndex(list, match, fallback)
The index of the first item that match returns true for, or a fallback when none do. match is a plain function of an item. list and fallback may each be a constant or a reactive value.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to search. |
match | Function | A plain function of an item, true for the item to find. |
fallback | Any or Sprites.Reactive.Value | The value returned when no item matches. |
Returns a read-only Sprites.Reactive.Value holding the found index or the fallback.
const list = Sprites.Reactive.Value([3, 7, 4, 9]);
const limit = Sprites.Reactive.Value(5);
const found = Sprites.Array.FindIndex(list, (n) => {
const max = Sprites.Reactive.Calculate.Get(limit);
return n > max;
}, -1);
Sprites.Ui.Input.Number(limit, 0, 9);
Sprites.Ui.Dom.Text(' index = ', found);Sprites.Array.FromBits Sprites.Reactive.Value
Sprites.Array.FromBits(bytes, width, height, on, off)
A flat cell array unpacked from a row of packed bits: each byte is one row, the top bit the leftmost pixel, a set bit taking the on value and a clear bit the off value, so a one bit glyph or tile row becomes a width by height cell array. Every argument may be a constant or a reactive value, so the cells follow them.
| Input | Type | Description |
|---|---|---|
bytes | Array or Sprites.Reactive.Value | The packed rows, one byte per row, the top bit leftmost. |
width | Number or Sprites.Reactive.Value | The number of cells across each row. |
height | Number or Sprites.Reactive.Value | The number of rows. |
on | Any or Sprites.Reactive.Value | The value a set bit takes. |
off | Any or Sprites.Reactive.Value | The value a clear bit takes. |
Returns a read-only Sprites.Reactive.Value holding the width by height cell array.
const bytes = Sprites.Reactive.Value([129, 66, 36, 24]);
const cells = Sprites.Array.FromBits(bytes, 8, 4, '#', '.');
const joined = Sprites.Text.Join(cells, '');
Sprites.Ui.Dom.Text(' cells = ', joined);Sprites.Array.Gather Sprites.Reactive.Value
Sprites.Array.Gather(build)
Gather the values emitted inside build into one reactive list. Inside build, Sprites.Array.Emit hands a value up; any reactive logic works, so a fixed value, an If that emits only while a condition holds, and an Each that emits one per element may all sit together, and the list follows as the conditions and lists change. It works the same in a lens: the gather runs once and the collected list is the value a Set commits. A pending emitted value, or a pending If or Each condition inside, pends the whole list.
| Input | Type | Description |
|---|---|---|
build | Function | Builds the emissions. Call Sprites.Array.Emit to add a value, on its own or inside an If, Each or Repeat. |
Returns a read-only Sprites.Reactive.Value holding the gathered list.
const extra = Sprites.Reactive.Value(true);
const list = Sprites.Reactive.Value(['a', 'b']);
const gathered = Sprites.Array.Gather(() => {
Sprites.Array.Emit('start');
Sprites.Reactive.If(extra, () => {
Sprites.Array.Emit('extra');
});
Sprites.Reactive.Each(list, (item) => {
Sprites.Array.Emit(item);
});
Sprites.Array.Emit('end');
});
Sprites.Ui.Input.Checkbox(extra);
Sprites.Ui.Button.Push(list, 'x', 'Add item');
const joined = Sprites.Text.Join(gathered, ', ');
Sprites.Ui.Dom.Text(' gathered = ', joined);Sprites.Array.IndexOf Sprites.Reactive.Value
Sprites.Array.IndexOf(list, value)
The index of a value in a list, or minus one when it is absent. Both may be a constant or a reactive value, so the result follows them.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to search. |
value | Any or Sprites.Reactive.Value | The value to look for. |
Returns a read-only Sprites.Reactive.Value holding the index, or minus one.
const list = Sprites.Reactive.Value(['red', 'green', 'blue']);
const value = Sprites.Reactive.Value('green');
const at = Sprites.Array.IndexOf(list, value);
Sprites.Ui.Input.Dropdown(value, () => {
Sprites.Ui.Input.Option('red', 'Red');
Sprites.Ui.Input.Option('green', 'Green');
Sprites.Ui.Input.Option('blue', 'Blue');
});
Sprites.Ui.Dom.Text(' index = ', at);Sprites.Array.InsertAt Sprites.Reactive.Value
Sprites.Array.InsertAt(list, index, item)
A new list with item inserted at index. An index inside the range from zero to the length inclusive lands the item there; an index outside the range keeps the list as it stands. Each argument may be a constant or a reactive value, so the result follows them.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to insert into. |
index | Number or Sprites.Reactive.Value | The position the item lands at, from zero to the length inclusive. |
item | Any or Sprites.Reactive.Value | The value inserted. |
Returns a read-only Sprites.Reactive.Value holding the new list, or the list unchanged when the index is out of range.
const list = Sprites.Reactive.Value(['a', 'b', 'c']);
const index = Sprites.Reactive.Value(1);
const longer = Sprites.Array.InsertAt(list, index, 'x');
Sprites.Ui.Input.Number(index, 0, 3);
const joined = Sprites.Text.Join(longer, ', ');
Sprites.Ui.Dom.Text(' list = ', joined);Sprites.Array.IsEmpty Sprites.Reactive.Value
Sprites.Array.IsEmpty(list)
True when a list holds no items. A missing list counts as empty.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to test. |
Returns a read-only Sprites.Reactive.Value, true while the list holds no items.
const list = Sprites.Reactive.Value([]);
const empty = Sprites.Array.IsEmpty(list);
Sprites.Ui.Button.Push(list, 'item', 'Add item');
Sprites.Ui.Button.SetValue(list, [], 'Clear');
Sprites.Ui.Dom.Text(' empty = ', empty);Sprites.Array.Length Sprites.Reactive.Value
Sprites.Array.Length(list)
The length of a list. It is read only; for a two way length that resizes the list on set, use SizeBinding.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to measure. |
Returns a read-only Sprites.Reactive.Value holding the length.
const list = Sprites.Reactive.Value(['a', 'b']);
const length = Sprites.Array.Length(list);
Sprites.Ui.Button.Push(list, 'x', 'Add');
Sprites.Ui.Dom.Text(' length = ', length);Sprites.Array.Map Sprites.Reactive.Value
Sprites.Array.Map(list, map)
A list with map applied to each item. map is a plain function of an item and its index. list may be a constant or a reactive value, so the result follows it.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to map over. |
map | Function | A plain function of an item and its index, returning the new item. |
Returns a read-only Sprites.Reactive.Value holding the mapped list.
const list = Sprites.Reactive.Value([1, 2, 3]);
const doubled = Sprites.Array.Map(list, (n) => {
return n * 2;
});
Sprites.Ui.Button.Push(list, 4, 'Add 4');
const joined = Sprites.Text.Join(doubled, ', ');
Sprites.Ui.Dom.Text(' doubled = ', joined);Sprites.Array.RemoveAt Sprites.Reactive.Value
Sprites.Array.RemoveAt(list, index)
A new list with the item at index removed. An index inside the range from zero to the last item removes that item; an index outside the range keeps the list as it stands. Each argument may be a constant or a reactive value, so the result follows them.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to remove from. |
index | Number or Sprites.Reactive.Value | The position of the item removed, from zero to the last item. |
Returns a read-only Sprites.Reactive.Value holding the new list, or the list unchanged when the index is out of range.
const list = Sprites.Reactive.Value(['a', 'b', 'c', 'd']);
const index = Sprites.Reactive.Value(1);
const shorter = Sprites.Array.RemoveAt(list, index);
Sprites.Ui.Input.Number(index, 0, 3);
const joined = Sprites.Text.Join(shorter, ', ');
Sprites.Ui.Dom.Text(' list = ', joined);Sprites.Array.Resize Sprites.Reactive.Value
Sprites.Array.Resize(list, length, paddingElement)
A list cropped or padded to a length. Positions past the old end take the padding element. It is read only; for a two way length that writes the resized list back, use SizeBinding.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to resize. |
length | Number or Sprites.Reactive.Value | The new length. |
paddingElement | Any or Sprites.Reactive.Value | The value for positions past the old end. |
Returns a read-only Sprites.Reactive.Value holding the resized list.
const list = Sprites.Reactive.Value(['a', 'b', 'c']);
const length = Sprites.Reactive.Value(2);
const sized = Sprites.Array.Resize(list, length, '.');
Sprites.Ui.Input.Number(length, 0, 7);
const joined = Sprites.Text.Join(sized, ', ');
Sprites.Ui.Dom.Text(' sized = ', joined);Sprites.Array.Set Sprites.Reactive.Value
Sprites.Array.Set(list, index, value)
A new list with the item at index replaced by value. An index inside the range keeps every other item as it stands; an index outside the range keeps the whole list as it is. Each argument may be a constant or a reactive value, so the result follows them.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to replace an item in. |
index | Number or Sprites.Reactive.Value | The position of the item replaced. |
value | Any or Sprites.Reactive.Value | The new value at the index. |
Returns a read-only Sprites.Reactive.Value holding the new list, or the list unchanged when the index is out of range.
const list = Sprites.Reactive.Value(['a', 'b', 'c']);
const index = Sprites.Reactive.Value(1);
const updated = Sprites.Array.Set(list, index, 'X');
Sprites.Ui.Input.Number(index, 0, 2);
const joined = Sprites.Text.Join(updated, ', ');
Sprites.Ui.Dom.Text(' list = ', joined);Sprites.Array.SizeBinding Sprites.Reactive.Value
Sprites.Array.SizeBinding(list, paddingElement)
A two way binding to a list's length. Read, it is the item count; set, it resizes the list, cropping when smaller and padding with the padding element when larger, and writes the new list back. Every set is valid, so the binding is always settable; for a read only count use Length.
| Input | Type | Description |
|---|---|---|
list | Sprites.Reactive.Value | The list value it reads and writes. |
paddingElement | Any or Sprites.Reactive.Value | The value for new positions when growing. |
Returns a two-way Sprites.Reactive.Value over the list's length.
const list = Sprites.Reactive.Value(['a', 'b', 'c']);
const size = Sprites.Array.SizeBinding(list, '.');
Sprites.Ui.Input.Number(size, 0, 8);
const joined = Sprites.Text.Join(list, ', ');
Sprites.Ui.Dom.Text(' list = ', joined);Sprites.Array.Slice Sprites.Reactive.Value
Sprites.Array.Slice(list, start, end)
A shallow slice of a list, from start up to end. Leave end out for the rest. Each argument may be a constant or a reactive value.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to slice. |
start | Number or Sprites.Reactive.Value | The first index kept. |
end | Number or Sprites.Reactive.Value | Optional. The index to stop before. |
Returns a read-only Sprites.Reactive.Value holding the slice.
const list = Sprites.Reactive.Value([1, 2, 3, 4, 5]);
const count = Sprites.Reactive.Value(3);
const head = Sprites.Array.Slice(list, 0, count);
Sprites.Ui.Input.Number(count, 0, 5);
const joined = Sprites.Text.Join(head, ', ');
Sprites.Ui.Dom.Text(' head = ', joined);Sprites.Array.Some Sprites.Reactive.Value
Sprites.Array.Some(list, match)
True when match returns true for some item. match is a plain function of an item. list may be a constant or a reactive value, so the result follows it.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list to test. |
match | Function | A plain function of an item, true for a matching item. |
Returns a read-only Sprites.Reactive.Value, true while some item matches.
const list = Sprites.Reactive.Value([2, 4, 6]);
const hasOdd = Sprites.Array.Some(list, (n) => {
return n % 2 === 1;
});
Sprites.Ui.Button.Push(list, 7, 'Add 7');
Sprites.Ui.Dom.Text(' hasOdd = ', hasOdd);Sprites.Array.Choose Sprites.Reactive.Value
Sprites.Array.Choose(mask, on, off)
A list built from a mask list and two values: where a mask element is set the output takes the on value, else the off value. So a one bit glyph row becomes a row of the ink colour where a pixel is set and the paper colour where it is clear. A primitive: one Calculate over a raw map, so a whole cell folds in one step rather than one node per pixel.
| Input | Type | Description |
|---|---|---|
mask | Array or Sprites.Reactive.Value | The list whose set elements pick the on value. |
on | any or Sprites.Reactive.Value | The value a set element takes. |
off | any or Sprites.Reactive.Value | The value a clear element takes. |
Returns a read-only Sprites.Reactive.Value holding the chosen list.
Sprites.Array.Lookup Sprites.Reactive.Value
Sprites.Array.Lookup(list, table, indexed)
A list with each element resolved through a table, or kept as it stands. indexed true reads the table at each element, so a slot index becomes the colour there; indexed false returns the element unchanged, a packed colour already. A primitive: one Calculate over a raw map, in one node, so a change recomputes the array once rather than one node per element.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list of elements, indices or values. |
table | Array or Sprites.Reactive.Value | The table an index reads from. |
indexed | Boolean or Sprites.Reactive.Value | True to read the table at each element, false to keep the element. |
Returns a read-only Sprites.Reactive.Value holding the resolved list.
Sprites.Array.Concat Sprites.Reactive.Value
Sprites.Array.Concat(first, second)
A new list of the elements of first then the elements of second. A missing list counts as empty, so a join with nothing keeps the other whole. A primitive: one Calculate over the raw join, since concatenation is a base array operation nothing else composes.
| Input | Type | Description |
|---|---|---|
first | Array or Sprites.Reactive.Value | The list whose elements come first. |
second | Array or Sprites.Reactive.Value | The list whose elements follow. |
Returns a read-only Sprites.Reactive.Value holding the joined list.
const a = Sprites.Reactive.Value([1, 2]);
const b = Sprites.Reactive.Value([3, 4]);
const joined = Sprites.Array.Concat(a, b);
const length = Sprites.Array.Length(joined);
Sprites.Ui.Dom.Text('length ', length);Sprites.Array.KeyBy Sprites.Reactive.Value
Sprites.Array.KeyBy(list, keyName, valueName)
An object mapping each record's key field to its value field, so a list of records reads as a lookup by one of their fields. A later record with the same key wins. A missing list is the empty object. A primitive: one Calculate over the raw fold, since building a lookup is a base operation nothing else composes. Pair it with Sprites.Object.At to read the lookup by a reactive key.
| Input | Type | Description |
|---|---|---|
list | Array or Sprites.Reactive.Value | The list of records. |
keyName | String or Sprites.Reactive.Value | The field whose value becomes each entry's key. |
valueName | String or Sprites.Reactive.Value | The field whose value becomes each entry's value. |
Returns a read-only Sprites.Reactive.Value holding the lookup object.
const rows = Sprites.Reactive.Value([
{ id: 'a', name: 'Red' },
{ id: 'b', name: 'Green' }
]);
const byId = Sprites.Array.KeyBy(rows, 'id', 'name');
const name = Sprites.Object.At(byId, 'b');
Sprites.Ui.Dom.Text('b → ', name);