 |
Up |  |
TOC | Index | |||
| << 7 Included Tools | < 8.15 Searching | Up: 8 API Reference | 8.17 Serialization of Euphoria Objects > | 9 Release Notes >> | |||
8.16 Sequence Manipulation
8.16.1 Constants
8.16.1.1 ADD_PREPEND
include std/sequence.e namespace stdseq public enum ADD_PREPEND
8.16.1.2 ADD_APPEND
include std/sequence.e namespace stdseq public enum ADD_APPEND
8.16.1.3 ADD_SORT_UP
include std/sequence.e namespace stdseq public enum ADD_SORT_UP
8.16.1.4 ADD_SORT_DOWN
include std/sequence.e namespace stdseq public enum ADD_SORT_DOWN
8.16.1.5 ROTATE_LEFT
include std/sequence.e namespace stdseq public constant ROTATE_LEFT
8.16.1.6 ROTATE_RIGHT
include std/sequence.e namespace stdseq public constant ROTATE_RIGHT
8.16.2 Basic routines
8.16.2.1 binop_ok
include std/sequence.e namespace stdseq public function binop_ok(object a, object b)
Checks whether two objects can perform a sequence operation together.
Parameters:
- a : one of the objects to test for compatible shape
- b : the other object
Returns:
An integer, 1 if a sequence operation is valid between a and b, else 0.
Example 1:
i = binop_ok({1,2,3},{4,5})
-- i is 0
i = binop_ok({1,2,3},4)
-- i is 1
i = binop_ok({1,2,3},{4,{5,6},7})
-- i is 1
See Also:
8.16.2.2 fetch
include std/sequence.e namespace stdseq public function fetch(sequence source, sequence indexes)
Retrieves an element nested arbitrarily deep into a sequence.
Parameters:
- source : the sequence from which to fetch
- indexes : a sequence of integers, the path to follow to reach the element to return.
Returns:
An object, which is source[indexes[1]][indexes[2]]...[indexes[$]]
Errors:
If the path cannot be followed to its end, an error about reading a nonexistent element, or subscripting an atom, will occur.
Comments:
The last element of indexes may be a pair {lower,upper}, in which case a slice of the innermost referenced sequence is returned.
Example 1:
x = fetch({0,1,2,3,{"abc","def","ghi"},6},{5,2,3})
-- x is 'f', or 102.
See Also:
store, Subscripting of Sequences
8.16.2.3 store
include std/sequence.e namespace stdseq public function store(sequence target, sequence indexes, object x)
Stores something at a location nested arbitrarily deep into a sequence.
Parameters:
- target : the sequence in which to store something
- indexes : a sequence of integers, the path to follow to reach the place where to store
- x : the object to store.
Returns:
A sequence, a copy of target with the specified place indexes modified by storing x into it.
Errors:
If the path to storage location cannot be followed to its end, or an index is not what one would expect or is not valid, an error about illegal sequence operations will occur.
Comments:
If the last element of indexes is a pair of integers, x will be stored as a slice three, the bounding indexes being given in the pair as {lower,upper}..
In Euphoria, you can never modify an object by passing it to a routine. You have to get a modified copy and then assign it back to the original.
Example 1:
s = store({0,1,2,3,{"abc","def","ghi"},6},{5,2,3},108)
-- s is {0,1,2,3,{"abc","del","ghi"},6}
See Also:
fetch, Subscripting of Sequences
8.16.2.4 valid_index
include std/sequence.e namespace stdseq public function valid_index(sequence st, object x)
Checks whether an index exists on a sequence.
Parameters:
- s : the sequence for which to check
- x : an object, the index to check.
Returns:
An integer, 1 if s[x] makes sense, else 0.
Example 1:
i = valid_index({51,27,33,14},2)
-- i is 1
See Also:
8.16.2.5 rotate
include std/sequence.e
namespace stdseq
public function rotate(sequence source, integer shift, integer start = 1,
integer stop = length(source))
Rotates a slice of a sequence.
Parameters:
- source : sequence to be rotated
- shift : direction and count to be shifted (ROTATE_LEFT or ROTATE_RIGHT)
- start : starting position for shift, defaults o 1
- stop : stopping position for shift, defaults to length(source)
Comments:
Use amount * direction to specify the shift. direction is either ROTATE_LEFT or ROTATE_RIGHT. This enables to shift multiple places in a single call. For instance, use ROTATE_LEFT * 5 to rotate left, 5 positions.
A null shift does nothing and returns source unchanged.
Example 1:
s = rotate({1, 2, 3, 4, 5}, ROTATE_LEFT)
-- s is {2, 3, 4, 5, 1}
Example 2:
s = rotate({1, 2, 3, 4, 5}, ROTATE_RIGHT * 2)
-- s is {4, 5, 1, 2, 3}
Example 3:
s = rotate({11,13,15,17,19,23}, ROTATE_LEFT, 2, 5)
-- s is {11,15,17,19,13,23}
Example 4:
s = rotate({11,13,15,17,19,23}, ROTATE_RIGHT, 2, 5)
-- s is {11,19,13,15,17,23}
See Also:
8.16.2.6 columnize
include std/sequence.e
namespace stdseq
public function columnize(sequence source, object cols = {}, object defval = 0)
Converts a set of sub sequences into a set of 'columns'.
Parameters:
- source : sequence containing the sub-sequences
- cols : either a specific column number or a set of column numbers. Default is 0, which returns the maximum number of columns.
- defval : an object. Used when a column value is not available. Default is 0
Comments:
Any atoms found in source are treated as if they are a 1-element sequence.
Example 1:
s = columnize({{1, 2}, {3, 4}, {5, 6}})
-- s is { {1,3,5}, {2,4,6}}
Example 2:
s = columnize({{1, 2}, {3, 4}, {5, 6, 7}})
-- s is { {1,3,5}, {2,4,6}, {0,0,7} }
s = columnize({{1, 2}, {3, 4}, {5, 6, 7},,-999})
--> Change the not-available value.
-- s is { {1,3,5}, {2,4,6}, {-999,-999,7} }
Example 3:
s = columnize({{1, 2}, {3, 4}, {5, 6, 7}}, 2)
-- s is { {2,4,6} } -- Column 2 only
Example 4:
s = columnize({{1, 2}, {3, 4}, {5, 6, 7}}, {2,1})
-- s is { {2,4,6}, {1,3,5} } -- Column 2 then column 1
Example 5:
s = columnize({"abc", "def", "ghi"})
-- s is {"adg", "beh", "cfi" }
8.16.2.7 apply
include std/sequence.e
namespace stdseq
public function apply(sequence source, integer rid, object userdata = {})
Apply a function to every element of a sequence returning a new sequence of the same size.
Parameters:
- source : the sequence to map
- rid : the routine_id of function to use as converter
- userdata : an object passed to each invocation of rid. If omitted, {} is used.
Returns:
A sequence, the length of source. Each element there is the corresponding element in source mapped using the routine referred to by rid.
Comments:
The supplied routine must take two parameters. The type of the first parameter must be compatible with all the elements in source. The second parameter is an object containing userdata.
Example 1:
function greeter(object o, object d)
return o[1] & ", " & o[2] & d
end function
s = apply({{"Hello", "John"}, {"Goodbye", "John"}},routine_id("greeter"),"!")
-- s is {"Hello, John!", "Goodbye, John!"}
See Also:
8.16.2.8 mapping
include std/sequence.e
namespace stdseq
public function mapping(object source_arg, sequence from_set, sequence to_set,
integer one_level = 0)
Each item from source_arg found in from_set is changed into the corresponding item in to_set
Parameters:
- source_arg : Any Euphoria object to be transformed.
- from_set : A sequence of objects representing the only items from source_arg that are actually transformed.
- to_set : A sequence of objects representing the transformed equivalents of those found in from_set.
- one_level : An integer. 0 (the default) means that mapping applies to every atom in every level of sub-sequences. 1 means that mapping only applies to the items at the first level in source_arg.
Returns:
An object, The transformed version of source_arg.
Comments:
- When one_level is zero or omitted, for each item in source_arg,
- if it is an atom then it may be transformed
- if it is a sequence, then the mapping is performed recursively on the sequence.
- This option required from_set to only contain atoms and contain no sub-sequences.
- When one_level is not zero, for each item in source_arg,
- regardless of whether it is an atom or sequence, if it is found in from_set then it is mapped to the corresponding object in to_set..
- Mapping occurs when an item in source_arg is found in from_set, then it is replaced by the corresponding object in to_set.
Example 1:
res = mapping("The Cat in the Hat", "aeiou", "AEIOU")
-- res is now "ThE CAt In thE HAt"
8.16.2.9 length
<built-in> function length(object target)
Return the length of an object.
Parameters:
- target : the object being queried
Returns:
An integer, the number of elements involved with target.
Comments:
- An atom only ever has a length of 1.
- The length of a sequence is the number of elements in the sequence.
- The length of each sequence is stored internally by the interpreter for fast access. In some other languages this operation requires a search through memory for an end marker.
Example 1:
length({{1,2}, {3,4}, {5,6}}) -- 3
length("") -- 0
length({}) -- 0
length( 7 ) -- 1
length( 3.14 ) -- 1
See Also:
8.16.2.10 reverse
include std/sequence.e namespace stdseq public function reverse(object target, integer pFrom = 1, integer pTo = 0)
Reverse the order of elements in a sequence.
Parameters:
- target : the sequence to reverse.
- pFrom : an integer, the starting point. Defaults to 1.
- pTo : an integer, the end point. Defaults to 0.
Returns:
A sequence, if target is a sequence, the same length as target and the same elements, but those with index between pFrom and pTo appear in reverse order.
Comments:
In the result sequence, some or all top-level elements appear in reverse order compared to the original sequence. This does not reverse any sub-sequences found in the original sequence.
The pTo parameter can be negative, which indicates an offset from the last element. Thus -1 means the second-last element and 0 means the last element.
Example 1:
reverse({1,3,5,7}) -- {7,5,3,1}
reverse({1,3,5,7,9}, 2, -1) -- {1,7,5,3,9}
reverse({1,3,5,7,9}, 2) -- {1,9,7,5,3}
reverse({{1,2,3}, {4,5,6}}) -- {{4,5,6}, {1,2,3}}
reverse({99}) -- {99}
reverse({}) -- {}
reverse(42) -- 42
8.16.2.11 shuffle
include std/sequence.e namespace stdseq public function shuffle(object seq)
Shuffle the elements of a sequence.
Parameters:
- seq: the sequence to shuffle.
Returns:
A sequence
Comments:
The input sequence does not have to be in any specific order and can contain duplicates. The output will be in an unpredictable order, which might even be the same as the input order.
Example 1:
shuffle({1,2,3,3}) -- {3,1,3,2}
shuffle({1,2,3,3}) -- {2,3,1,3}
shuffle({1,2,3,3}) -- {1,2,3,3}
8.16.3 Building sequences
8.16.3.1 series
include std/sequence.e namespace stdseq public function series(object start, object increment, integer count = 2, integer op = '+')
Returns a new sequence built as a series from a given object.
Parameters:
- start : the initial value from which to start
- increment : the value to recursively add to start to get new elements
- count : an integer, the number of items in the returned sequence. The default is 2.
- operation : an integer, the type of operation used to build the series. Can be either '+' for a linear series or '*' for a geometric series. The default is '+'.
Returns:
An object, either 0 on failure or a sequence containing the series.
Comments:
- The first item in the returned series is always start.
- A linear series is formed by adding increment to start.
- A geometric series is formed by multiplying increment by start.
- If count is negative, or if start op increment is invalid, then 0 is returned. Otherwise, a sequence, of length count+1, staring with start and whose adjacent elements differ by increment, is returned.
Example 1:
s = series( 1, 4, 5)
-- s is {1, 5, 9, 13, 17}
s = series( 1, 2, 6, '*')
-- s is {1, 2, 4, 8, 16, 32}
s = series({1,2,3}, 4, 2)
-- s is {{1,2,3}, {5,6,7}}
s = series({1,2,3}, {4,-1,10}, 2)
-- s is {{1,2,3}, {5,1,13}}
See Also:
8.16.3.2 repeat_pattern
include std/sequence.e namespace stdseq public function repeat_pattern(object pattern, integer count)
Returns a periodic sequence, given a pattern and a count.
Parameters:
- pattern : the sequence whose elements are to be repeated
- count : an integer, the number of times the pattern is to be repeated.
Returns:
A sequence, empty on failure, and of length count*length(pattern) otherwise. The first elements of the returned sequence are those of pattern. So are those that follow, on to the end.
Example 1:
s = repeat_pattern({1,2,5},3)
-- s is {1,2,5,1,2,5,1,2,5}
See Also:
8.16.3.3 repeat
<built-in> function repeat(object item, atom count)
Create a sequence whose all elements are identical, with given length.
Parameters:
- item : an object, to which all elements of the result will be equal
- count : an atom, the requested length of the result sequence. This must be a value from zero to 0x3FFFFFFF. Any floating point values are first floored.
Returns:
A sequence, of length count each element of which is item.
Errors:
count cannot be less than zero and cannot be greater than 1,073,741,823.
Comments:
When you repeat() a sequence or a floating-point number the interpreter does not actually make multiple copies in memory. Rather, a single copy is "pointed to" a number of times.
Example 1:
repeat(0, 10) -- {0,0,0,0,0,0,0,0,0,0}
repeat("JOHN", 4) -- {"JOHN", "JOHN", "JOHN", "JOHN"}
-- The interpreter will create only one copy of "JOHN"
-- in memory and create a sequence containing four references to it.
See Also:
8.16.4 Adding to sequences
8.16.4.1 append
<built-in> function append(sequence target, object x)
Adds an object as the last element of a sequence.
Parameters:
- source : the sequence to add to
- x : the object to add
Returns:
A sequence, whose first elements are those of target and whose last element is x.
Comments:
The length of the resulting sequence will be length(target) + 1, no matter what x is.
If x is an atom this is equivalent to result = target & x. If x is a sequence it is not equivalent.
The extra storage is allocated automatically and very efficiently with Euphoria's dynamic storage allocation. The case where target itself is append()ed to (as in Example 1 below) is highly optimized.
Example 1:
sequence x
x = {}
for i = 1 to 10 do
x = append(x, i)
end for
-- x is now {1,2,3,4,5,6,7,8,9,10}
Example 2:
sequence x, y, z
x = {"fred", "barney"}
y = append(x, "wilma")
-- y is now {"fred", "barney", "wilma"}
z = append(append(y, "betty"), {"bam", "bam"})
-- z is now {"fred", "barney", "wilma", "betty", {"bam", "bam"}}
See Also:
8.16.4.2 prepend
<built-in> function prepend(sequence target, object x)
Adds an object as the first element of a sequence.
Parameters:
- source : the sequence to add to
- x : the object to add
Returns:
A sequence, whose last elements are those of target and whose first element is x.
Comments:
The length of the returned sequence will be length(target) + 1 always.
If x is an atom this is the same as result = x & target. If x is a sequence it is not the same.
The case where target itself is prepend()ed to is handled very efficiently.
Example 1:
prepend({1,2,3}, {0,0}) -- {{0,0}, 1, 2, 3}
-- Compare with concatenation:
{0,0} & {1,2,3} -- {0, 0, 1, 2, 3}
Example 2:
s = {}
for i = 1 to 10 do
s = prepend(s, i)
end for
-- s is {10,9,8,7,6,5,4,3,2,1}
See Also:
8.16.4.3 insert
<built-in> function insert(sequence target, object what, integer index)
Insert an object into a sequence as a new element at a given location.
Parameters:
- target : the sequence to insert into
- what : the object to insert
- index : an integer, the position in target where what should appear
Returns:
A sequence, which is target with one more element at index, which is what.
Comments:
target can be a sequence of any shape, and what any kind of object.
The length of the returned sequence is always length(target) + 1.
insert()ing a sequence into a string returns a sequence which is no longer a string.
Example 1:
s = insert("John Doe", " Middle", 5)
-- s is {'J','o','h','n'," Middle",' ','D','o','e'}
Example 2:
s = insert({10,30,40}, 20, 2)
-- s is {10,20,30,40}
See Also:
remove, splice, append, prepend
8.16.4.4 splice
<built-in> function splice(sequence target, object what, integer index)
Inserts an object as a new slice in a sequence at a given position.
Parameters:
- target : the sequence to insert into
- what : the object to insert
- index : an integer, the position in target where what should appear
Returns:
A sequence, which is target with one or more elements, those of what, inserted at locations starting at index.
Comments:
target can be a sequence of any shape, and what any kind of object.
The length of this new sequence is the sum of the lengths of target and what. splice() is equivalent to insert() when what is an atom, but not when it is a sequence.
Splicing a string into a string results into a new string.
Example 1:
s = splice("John Doe", " Middle", 5)
-- s is "John Middle Doe"
Example 2:
s = splice({10,30,40}, 20, 2)
-- s is {10,20,30,40}
See Also:
8.16.4.5 pad_head
include std/sequence.e namespace stdseq public function pad_head(object target, integer size, object ch = ' ')
Pad the beginning of a sequence with an object so as to meet a minimum length condition.
Parameters:
- target : the sequence to pad.
- size : an integer, the target minimum size for target
- padding : an object, usually the character to pad to (defaults to ' ').
Returns:
A sequence, either target if it was long enough, or a sequence of length size whose last elements are those of target and whose first few head elements all equal padding.
Comments:
pad_head() will not remove characters. If length(target) is greater than size, this function simply returns target. See head() if you wish to truncate long sequences.
Example 1:
s = pad_head("ABC", 6)
-- s is " ABC"
s = pad_head("ABC", 6, '-')
-- s is "---ABC"
See Also:
8.16.4.6 pad_tail
include std/sequence.e namespace stdseq public function pad_tail(object target, integer size, object ch = ' ')
Pad the end of a sequence with an object so as to meet a minimum length condition.
Parameters:
- target : the sequence to pad.
- size : an integer, the target minimum size for target
- padding : an object, usually the character to pad to (defaults to ' ').
Returns:
A sequence, either target if it was long enough, or a sequence of length size whose first elements are those of target and whose last few head elements all equal padding.
Comments:
pad_tail() will not remove characters. If length(target) is greater than size, this function simply returns target. See tail() if you wish to truncate long sequences.
Comments:
pad_tail() will not remove characters. If length(str) is greater than params, this function simply returns str. see tail() if you wish to truncate long sequences.
Example 1:
s = pad_tail("ABC", 6)
-- s is "ABC "
s = pad_tail("ABC", 6, '-')
-- s is "ABC---"
See Also:
8.16.4.7 add_item
include std/sequence.e namespace stdseq public function add_item(object needle, sequence haystack, integer pOrder = 1)
Adds an item to the sequence if its not already there. If it already exists in the list, the list is returned unchanged.
Parameters:
- needle : object to add.
- haystack : sequence to add it to.
- order : an integer; determines how the needle affects the haystack. It can be added to the front (prepended), to the back (appended), or sorted after adding. The default is to prepend it.
Returns:
A sequence, which is haystack with needle added to it.
Comments:
An error occurs if an invalid order argument is supplied.
The following enum is provided for specifying order:
- ADD_PREPEND -- prepend needle to haystack. This is the default option.
- ADD_APPEND -- append needle to haystack.
- ADD_SORT_UP -- sort haystack in ascending order after inserting needle
- ADD_SORT_DOWN -- sort haystack in descending order after inserting needle
Example 1:
s = add_item( 1, {3,4,2}, ADD_PREPEND ) -- prepend
-- s is {1,3,4,2}
Example 2:
s = add_item( 1, {3,4,2}, ADD_APPEND ) -- append
-- s is {3,4,2,1}
Example 3:
s = add_item( 1, {3,4,2}, ADD_SORT_UP ) -- ascending
-- s is {1,2,3,4}
Example 4:
s = add_item( 1, {3,4,2}, ADD_SORT_DOWN ) -- descending
-- s is {4,3,2,1}
Example 5:
s = add_item( 1, {3,1,4,2} )
-- s is {3,1,4,2} -- Item was already in list so no change.
8.16.4.8 remove_item
include std/sequence.e namespace stdseq public function remove_item(object needle, sequence haystack)
Removes an item from the sequence.
Parameters:
- needle : object to remove.
- haystack : sequence to remove it from.
Returns:
A sequence, which is haystack with needle removed from it.
Comments:
If needle is not in haystack then haystack is returned unchanged.
Example 1:
s = remove_item( 1, {3,4,2,1} ) --> {3,4,2}
s = remove_item( 5, {3,4,2,1} ) --> {3,4,2,1}
8.16.5 Extracting, removing, replacing from/into a sequence
8.16.5.1 head
<built-in> function head(sequence source, atom size=1)
Return the first size item(s) of a sequence.
Parameters:
- source : the sequence from which elements will be returned
- size : an integer; how many elements, at most, will be returned. Defaults to 1.
Returns:
A sequence, source if its length is not greater than size, or the size first elements of source otherwise.
Example 1:
s2 = head("John Doe", 4)
-- s2 is John
Example 2:
s2 = head("John Doe", 50)
-- s2 is John Doe
Example 3:
s2 = head({1, 5.4, "John", 30}, 3)
-- s2 is {1, 5.4, "John"}
See Also:
8.16.5.2 tail
<built-in> function tail(sequence source, atom size=length(source) - 1)
Return the last size item(s) of a sequence.
Parameters:
- source : the sequence to get the tail of.
- size : an integer, the number of items to return. (defaults to length(source) - 1)
Returns:
A sequence, of length at most size. If the length is less than size, then source was returned. Otherwise, the size last elements of source were returned.
Comments:
source can be any type of sequence, including nested sequences.
Example 1:
s2 = tail("John Doe", 3)
-- s2 is "Doe"
Example 2:
s2 = tail("John Doe", 50)
-- s2 is "John Doe"
Example 3:
s2 = tail({1, 5.4, "John", 30}, 3)
-- s2 is {5.4, "John", 30}
See Also:
8.16.5.3 mid
include std/sequence.e namespace stdseq public function mid(sequence source, atom start, atom len)
Returns a slice of a sequence, given by a starting point and a length.
Parameters:
- source : the sequence some elements of which will be returned
- start : an integer, the lower index of the slice to return
- len : an integer, the length of the slice to return
Returns:
A sequence, made of at most len elements of source. These elements are at contiguous positions in source starting at start.
Errors:
If len is less than -length(source), an error occurs.
Comments:
len may be negative, in which case it is added length(source) once.
Example 1:
s2 = mid("John Middle Doe", 6, 6)
-- s2 is Middle
Example 2:
s2 = mid("John Middle Doe", 6, 50)
-- s2 is Middle Doe
Example 3:
s2 = mid({1, 5.4, "John", 30}, 2, 2)
-- s2 is {5.4, "John"}
Example 4:
s2 = mid({1, 5.4, "John", 30}, 2, -1)
-- s2 is {5.4, "John", 30}
See Also:
8.16.5.4 slice
include std/sequence.e namespace stdseq public function slice(sequence source, atom start = 1, atom stop = 0)
Return a portion of the supplied sequence.
Parameters:
- source : the sequence from which to get a portion
- start : an integer, the starting point of the portion. Default is 1.
- stop : an integer, the ending point of the portion. Default is length(source).
Returns:
A sequence.
Comments:
- If the supplied start is less than 1 then it set to 1.
- If the supplied stop is less than 1 then length(source) is added to it. In this way, 0 represents the end of source, -1 represents one element in from the end of source and so on.
- If the supplied stop is greater than length(source) then it is set to the end.
- After these adjustments, and if source[start..stop] makes sense, it is returned, otherwise, {} is returned.
Examples:
s2 = slice("John Doe", 6, 8)--> "Doe"
s2 = slice("John Doe", 6, 50) --> "Doe"
s2 = slice({1, 5.4, "John", 30}, 2, 3) --> {5.4, "John"}
s2 = slice({1,2,3,4,5}, 2, -1) --> {2,3,4}
s2 = slice({1,2,3,4,5}, 2) --> {2,3,4,5}
s2 = slice({1,2,3,4,5}, , 4) --> {1,2,3,4}
See Also:
8.16.5.5 vslice
include std/sequence.e namespace stdseq public function vslice(sequence source, atom colno, object error_control = 0)
Perform a vertical slice on a nested sequence
Parameters:
- source : the sequence to take a vertical slice from
- colno : an atom, the column number to extract (rounded down)
- error_control : an object which says what to do if some element does not exist. Defaults to 0 (crash in such a circumstance).
Returns:
A sequence, usually of the same length as source, made of all the source[x][colno].
Errors:
If an element is not defined and error_control is 0, an error occurs. If colno is less than 1, it cannot be any valid column, and an error occurs.
Comments:
If it is not possible to return the sequence of all source[x][colno]] for all available x, the outcome is decided by error_control:
- If 0 (the default), program is aborted.
- If a nonzero atom, the short vertical slice is returned.
- Otherwise, elements of error_control will be taken to make for any missing element. The elements are selected from the first to the last, as needed and this cycles again from the first.
Example 1:
s = vslice({{5,1}, {5,2}, {5,3}}, 2)
-- s is {1,2,3}
s = vslice({{5,1}, {5,2}, {5,3}}, 1)
-- s is {5,5,5}
See Also:
8.16.5.6 remove
<built-in> function remove(sequence target, atom start, atom stop=start)
Remove an item, or a range of items from a sequence.
Parameters:
- target : the sequence to remove from.
- start : an atom, the (starting) index at which to remove
- stop : an atom, the index at which to stop removing (defaults to start)
Returns:
A sequence, obtained from target by carving the start..stop slice out of it.
Comments:
A new sequence is created. target can be a string or complex sequence.
Example 1:
s = remove("Johnn Doe", 4)
-- s is "John Doe"
Example 2:
s = remove({1,2,3,3,4}, 4)
-- s is {1,2,3,4}
Example 3:
s = remove("John Middle Doe", 6, 12)
-- s is "John Doe"
Example 4:
s = remove({1,2,3,3,4,4}, 4, 5)
-- s is {1,2,3,4}
See Also:
replace, insert, splice, remove_all
8.16.5.7 patch
include std/sequence.e namespace stdseq public function patch(sequence target, sequence source, integer start, object filler = ' ')
Changes a sequence slice, possibly with padding
Parameters:
- target : a sequence, a modified copy of which will be returned
- source : a sequence, to be patched inside or outside target
- start : an integer, the position at which to patch
- filler : an object, used for filling gaps. Defaults to ' '
Returns:
A sequence, which looks like target, but a slice starting at start equals source.
Comments:
In some cases, this call will result in the same result as replace().
If source doesn't fit into target because of the lengths and the supplied start value, gaps will be created, and filler is used to fill them in.
Notionally, target has an infinite amount of filler on both sides, and start counts position relative to where target actually starts. Then, notionally, a replace() operation is performed.
Example 1:
sequence source = "abc", target = "John Doe" sequence s = patch(target, source, 11,'0') -- s is now "John Doe00abc"
Example 2:
sequence source = "abc", target = "John Doe" sequence s = patch(target, source, -1) -- s is now "abcohn Doe" Note that there was no gap to fill. Since -1 = 1 - 2, the patching started 2 positions before the initial 'J'.
Example 3:
sequence source = "abc", target = "John Doe" sequence s = patch(target, source, 6) -- s is now "John Dabc"
See Also:
8.16.5.8 remove_all
include std/sequence.e namespace stdseq public function remove_all(object needle, sequence haystack)
Removes all occurrences of some object from a sequence.
Parameters:
- needle : the object to remove.
- haystack : the sequence to remove from.
Returns:
A sequence, of length at most length(haystack), and which has the same elements, without any copy of needle left
Comments:
This function weeds elements out, not sub-sequences.
Example 1:
s = remove_all( 1, {1,2,4,1,3,2,4,1,2,3} )
-- s is {2,4,3,2,4,2,3}
Example 2:
s = remove_all('x', "I'm toox secxksy for my shixrt.")
-- s is "I'm too secksy for my shirt."
See Also:
8.16.5.9 retain_all
include std/sequence.e namespace stdseq public function retain_all(object needles, sequence haystack)
Keeps all occurrences of a set of objects from a sequence and removes all others.
Parameters:
- needles : the set of objects to retain.
- haystack : the sequence to remove items not in needles.
Returns:
A sequence containing only those objects from haystack that are also in needles.
Example:
s = retain_all( {1,3,5}, {1,2,4,1,3,2,4,1,2,3} ) --> {1,1,3,1,3}
s = retain_all("0123456789", "+34 (04) 555-44392") -> "340455544392"
See Also:
8.16.5.10 filter
include std/sequence.e
namespace stdseq
public function filter(sequence source, object rid, object userdata = {},
object rangetype = "")
Filter a sequence based on a user supplied comparator function.
Parameters:
- source : sequence to filter
- rid : Either a routine_id of function to use as comparator or one of the predefined comparitors.
- userdata : an object passed to each invocation of rid. If omitted, {} is used.
- rangetype: A sequence. Only used when rid is "in" or "out". This is used to let the function know how to interpret userdata. When rangetype is an empty string (which is the default), then userdata is treated as a set of zero or more discrete items such that "in" will only return items from source that are in the set of item in userdata and "out" returns those not in userdata. The other values for rangetype mean that userdata must be a set of exactly two items, that represent the lower and upper limits of a range of values.
Returns:
A sequence, made of the elements in source which passed the comparitor test.
Comments:
- The only items from source that are returned are those that pass the test.
- When rid is a routine_id, that user defined routine must be a function. Each item in source, along with the userdata is passed to the function. The function must return a non-zero atom if the item is to be included in the result sequence, otherwise it should return zero to exclude it from the result.
- The predefined comparitors are...
| "<" or "lt" | return items in source that are less than userdata |
| "<=" or "le" | return items in source that are less than or equal to userdata |
| "=" or "==" or "eq" | return items in source that are equal to userdata |
| "!=" or "ne" | return items in source that are not equal to userdata |
| ">" or "gt" | return items in source that are greater than userdata |
| ">=" or "ge" | return items in source that are greater than or equal to userdata |
| "in" | return items in source that are in userdata |
| "out" | return items in source that are not in userdata |
- Range Type Usage
| Range Type | Meaning |
|---|---|
| "[]" | Inclusive range. Lower and upper are in the range. |
| "[)" | Low Inclusive range. Lower is in the range but upper is not. |
| "(]" | High Inclusive range. Lower is not in the range but upper is. |
| "()" | Exclusive range. Lower and upper are not in the range. |
Example 1:
function mask_nums(atom a, object t)
if sequence(t) then
return 0
end if
return and_bits(a, t) != 0
end function
function even_nums(atom a, atom t)
return and_bits(a,1) = 0
end function
constant data = {5,8,20,19,3,2,10}
filter(data, routine_id("mask_nums"), 1) --> {5,19,3}
filter(data, routine_id("mask_nums"), 2) -->{19, 3, 2, 10}
filter(data, routine_id("even_nums")) -->{8, 20, 2, 10}
-- Using 'in' and 'out' with sets.
filter(data, "in", {3,4,5,6,7,8}) -->{5,8,3}
filter(data, "out", {3,4,5,6,7,8}) -->{20,19,2,10}
-- Using 'in' and 'out' with ranges.
filter(data, "in", {3,8}, "[]") --> {5,8,3}
filter(data, "in", {3,8}, "[)") --> {5,3}
filter(data, "in", {3,8}, "(]") --> {5,8}
filter(data, "in", {3,8}, "()") --> {5}
filter(data, "out", {3,8}, "[]") --> {20,19,2,10}
filter(data, "out", {3,8}, "[)") --> {8,20,19,2,10}
filter(data, "out", {3,8}, "(]") --> {20,19,3,2,10}
filter(data, "out", {3,8}, "()") --> {8,20,19,3,2,10}
Example 3:
function quiksort(sequence s)
if length(s) < 2 then
return s
end if
return quiksort( filter(s[2..$], "<=", s[1]) ) & s[1] & quiksort(filter(s[2..$], ">", s[1]))
end function
? quiksort( {5,4,7,2,4,9,1,0,4,32,7,54,2,5,8,445,67} )
--> {0,1,2,2,4,4,4,5,5,7,7,8,9,32,54,67,445}
See Also:
8.16.5.11 STDFLTR_ALPHA
public constant STDFLTR_ALPHA
Predefined routine_id for use with filter().
Comments:
Used to filter out non-alphabetic characters from a string.
Example:
-- Collect only the alphabetic characters from 'text' result = filter(text, STDFLTR_ALPHA)
8.16.5.12 replace
<built-in> function replace(sequence target, object replacement, integer start, integer stop=start)
Replace a slice in a sequence by an object.
Parameters:
- target : the sequence in which replacement will be done.
- replacement : an object, the item to replace with.
- start : an integer, the starting index of the slice to replace.
- stop : an integer, the stopping index of the slice to replace.
Returns:
A sequence, which is made of target with the start..stop slice removed and replaced by replacement, which is splice()d in.
Comments:
- A new sequence is created. target can be a string or complex sequence of any shape.
- To replace by just one element, enclose replacement in curly braces, which will be removed at replace time.
Example 1:
s = replace("John Middle Doe", "Smith", 6, 11)
-- s is "John Smith Doe"
s = replace({45.3, "John", 5, {10, 20}}, 25, 2, 3)
-- s is {45.3, 25, {10, 20}}
See Also:
8.16.5.13 extract
include std/sequence.e namespace stdseq public function extract(sequence source, sequence indexes)
Picks out from a sequence a set of elements according to the supplied set of indexes.
Parameters:
- source : the sequence from which to extract elements
- indexes : a sequence of atoms, the indexes of the elements to be fetched in source.
Returns:
A sequence, of the same length as indexes.
Example 1:
s = extract({11,13,15,17},{3,1,2,1,4})
-- s is {15,11,13,11,17}
See Also:
8.16.5.14 project
include std/sequence.e namespace stdseq public function project(sequence source, sequence coords)
Creates a list of sequences based on selected elements from sequences in the source.
Parameters:
- source : a list of sequences.
- coords : a list of index lists.
Returns:
A sequence, with the same length as source. Each of its elements is a sequence, the length of coords. Each innermost sequence is made of the elements from the corresponding source sub-sequence.
Comments:
For each sequence in source, a set of sub-sequences is created; one for each index list in coords. An index list is just a sequence containing indexes for items in a sequence.
Example 1:
s = project({ "ABCD", "789"}, {{1,2}, {3,1}, {2}})
-- s is {{"AB","CA","B"},{"78","97","8"}}
See Also:
8.16.6 Changing the shape of a sequence
8.16.6.1 split
include std/sequence.e
namespace stdseq
public function split(sequence st, object delim = ' ', integer no_empty = 0,
integer limit = 0)
Split a sequence on separator delimiters into a number of sub-sequences.
Parameters:
- source : the sequence to split.
- delim : an object (default is ' '). The delimiter that separates items in source.
- no_empty : an integer (default is 0). If not zero then all zero-length sub-sequences are removed from the returned sequence. Use this when leading, trailing and duplicated delimiters are not significant.
- limit : an integer (default is 0). The maximum number of sub-sequences to create. If zero, there is no limit.
Returns:
A sequence, of sub-sequences of source. Delimiters are removed.
Comments:
This function may be applied to a string sequence or a complex sequence.
If limit is > 0, this is the maximum number of sub-sequences that will created, otherwise there is no limit.
Example 1:
result = split("John Middle Doe")
-- result is {"John", "Middle", "Doe"}
Example 2:
result = split("John,Middle,Doe", ",",, 2) -- Only want 2 sub-sequences.
-- result is {"John", "Middle,Doe"}
Example 3:
result = split("John||Middle||Doe|", '|') -- Each '|' is significant by default
-- result is {"John","","Middle","","Doe",""}
result = split("John||Middle||Doe|", '|', 1) -- Adjacent '|' are just a single delim,
-- and leading/trailing '|' ignored.
-- result is {"John","Middle","Doe"}
See Also:
8.16.6.2 split_any
include std/sequence.e
namespace stdseq
public function split_any(sequence source, object delim = ", \t|", integer limit = 0,
integer no_empty = 0)
Split a sequence by any of the separators in the list of delimiters.
If limit is > 0 then limit the number of tokens that will be split to limit.
Parameters:
- source : the sequence to split.
- delim : a list of delimiters to split by. The default set is comma, space, tab and bar.
- limit : an integer (default is 0). The maximum number of sub-sequences to create. If zero, there is no limit.
- no_empty : an integer (default is 0). If not zero then all zero-length sub-sequences removed from the returned sequence. Use this when leading, trailing and duplicated delimiters are not significant.
Comments:
- This function may be applied to a string sequence or a complex sequence.
- It works like split(), but in this case delim is a set of potential delimiters rather than a single delimiter.
- If delim is an empty set, the source is returned in a sequence.
Example 1:
result = split_any("One,Two|Three Four") -- Default delims
-- result is {"One", "Two", "Three", "Four"}
result = split_any("192.168.1.103:8080", ".:") -- Using dot and colon
-- result is {"192","168","1","103","8080"}
result = split_any("One,Two|Three Four",, 2) -- limited to two splits
-- result is {"One", "Two", "Three Four"}
result = split_any(",One,,Two| Three|| Four," ) -- Allow Empty option
-- result is {"","One","","Two","","Three","","","Four",""}
result = split_any(",One,,Two| Three|| Four,",,,1) -- No Empty option
-- result is {"One", "Two", "Three", "Four"}
result = split_any(",One,,Two| Three|| Four,", "") -- Empty delimiters
-- result is {",One,,Two| Three|| Four,"}
See Also:
8.16.6.3 join
include std/sequence.e namespace stdseq public function join(sequence items, object delim = " ")
Join sequences together using a delimiter.
Parameters:
- items : the sequence of items to join.
- delim : an object, the delimiter to join by. Defaults to " ".
Comments:
This function may be applied to a string sequence or a complex sequence
Example 1:
result = join({"John", "Middle", "Doe"})
-- result is "John Middle Doe"
Example 2:
result = join({"John", "Middle", "Doe"}, ",")
-- result is "John,Middle,Doe"
See Also:
8.16.6.4 BK_LEN
include std/sequence.e namespace stdseq public enum BK_LEN
Indicates that size parameter is maximum length of sub-sequence. See breakup
8.16.6.5 BK_PIECES
include std/sequence.e namespace stdseq public enum BK_PIECES
Indicates that size parameter is maximum number of sub-sequence. See breakup
8.16.6.6 breakup
include std/sequence.e namespace stdseq public function breakup(sequence source, object size, integer style = BK_LEN)
Breaks up a sequence into multiple sequences of a given length.
Parameters:
- source : the sequence to be broken up into sub-sequences.
- size : an object, if an integer it is either the maximum length of each resulting sub-sequence or the maximum number of sub-sequences to break source into.
If size is a sequence, it is a list of element counts for the sub-sequences it creates. - style : an integer, Either BK_LEN if size integer represents the sub-sequences' maximum length, or BK_PIECES if the size integer represents the maximum number of sub-sequences (pieces) to break source into.
Returns:
A sequence, of sequences.
Comments:
When size is an integer and style is BK_LEN...
The sub-sequences have length size, except possibly the last one, which may be shorter. For example if source has 11 items and size is 3, then the first three sub-sequences will get 3 items each and the remaining 2 items will go into the last sub-sequence. If size is less than 1 or greater than the length of the source, the source is returned as the only sub-sequence.
When size is an integer and style is BK_PIECES...
There is exactly size sub-sequences created. If the source is not evenly divisible into that many pieces, then the lefthand sub-sequences will contain one more element than the right-hand sub-sequences. For example, if source contains 10 items and we break it into 3 pieces, piece #1 gets 4 elements, piece #2 gets 3 items and piece #3 gets 3 items - a total of 10. If source had 11 elements then the pieces will have 4,4, and 3 respectively.
When size is a sequence...
The style parameter is ignored in this case. The source will be broken up according to the counts contained in the size parameter. For example, if size was {3,4,0,1} then piece #1 gets 3 items, #2 gets 4 items, #3 gets 0 items, and #4 gets 1 item. Note that if not all items from source are placed into the sub-sequences defined by size, and extra sub-sequence is appended that contains the remaining items from source.
In all cases, when concatenated these sub-sequences will be identical to the original source.
Example 1:
s = breakup("5545112133234454", 4)
-- s is {"5545", "1121", "3323", "4454"}
Example 2:
s = breakup("12345", 2)
-- s is {"12", "34", "5"}
Example 3:
s = breakup({1,2,3,4,5,6}, 3)
-- s is {{1,2,3}, {4,5,6}}
Example 4:
s = breakup("ABCDEF", 0)
-- s is {"ABCDEF"}
See Also:
8.16.6.7 flatten
include std/sequence.e namespace stdseq public function flatten(sequence s, object delim = "")
Remove all nesting from a sequence.
Parameters:
- s : the sequence to flatten out.
- delim : An optional delimiter to place after each flattened sub-sequence (except the last one).
Returns:
A sequence, of atoms, all the atoms in s enumerated.
Comments:
- If you consider a sequence as a tree, then the enumeration is performed by left-right reading of the tree. The elements are simply read left to right, without any care for braces.
- Empty sub-sequences are stripped out entirely.
Example 1:
s = flatten({{18, 19}, 45, {18.4, 29.3}})
-- s is {18, 19, 45, 18.4, 29.3}
Example 2:
s = flatten({18,{ 19, {45}}, {18.4, {}, 29.3}})
-- s is {18, 19, 45, 18.4, 29.3}
Example 3:
Using the delimiter argument.
s = flatten({"abc", "def", "ghi"}, ", ")
-- s is "abc, def, ghi"
8.16.6.8 pivot
include std/sequence.e namespace stdseq public function pivot(object data_p, object pivot_p = 0)
Returns a sequence of three sub-sequences. The sub-sequences contain all the elements less than the supplied pivot value, equal to the pivot, and greater than the pivot.
Parameters:
- data_p : Either an atom or a list. An atom is treated as if it is one-element sequence.
- pivot_p : An object. Default is zero.
Returns:
A sequence, { {less than pivot}, {equal to pivot}, {greater than pivot} }
Comments:
pivot() is used as a split up a sequence relative to a specific value.
Example 1:
pivot( {7, 2, 8.5, 6, 6, -4.8, 6, 6, 3.341, -8, "text"}, 6 )
-- Ans: {{2, -4.8, 3.341, -8}, {6, 6, 6, 6}, {7, 8.5, "text"}}
pivot( {4, 1, -4, 6, -1, -7, 9, 10} )
-- Ans: {{-4, -1, -7}, {}, {4, 1, 6, 9, 10}}
pivot( 5 )
-- Ans: {{}, {}, {5}}
Example 2:
function quiksort(sequence s)
if length(s) < 2 then
return s
end if
sequence k = pivot(s, s[rand(length(s))])
return quiksort(k[1]) & k[2] & quiksort(k[3])
end function
sequence t2 = {5,4,7,2,4,9,1,0,4,32,7,54,2,5,8,445,67}
? quiksort(t2) --> {0,1,2,2,4,4,4,5,5,7,7,8,9,32,54,67,445}
8.16.6.9 build_list
include std/sequence.e
namespace stdseq
public function build_list(sequence source, object transformer, integer singleton = 1,
object user_data = {})
Implements "List Comprehension" or building a list based on the contents of another list.
Parameters:
- source : A sequence. The list of items to base the new list upon.
- transformer : One or more routine_ids. These are routine ids of functions that must receive three parameters (object x, sequence i, object u) where 'x' is an item in the source list, 'i' contains the position that 'x' is found in the source list and the length of source, and 'u' is the user_data value. Each transformer must return a two-element sequence. If the first element is zero, then build_list() continues on with the next transformer function for the same 'x'. If the first element is not zero, the second element is added to the new list being built (other elements are ignored) and build_list skips the rest of the transformers and processes the next element in source.
- singleton : An integer. If zero then the transformer functions return multiple list elements. If not zero then the transformer functions return a single item (which might be a sequence).
- user_data : Any object. This is passed unchanged to each transformer function.
Returns:
A sequence, The new list of items.
Comments:
- If the transformer is -1, then the source item is just copied.
Example 1:
function remitem(object x, sequence i, object q)
if (x < q) then
return {0} -- no output
else
return {1,x} -- copy 'x'
end if
end function
sequence s
-- Remove negative elements (x < 0)
s = build_list({-3, 0, 1.1, -2, 2, 3, -1.5}, routine_id("remitem"), , 0)
-- s is {0, 1.1, 2, 3}
8.16.6.10 transform
include std/sequence.e namespace stdseq public function transform(sequence source_data, object transformer_rids)
Transforms the input sequence by using one or more user-supplied transformers.
Parameters:
- source_data : A sequence to be transformed.
- transformer_rids : An object. One or more routine_ids used to transform the input.
Returns:
The source sequence, that has been transformed.
Comments:
- This works by calling each transformer in order, passing to it the result of the previous transformation. Of course, the first transformer gets the original sequence as passed to this routine.
- Each transformer routine takes one or more parameters. The first is a source sequence to be transformed and others are any user data that may have been supplied to the transform routine.
- Each transformer routine returns a transformed sequence.
- The transformer_rids parameters is either a single routine_id or a sequence of routine_ids. In this second case, the routine_id may actually be a multi-element sequence containing the real routine_id and some user data to pass to the transformer routine. If there is no user data then the transformer is called with only one parameter.
Examples:
res = transform(" hello ", {
{ routine_id("trim"), " ", 0 },
routine_id("upper")
})
--> "HELLO"
8.16.6.11 transmute
include std/sequence.e
namespace stdseq
public function transmute(sequence source_data, sequence current_items, sequence new_items,
integer start = 1, integer limit = length(source_data))
Replaces all instances of any element from the current_items sequence that occur in the source_data sequence with the corresponding item from the new_items sequence.
Parameters:
- source_data : a sequence, the data that might contain elements from current_items
- current_items : a sequence, the set of items to look for in source_data. Matching data is replaced with the corresponding data from new_items.
- new_items : a sequence, the set of replacement data for any matches found.
- start : an integer, the starting point of the search. Defaults to 1.
- limit : an integer, the maximum number of replacements to be made. Defaults to length(source_data).
Returns:
A sequence, an updated version of source_data.
Comments:
By default, this routine operates on single elements from each of the arguments. That is to say, it scans source_data for elements that match any single element in current_items and when matched, replaces that with a single element from new_items.
For example, you can find all occurrances of 'h', 's', and 't' in a string and replace them with '1', '2', and '3' respectively.
transmute(SomeString, "hts", "123")
However, the routine can also be used to scan for sub-sequences and/or replace matches with sequences rather than single elements. This is done by making the first element in current_items and/or new_items an empty sequence.
For example, to find all occurrances of "sh","th", and "sch" you have the current_items as {{}, "sh", "th", "sch"}. Note that for the purposes of determine the corresponding replacement data, the leading empty sequence is not counted, so in this example "th" is the second item.
res = transmute("the school shoes", {{}, "sh", "th", "sch"}, "123")
-- res becomes "2e 3ool 1oes"
The similar syntax is used to indicates that replacements are sequences and not single elements.
res = transmute("the school shoes", {{}, "sh", "th", "sch"}, {{}, "SH", "TH", "SCH"})
-- res becomes "THe SCHool SHoes"
Using this option also allows you to remove matching data.
res = transmute("the school shoes", {{}, "sh", "th", "sch"}, {{}, "", "", ""})
-- res becomes "e ool oes"
Another thing to note is that when using this syntax, you can still mix together atoms and sequences.
res = transmute("the school shoes", {{}, "sh", 't', "sch"}, {{}, 'x', "TH", "SCH"})
-- res becomes "THhe SCHool xoes"
Example 1:
res = transmute("John Smith enjoys uncooked apples.", "aeiouy", "YUOIEA")
-- res is "JIhn SmOth UnjIAs EncIIkUd YpplUs."
See Also:
8.16.6.12 sim_index
include std/sequence.e namespace stdseq public function sim_index(sequence A, sequence B)
Calculates the similarity between two sequences.
Parameters:
- A : A sequence.
- B : A sequence.
Returns:
An atom, the closer to zero, the more the two sequences are alike.
Comments:
The calculation is weighted to give mismatched elements towards the front of the sequences larger scores. This means that sequences that differ near the begining are considered more un-alike than mismatches towards the end of the sequences. Also, unmatched elements from the first sequence are weighted more than unmatched elements from the second sequence.
Two identical sequences return zero. A non-zero means that they are not the same and larger values indicate a larger differences.
Example 1:
? sim_index("sit", "sin") --> 0.08784
? sim_index("sit", "sat") --> 0.32394
? sim_index("sit", "skit") --> 0.34324
? sim_index("sit", "its") --> 0.68293
? sim_index("sit", "kit") --> 0.86603
? sim_index("knitting", "knitting") --> 0.00000
? sim_index("kitting", "kitten") --> 0.09068
? sim_index("knitting", "knotting") --> 0.27717
? sim_index("knitting", "kitten") --> 0.35332
? sim_index("abacus","zoological") --> 0.76304
8.16.6.13 SEQ_NOALT
include std/sequence.e namespace stdseq public constant SEQ_NOALT
Indicates that remove_subseq() must not replace removed sub-sequences with an alternative value.
8.16.6.14 remove_subseq
include std/sequence.e namespace stdseq public function remove_subseq(sequence source_list, object alt_value = SEQ_NOALT)
Removes all sub-sequences from the supplied sequence, optionally replacing them with a supplied alternative value. One common use is to remove all strings from a mixed set of numbers and strings.
Parameters:
- source_list : A sequence from which sub-sequences are removed.
- alt_value : An object. The default is SEQ_NOALT, which causes sub-sequences to be physically removed, otherwise any other value will be used to replace the sub-sequence.
Returns:
A sequence, which contains only the atoms from source_list and optionally the alt_value where sub-sequences used to be.
Example:
sequence s = remove_subseq({4,6,"Apple",0.1, {1,2,3}, 4})
-- 's' is now {4, 6, 0.1, 4} -- length now 4
s = remove_subseq({4,6,"Apple",0.1, {1,2,3}, 4}, -1)
-- 's' is now {4, 6, -1, 0.1, -1, 4} -- length unchanged.
8.16.6.15 RD_INPLACE
include std/sequence.e namespace stdseq public enum RD_INPLACE
Removes items while preserving the original order of the unique items.
See Also:
8.16.6.16 RD_PRESORTED
include std/sequence.e namespace stdseq public enum RD_PRESORTED
Assumes that the elements in source_data are already sorted. If they are not already sorted, this option merely removed adjacent duplicate elements.
See Also:
8.16.6.17 RD_SORT
include std/sequence.e namespace stdseq public enum RD_SORT
Will return the unique elements in ascending sorted order.
See Also:
8.16.6.18 remove_dups
include std/sequence.e namespace stdseq public function remove_dups(sequence source_data, integer proc_option = RD_PRESORTED)
Removes duplicate elements
Parameters:
- source_data : A sequence that may contain duplicated elements
- proc_option : One of RD_INPLACE, RD_PRESORTED, or RD_SORT.
- RD_INPLACE removes items while preserving the original order of the unique items.
- RD_PRESORTED assumes that the elements in source_data are already sorted. If they are not already sorted, this option merely removed adjacent duplicate elements.
- RD_SORT will return the unique elements in ascending sorted order.
Returns:
A sequence, that contains only the unique elements from source_data.
Example 1:
sequence s = { 4,7,9,7,2,5,5,9,0,4,4,5,6,5}
? remove_dups(s, RD_INPLACE) --> {4,7,9,2,5,0,6}
? remove_dups(s, RD_SORT) --> {0,2,4,5,6,7,9}
? remove_dups(s, RD_PRESORTED) --> {4,7,9,7,2,5,9,0,4,5,6,5}
? remove_dups(sort(s), RD_PRESORTED) --> {0,2,4,5,6,7,9}
8.16.6.19 COMBINE_UNSORTED
include std/sequence.e namespace stdseq public enum COMBINE_UNSORTED
8.16.6.20 COMBINE_SORTED
include std/sequence.e namespace stdseq public enum COMBINE_SORTED
8.16.6.21 combine
include std/sequence.e namespace stdseq public function combine(sequence source_data, integer proc_option = COMBINE_SORTED)
Combines all the sub-sequences into a single, optionally sorted, list
Parameters:
- source_data : A sequence that contains sub-sequences to be combined.
- proc_option : An integer; COMBINE_UNSORTED to return a non-sorted list and COMBINE_SORTED (the default) to return a sorted list.
Returns:
A sequence, that contains all the elements from all the first-level of sub-sequences from source_data.
Comments:
The elements in the sub-sequences do not have to be pre-sorted.
Only one level of sub-sequence is combined.
Example 1:
sequence s = { {4,7,9}, {7,2,5,9}, {0,4}, {5}, {6,5}}
combine(s, COMBINE_SORTED) --> {0,2,4,4,5,5,5,6,7,7,9,9}
combine(s, COMBINE_UNSORTED) --> {4,7,9,7,2,5,9,0,4,5,6,5}
Example 2:
sequence s = { {"cat", "dog"}, {"fish", "whale"}, {"wolf"}, {"snail", "worm"}}
combine(s) --> {"cat","dog","fish","snail","whale","wolf","worm"}
combine(s, COMBINE_UNSORTED) --> {"cat","dog","fish","whale","wolf","snail","worm"}
Example 3:
sequence s = { "cat", "dog","fish", "whale", "wolf", "snail", "worm"}
combine(s) --> "aaacdeffghhiilllmnooorsstwww"
combine(s, COMBINE_UNSORTED) --> "catdogfishwhalewolfsnailworm"
8.16.6.22 minsize
include std/sequence.e
namespace stdseq
public function minsize(object source_data,
integer min_size = floor(length(source_data)* 1.5),
object new_data = 0)
Ensures that the supplied sequence is at least the supplied minimum length.
Pads source_data to the right until its length reaches min_size using new_data as filler.
Parameters:
- source_data : An object that might need extending.
- min_size: An integer. The minimum length that source_data must be. The default is to increase the length of
- new_data: An object. This used to when source_data needs to be extended, in which case it is appended as many times as required to make the length equal to min_size. The default is 0.
Returns:
A sequence. The padded sequence, unchanged if its size was not less than min_size on input.
Example:
sequence s
s = minsize({4,3,6,2,7,1,2}, 10, -1) --> {4,3,6,2,7,1,2,-1,-1,-1}
s = minsize({4,3,6,2,7,1,2}, 5, -1) --> {4,3,6,2,7,1,2}
