Series "getters"
There are so many commands to manipulate series that I have split them into two chapters: one for the built-in functions (commands) that get information from a series, that I call "getters", and another for those 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.
action! length? Red-by-example MyCode4fun
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
function! empty? Red-by-example MyCode4fun
Returns true if a series is empty, otherwise returns false.
>> a: [3 4 5]
== [3 4 5]
>> empty? a
== false
>> b:[]
== []
>> empty? b
== true
action! pick Red-by-example MyCode4fun
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"
action! at Red-by-example MyCode4fun
Returns the series at a given index.
>> at ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] 4
== ["cow" "fly" "ant" "bee"]
action! select and action! find Red-by-example on select Red-by-example on find MyCode4fun on select MyCode4fun on 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"]
An example of select:
>> movies: [
title "Gone with the wind"
star "Scarlet Something"
quality "pretty good"
age "very old"
]
>> print select movies 'quality
pretty good
Is interesting to note that a "shortcut" for select is the path notation:
>> print movies/star
Scarlet Something
/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:
>> select/part ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["cow"] 3
== none
>> select/part ["cat" "dog" "fox" "cow" "fly" "ant" "bee" ] ["fox"] 3
== "cow"
>> 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.
I highlighted below the "records" in yellow and the match in red:
>> 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"]
/same
Uses same? as comparator. This comparator returns true if the two objects have the same identity:
>> a: "dog" b: "dog"
== "dog"
>> same? a b
== false ;each is associated with a string with "dog", but not the same string.
>> b: a
== "dog"
>> same? a b ;both refer to the very same string
== true
/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 built-in function at .
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
function! last Red-by-example MyCode4fun
Returns the last value of the series.
>> last ["cat" "dog" "fox" "cow" "fly" "ant" "bee"]
== "bee"
function! extract Red-by-example MyCode4fun
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"]
action! copy Red-by-example MyCode4fun
See Copying chapter.
Sets
native! union Red-by-example MyCode4fun
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]
/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:
>> union/skip [a b c c d e e f f] [a j k c y m e z z] 3
== [a b c c d e e f f]
>> union/skip [k b c c d e e f f] [a j k c y m e z z] 3
== [k b c c d e e f f a j k]
native! difference Red-by-example
Returns only the elements that are not present in both series.
>> difference [3 4 5 6] [5 6 7 8]
== [3 4 7 8]
/case
Use case-sensitive comparison
/skip
Treat the series as fixed size records.
native! intersect Red-by-example
Returns only the elements that are present in both series:
>> intersect [3 4 5 6] [5 6 7 8]
== [5 6]
/case
Use case-sensitive comparison
/skip
Treat the series as fixed size records.
native! unique Red-by-example MyCode4fun
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.
native! exclude Red-by-example
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]
I could not find it in documentation, 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]
/case
Use case-sensitive comparison
/skip
Treat the series as fixed size records.