Skip to main content

Lists in Bitbybit

Lists category icon

View Full Source & Details on GitHub

bitbybit.lists reads, builds and reshapes lists. A list is a plain JavaScript array, so it can hold anything: numbers, texts, points, shapes, or other lists, as in [1, 2, 3], ["apple", "banana"] or [[0,0,0], [1,1,1]].

Two rules first​

  • Positions count from 0: index 0 is the first item.
  • clone keeps your input as it was. Most functions take a clone option, on by default, that deep-copies the list (with structuredClone) before working on it. Switched off, the functions that add, remove, reverse, shuffle or sort change the list you pass in, which is faster on large data. Data with circular references cannot be copied, and cloning it throws. removeAllItems has no such option: it always empties the list it is given.

Building lists​

  • createEmptyList gives [].
  • repeat gives a list that holds the same item times times.
  • repeatInPattern repeats a list of items over and over until the result is lengthLimit long, so [1, 2, 3] to length 7 gives [1, 2, 3, 1, 2, 3, 1].
  • concatenate joins several lists end to end.

Reading items​

  • getItem reads the item at an index; an index outside the list throws. getFirstItem and getLastItem read the ends and throw on an empty list.
  • getSubList cuts out the items from indexStart up to, but not including, indexEnd.
  • getNthItem keeps every nth item: an item is kept when its index plus offset divides evenly by nth. getByPattern keeps the items where a repeating true/false pattern says true.
  • randomGetThreshold keeps each item with probability threshold, so the result differs on every call.
  • includes tells whether an item is in the list and findIndex gives its first index, or -1. Both compare by identity: an object is found only if the very same object is in the list.

Here getNthItem keeps every second of two hundred spiral points, and a smooth curve passes through the points kept:

Bitbybit Platform

Every second point of a spiral in Rete

