Lists functions ================== **Contract / Module:** * free.util-lists General functions ----------------- enforce-not-empty ~~~~~~~~~~~~~~~~~ *in* ``list`` *→* ``bool`` Verify and enforces that a list is not empty. .. code:: lisp pact> (enforce-not-empty [1, 2, 3]) true pact> (enforce-not-empty []) util-lists.pact:22:4: List cannot be empty at :0:0: (enforce-not-empty []) is-empty ~~~~~~~~ *in* ``list`` *→* ``bool`` Return true if the list is empty. .. code:: lisp pact> (is-empty []) true pact> (is-empty ["a" "b"]) false is-singleton ~~~~~~~~~~~~ *in* ``list`` *→* ``bool`` Return true if the list has exactly 1 element. .. code:: lisp pact> (is-singleton ["a"]) true pact> (is-empty ["a" "b"]) false is-pair ~~~~~~~ *in* ``list`` *→* ``bool`` Return true if the list has exactly 2 elements. .. code:: lisp pact> (is-pair ["a"]) false pact> (is-pair ["a" "b"]) true is-not-empty ~~~~~~~~~~~~ *in* ``list`` *→* ``bool`` Return true if the list is not empty. .. code:: lisp pact> (is-not-empty []) false pact> (is-not-empty ["a" "b"]) true enforce-list-bounds ~~~~~~~~~~~~~~~~~~~~~ *in* ``list`` *idx* ``integer`` *→* ``bool`` Verify and ENFORCES that *idx* is in list bounds. | *idx* must be >= 0 and <= length *in* .. code:: lisp pact> (enforce-list-bounds [1,2,3] 0) true pact> (enforce-list-bounds [1,2,3] 1) true pact> (enforce-list-bounds [1,2,3] 2) true pact> (enforce-list-bounds [1,2,3] 3) util-lists.pact:26:4: Index out of bounds at :0:0: (enforce-list-bounds [1 2 3] 3) pact> (enforce-list-bounds [1,2,3] -1) util-lists.pact:26:4: Index out of bounds at :0:0: (enforce-list-bounds [1 2 3] -1) chain ~~~~~~ *in* ``list`` *→* ``list`` Chain list of lists: | All lists are chained to build a new unique list. .. code:: lisp pact> (chain [ [1,2], [3,4,5], [6,7,8] ]) [1 2 3 4 5 6 7 8] enumerate-list ~~~~~~~~~~~~~~~ *in* ``list`` *→* ``[object]`` Return a list of objects ``{'i:idx, 'v:value}`` where *'i* is the index, and *'v* the value. .. code:: lisp pact> (enumerate-list ["a", "b", "c"]) [{"i": 0,"v": "a"} {"i": 1,"v": "b"} {"i": 2,"v": "c"}] contains* ~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``bool`` Starred version of contains for list => arguments inverted. Useful for mapping and filtering .. code:: lisp pact> (contains* ["a", "b", "c"] "c") true pact> (contains* ["a", "b", "c"] "d") false first ~~~~~ *in* ``[]`` *→* ```` Return the first item of a list. .. code:: lisp pact> (first ["a", "b", "c"]) "a" last ~~~~~ *in* ``[]`` *→* ```` Return the last item of a list. .. code:: lisp pact> (last ["a", "b", "c"]) "c" at* ~~~ *in* ``[]`` *idx* ``integer`` *default* ```` *→* ```` *Starred version of the standard Pact function* ``(at )`` Return the element at *idx*, but returns *default* if the list is too short. .. code:: lisp pact> (at* ["a" "b" "c"] 1 "def") "b" pact> (at* ["a" "b" "c"] 4 "def") "def" Search Functions ----------------- search ~~~~~~~ *in* ``[]`` *item* ```` *→* ``[integer]`` Search an *item* into the list and returns a list of indexes. .. code:: lisp pact> (search ["a", "b", "a", "c"] "a") [0 2] pact> (search ["a", "b", "a", "c"] "b") [1] pact> (search ["a", "b", "a", "c"] "d") [] count ~~~~~ *in* ``[]`` *item* ```` *→* ``integer`` Returns the number of occurrences of an *item*. .. code:: lisp pact> (count ["a", "b", "a", "c"] "a") 2 pact> (count ["a", "b", "a", "c"] "b") 1 pact> (count ["a", "b", "a", "c"] "d") 0 Creation and extension functions --------------------------------- make-list-like ~~~~~~~~~~~~~~~ *in* ``[]`` *value* ```` *→* ``[]`` Creates a new list whose size is the same as *in*, by repeating *value*. This is just a simple improvement of the native ``(make-list)``. .. code:: lisp pact> (make-list-like [1 2 3 4 5] 1.0) [1.0 1.0 1.0 1.0 1.0] extend ~~~~~~ *in* ``[]`` *new-length* ``integer`` *value* ```` *→* ``[]`` Extend a list to *new-length* by repeating *value*. .. code:: lisp pact> (extend [1.0 1.0] 5 2.0) [1.0 1.0 2.0 2.0 2.0] extend-like ~~~~~~~~~~~~ *in* ``[]`` *target* ``[]`` *value* ```` *→* ``[]`` Extends a list to the same length as *target*, by repeating *value*. .. code:: lisp pact> (extend-like [1.0 1.0] [1 2 3 4 5] 2.0) [1.0 1.0 2.0 2.0 2.0] Insertion functions -------------------- insert-first ~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Insert an item at the left of the list. .. code:: lisp pact> (insert-first ["a", "b", "c"] "d") ["d" "a" "b" "c"] append-last ~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Append an item at the end of the list. .. code:: lisp pact> (append-last ["a", "b", "c"] "d") ["a" "b" "c" "d"] insert-at ~~~~~~~~~~~~ *in* ``[]`` *idx* ``integer`` *item* ```` *→* ``[]`` Insert an item at position *idx*. .. code:: lisp pact> (insert-at ["a", "b", "c"] 0 "d") ["d" "a" "b" "c"] pact> (insert-at ["a", "b", "c"] 1 "d") ["a" "d" "b" "c"] pact> (insert-at ["a", "b", "c"] 3 "d") ["a" "b" "c" "d"] insert-at* ~~~~~~~~~~~~ *in* ``[]`` *idx* ``integer`` *item* ```` *default* ```` *→* ``[]`` Starred version of ``(insert-at )``. When the list is too short, don't fail (like ``(insert-at )``). But add as many *default* elements to match the needed size. .. code:: lisp pact> (insert-at* ["a", "b", "c"] 0 "d" "unknown") ["d" "a" "b" "c"] pact> (insert-at* ["a", "b", "c"] 5 "d" "unknown") ["a" "b" "c" "unknown" "unknown" "d"] Replacement functions ---------------------- replace-first ~~~~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Replace the first item of the list. .. code:: lisp pact> (replace-first ["a", "b", "c"] "d") ["d" "b" "c"] replace-last ~~~~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Replace the last item of the list. .. code:: lisp pact> (replace-last ["a", "b", "c"] "d") ["a" "b" "d"] replace-at ~~~~~~~~~~~~~~~ *in* ``[]`` *idx* ``integer`` *item* ```` *→* ``[]`` Replace the item at position *idx*. .. code:: lisp pact> (replace-at ["a", "b", "c"] 0 "d") ["d" "b" "c"] pact> (replace-at ["a", "b", "c"] 1 "d") ["a" "d" "c"] replace-at* ~~~~~~~~~~~~ *in* ``[]`` *idx* ``integer`` *item* ```` *default* ```` *→* ``[]`` Starred version of ``(replace-at )``. When the list is too short, don't fail (like ``(replace-at )``). But add as many *default* elements to match the needed size. .. code:: lisp pact> (replace-at* ["a", "b", "c"] 0 "d" "unknown") ["d" "b" "c"] pact> (replace-at* ["a", "b", "c"] 5 "d" "unknown") ["a" "b" "c" "unknown" "unknown" "d"] replace-item ~~~~~~~~~~~~~~~ *in* ``[]`` *old-item* ```` *new-item* ```` *→* ``[]`` Replace each occurrence of *old-item* by *new-item*. .. code:: lisp pact> (replace-item ["a", "b", "c", "a"] "c" "rep") ["a" "b" "rep" "a"] pact> (replace-item ["a", "b", "c", "a"] "a" "rep") ["rep" "b" "c" "rep"] pact> (replace-item ["a", "b", "c", "a"] "not" "rep") ["a" "b" "c" "a"] replace-item* ~~~~~~~~~~~~~~~ *in* ``[]`` *old-item* ```` *new-item* ```` *→* ``[]`` Replace each occurrence of *old-item* by *new-item* but raises an error if *old-item* does not exist. .. code:: lisp pact> (replace-item* ["a", "b", "c", "a"] "c" "rep") ["a" "b" "rep" "a"] pact> (replace-item* ["a", "b", "c", "a"] "a" "rep") ["rep" "b" "c" "rep"] pact> (replace-item* ["a", "b", "c", "a"] "not" "rep") util-lists.pact:110:4: The item is not present in the list at :0:0: (replace-item* ["a" "b" "c" "a"] "not" "rep") Removal functions ---------------------- remove-first ~~~~~~~~~~~~~~~ *in* ``[]`` *→* ``[]`` Remove first element from the list. .. code:: lisp pact> (remove-first ["a", "b", "c"] ) ["b" "c"] remove-last ~~~~~~~~~~~~~~~ *in* ``[]`` *→* ``[]`` Remove last element from the list. .. code:: lisp pact> (remove-last ["a", "b", "c"] ) ["a" "b"] remove-at ~~~~~~~~~~~~~~~ *in* ``[]`` *idx* ``integer`` *→* ``[]`` Remove element at position *idx*. .. code:: lisp pact> (remove-at ["a", "b", "c"] 0) ["b" "c"] pact> (remove-at ["a", "b", "c"] 1) ["a" "c"] pact> (remove-at ["a", "b", "c"] 2) ["a" "b"] remove-item ~~~~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Remove an item from a list. .. code:: lisp pact> (remove-item ["a", "b", "c", "a", "d"] "a") ["b" "c" "d"] pact> (remove-item ["a", "b", "c", "a", "d"] "b") ["a" "c" "a" "d"] pact> (remove-item ["a", "b", "c", "a", "d"] "e") ["a" "b" "c" "a" "d"] remove-item* ~~~~~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Remove and item from the list but raises an error if it does not exist. .. code:: lisp pact> (remove-item* ["a", "b", "c", "a", "d"] "a") ["b" "c" "d"] pact> (remove-item* ["a", "b", "c", "a", "d"] "b") ["a" "c" "a" "d"] pact> (remove-item* ["a", "b", "c", "a", "d"] "e") util-lists.pact:140:4: The item is not present in the list at :0:0: (remove-item* ["a" "b" "c" "a" "d"] "e") Shifts and Rolls ---------------- shift-left ~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Shift a list to the left, and append an element. The leftmost (first) element is trashed .. code:: lisp pact> (shift-left ["a", "b", "c", "d"] "x") ["b" "c" "d" "x"] pact> (shift-left (shift-left ["a", "b", "c", "d"] "x") "y") ["c" "d" "x", "y"] shift-right ~~~~~~~~~~~ *in* ``[]`` *item* ```` *→* ``[]`` Shift a list to the right, and insert an element at the first position. The rightmost (last) element is trashed. .. code:: lisp pact> (shift-right ["a", "b", "c", "d"] "x") ["x" "a" "b" "c"] pact> (shift-right (shift-right ["a", "b", "c", "d"] "x") "y") ["y" "x" "a", "b"] roll-left ~~~~~~~~~~~ *in* ``[]`` *→* ``[]`` Roll a list from right to left. .. code:: lisp pact> (roll-left ["a", "b", "c", "d"]) ["b" "c" "d" "a"] pact> (roll-left (roll-left ["a", "b", "c", "d"])) ["c" "d" "a", "b"] roll-right ~~~~~~~~~~~ *in* ``[]`` *→* ``[]`` Roll a list from left to right. .. code:: lisp pact> (roll-right ["a", "b", "c", "d"]) ["d" "a" "b" "c"] pact> (roll-right (roll-right ["a", "b", "c", "d","e"])) ["d" "e" "a" "b" "c"] fifo-push ~~~~~~~~~~ *in* ``[]`` *fifo-size* ``integer`` *item* ```` *→* ``[]`` This function push an element into a defined size (by *fifo-size*) FIFO. *fifo-size* is target size If the current size is less then *fifo-size*, the element is only append. If the current size is equal to *fifo-size*, it means that the FIFO is full, the FIFO is shifted. .. code:: lisp pact> (fifo-push* ["a", "b", "c", "d"] 5 "x") ["a" "b" "c" "d" "x"] pact> (fifo-push* ["a", "b", "c", "d", "x"] 5 "y") ["b," "c" "d" "x", "y"]