Series "getters"
There are so many commands to manipulate series that I have split them into two chapters: one for the commands that get information from a series, that I call "getters", and another for the commands that change the series directly.
The "getter" commands only return values, without altering the series. Notice that any "getter" command may be used to change the series if you reassign the series to the returned value.
length?
Returns the size of a series from the current index to the end.
>> a: [1 3 5 7 9 11 13 15 17]
== [1 3 5 7 9 11 13 15 17]
>> length? a
== 9
>> length? find a 13 ;see the command "find".
== 3 ;from "13" to the tail there are 3 elements
empty?
Returns true
if a series is empty, otherwise returns false
.
>> a: [3 4 5]
== [3 4 5]
>> empty? a
== false
>> b:[]
== []
>> empty? b
== true
pick
Picks the value from a series at the position given by the second argument.
>> pick ["cat" "dog" "mouse" "fly"] 2
>> == "dog"
>> pick "delicious" 4
>> == #"i"
at
Returns the series at a given index.
>> at ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] 4
== ["cow" "fly" "ant" "bee"]
select & find
Both search a series for a given value. The search goes from left to right, except if /reverse
or /last
is used.
When they find a match:
select
returns the next element from the series after the match;
>> select ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow"]
== "fly"
find
returns a series that starts in the match and goes all the way to tail.>> find ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow"] == ["cow" "fly" "ant" "bee"]
/part
Limits the length of the area to be searched to a given number of elements. In the image below, the search area is highlighted:
>> find/part ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow"] 3
== none
>> find/part ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow"] 4
== ["cow" "fly" "ant" "bee"]
/only
Treat a series search value as a block, so it looks for a block inside the search area.
>> find/only ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow" "fly"] ;finds nothing
== none
>> find/only ["cat" "dog" "fox" ["cow" "fly"] "ant" "bee" ] ["cow" "fly"] ; finds the block
== [["cow" "fly"] "ant" "bee"]
/case
To perform a case sentive search. Upper and lower case become relevant.
/skip
Treats the series as a set of records, where each record has a fixed size. Will only try to match against each first item of such a record
>> find/skip ["cat" "dog" "fox" "dog" "dog" "dog" "cow" "dog" "fly" "dog" "ant" "dog" "bee" "dog"] ["dog"] 2
== ["dog" "dog" "cow" "dog" "fly" "dog" "ant" "dog" "bee" "dog"]
I highlighted below the "records" in yellow and the match in red:
/last
Finds the last occurrence of the key, from the tail
>> find/last [33 11 22 44 11 12] 11
== [11 12]
/reverse
The same as /last
, but from the current index that can be set, for example by the at
command.
find/tail
Normally find
returns the result including the matched item. With /tail
the returned is the part AFTER the match, similarly to select
>> find ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] "fly"
== ["fly" "ant" "bee"]
>> find/tail ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] "fly"
== ["ant" "bee"]
find/match
Match always compares the key to the beginning of the series. Also, the result is the part AFTER the match.
>> find/match ["cat" "dog" "fox" "cow" "fly" "ant" "bee"] "fly"
== none ;no match
>> find/match ["cat" "dog" "fox" "cow" "fly" "ant" "bee"] "cat"
== ["dog" "fox" "cow" "fly" "ant" "bee"] ;match
last
Returns the last value of the series.
>> last ["cat" "dog" "fox" "cow" "fly" "ant" "bee"]
== "bee"
extract
Extracts values from a series at given intervals, returning a new series.
>> extract [1 2 3 4 5 6 7 8 9] 3
== [1 4 7]
>> extract "abcdefghij" 2
== "acegi"
/index
Extracts values starting from a given position.
/into
Append the extracted values to a given series.
>> newseries: [] ;creates empty series - necessary as extract/into does not initialize a series
== []
>> extract/into "abcdefghij" 2 newseries
== [#"a" #"c" #"e" #"g" #"i"]
>> extract/into ["cat" "dog" "fox" "cow" "fly" "ant" "bee" "owl"] 2 newseries
== [#"a" #"c" #"e" #"g" #"i" "cat" "fox" "fly" "bee"]
copy
See Copying chapter.
Sets
union
Returns the result of joining two series. Duplicate entries are only included once.
>> union [3 4 5 6] [5 6 7 8]
== [3 4 5 6 7 8]
Allows the refinements:
/case
: use case-sensitive comparison
/skip
: treat the series as fixed size records.
>> union/case [A a b c] [b c C]
== [A a b c C]
With the /skip refinement, only the first element of each group (size given by argument) is compared. If there are duplicate entries, the record of the first series is kept:
difference
Returns only the elements that are not present in both series.
>> difference [3 4 5 6] [5 6 7 8]
== [3 4 7 8]
Allows the refinements:
/case
: use case-sensitive comparison
/skip
: treat the series as fixed size records.
intersect
Returns only the elements that are present in both series:
>> intersect [3 4 5 6] [5 6 7 8]
== [5 6]
Allows the refinements:
/case
: use case-sensitive comparison
/skip
: treat the series as fixed size records.
unique
Returns the series removing all duplicates:
>> unique [1 2 2 3 4 4 1 7 7]
== [1 2 3 4 7]
Allows the refinements:
/skip
: treat the series as fixed size records.
exclude
Returns a series where the second argument elements are removed from the first argument series.
>> a: [1 2 3 4 5 6 7 8]
== [1 2 3 4 5 6 7 8]
>> exclude a [2 5 8]
== [1 3 4 6 7]
>> a
== [1 2 3 4 5 6 7 8]
It is not well documented, but I think the returned series is a list of non-repeated
elements:
>> exclude "my house is a very funny house" "aeiou"
== "my hsvrfn"
>> exclude [1 1 2 2 3 3 4 4 5 5 6 6] [2 4]
== [1 3 5 6]
Allows /case
and /skip
refinements.