rete logoRete
Script Source (rete)
{
  "id": "rete-v2-json",
  "nodes": {
    "spiral": {
      "id": "spiral",
      "name": "bitbybit.point.spiral",
      "customName": "spiral",
      "async": false,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "phi": 0.9,
        "numberPoints": 200,
        "widening": 3,
        "radius": 6,
        "factor": 1
      },
      "inputs": {},
      "position": [
        40,
        40
      ]
    },
    "kept": {
      "id": "kept",
      "name": "bitbybit.lists.getNthItem",
      "customName": "get nth item",
      "async": false,
      "drawable": false,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "nth": 2,
        "offset": 0,
        "clone": true
      },
      "inputs": {
        "list": {
          "connections": [
            {
              "node": "spiral",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        460,
        40
      ]
    },
    "curve": {
      "id": "curve",
      "name": "bitbybit.occt.shapes.wire.interpolatePoints",
      "customName": "interpolate points",
      "async": true,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "periodic": false,
        "tolerance": 1e-7,
        "parametrization": "chordLength"
      },
      "inputs": {
        "points": {
          "connections": [
            {
              "node": "kept",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        880,
        40
      ]
    }
  },
  "modules": {}
}

Measuring​

  • listLength counts the items.
  • getListDepth gives how deeply lists are nested: [1, 2] is 1, [[1, 2], [3]] is 2.
  • getLongestListLength gives the length of the longest of several lists.

Adding and removing items​

  • addItem adds an item at the end, prependItem at the start, and addItemFirstLast at whichever end position names.
  • addItemAtIndex inserts an item at an index. addItemAtIndexes inserts the same item at several indexes, and addItemsAtIndexes inserts one item per index; both count the indexes on the list as it was before any insertion. addItemsAtIndexes throws unless there is one index per item, in ascending order.
  • removeItemAtIndex removes the item at an index, and removeItemAtIndexFromEnd counts from the end, where 0 is the last item. removeItemsAtIndexes removes several, all counted on the original list. removeFirstItem and removeLastItem remove the ends. Indexes outside the list are ignored.
  • removeNthItem removes the items getNthItem would keep, and randomRemoveThreshold drops each item with probability threshold.
  • removeAllItems empties the list in place.

Removing duplicates​

  • removeDuplicates keeps the first occurrence of each item, comparing by identity, so two equal-looking objects both stay.
  • removeDuplicateNumbers does the same for numbers, and removeDuplicateNumbersTolerance also counts numbers closer than tolerance (default 1e-7) as the same, so floating-point noise does not leave near copies.

Reshaping​

  • reverse reverses the order; shuffle puts the items in a random order.
  • groupNth splits the list into groups of nrElements. Items left over at the end are dropped unless keepRemainder is on.
  • flipLists turns a list of lists on its side, so rows become columns: [[0, 1, 2], [3, 4, 5]] gives [[0, 3], [1, 4], [2, 5]]. The inner lists must all have the same length, or it throws.
  • mergeElementsOfLists regroups lists by position, the first items together, then the second, and so on. Unlike flipLists it accepts lists of different lengths. level says how deep inside each list to regroup, and the result keeps that much nesting around the groups.
  • interleave weaves lists into one, taking the first item of each, then the second of each: [[0, 1, 2], [3, 4, 5]] gives [0, 3, 1, 4, 2, 5]. A shorter list drops out once it runs dry.

Sorting​

  • sortNumber sorts numbers, lowest first when orderAsc is on (the default) or highest first.
  • sortTexts sorts texts by character code, so capitals come before lower case: ["b", "a", "C"] gives ["C", "a", "b"].
  • sortByPropValue sorts objects by the number held in their property.

Every function​

FunctionWhat it does
addItemAdds an item at the end of the list.
addItemAtIndexInserts an item at a position; the items from that position on shift up by one.
addItemAtIndexesInserts the same item at several positions of the original list.
addItemFirstLastAdds an item at the start or at the end of the list, as chosen.
addItemsAtIndexesInserts several items, the first at the first index, the second at the second, and so on, all counted on the original list.
concatenateJoins several lists into one, end to end.
createEmptyListMakes a new list with nothing in it.
findIndexFinds the position of the first occurrence of an item, or -1 when it is not in the list.
flipListsTurns a list of lists on its side: rows become columns and columns become rows.
getByPatternKeeps the items where a repeating true/false pattern says true and drops the others.
getFirstItemReads the first item of the list.
getItemReads the item at a position in the list, counting from 0.
getLastItemReads the last item of the list.
getListDepthMeasures how deeply lists are nested inside the list.
getLongestListLengthMeasures the longest list among several.
getNthItemKeeps every nth item, starting from an offset.
getSubListCuts out the items from a start index up to, but not including, an end index.
groupNthSplits the list into groups of n items.
includesTells whether an item is in the list.
interleaveWeaves several lists into one by taking the first item of each in turn, then the second of each, and so on.
listLengthCounts the items in the list.
mergeElementsOfListsRegroups nested lists by position: the first items of every list go together, then the second items, and so on.
prependItemAdds an item at the start of the list.
randomGetThresholdKeeps each item of the list with a given probability and drops the rest, so the result differs on every call.
randomRemoveThresholdDrops each item of the list with a given probability and keeps the rest, so the result differs on every call.
removeAllItemsEmpties the list it is given, in place: the same array comes back with no items in it.
removeDuplicateNumbersRemoves repeated numbers, keeping the first occurrence of each.
removeDuplicateNumbersToleranceRemoves numbers that are within a tolerance of one already kept, so values that differ only by floating-point noise count as the same.
removeDuplicatesRemoves repeated items of any kind, keeping the first occurrence of each.
removeFirstItemRemoves the first item.
removeItemAtIndexRemoves the item at a position.
removeItemAtIndexFromEndRemoves an item counted from the end: index 0 is the last item, 1 the one before it.
removeItemsAtIndexesRemoves the items at several positions, all counted on the original list.
removeLastItemRemoves the last item.
removeNthItemRemoves every nth item, starting from an offset.
repeatMakes a list that holds the same item a number of times.
repeatInPatternRepeats a pattern of items over and over until the list reaches a given length.
reverseReverses the order of the items.
shufflePuts the items in a random order, different on every call.
sortByPropValueSorts objects by the number held in one of their properties.
sortNumberSorts numbers from lowest to highest, or from highest to lowest.
sortTextsSorts texts alphabetically, from A to Z or from Z to A.