Module Sqib

Sqib, a sequence query facility for Lua

This project is available on Github.

Info:

  • Copyright: © 2020 psmay
  • Release: 0.3.1-aa-20200804a
  • License: MIT
  • Author: psmay

Functions

empty () Returns a new Sqib.Seq containing zero elements.
from (value) Produces a Sqib.Seq by guessing the appropriate conversion for value.
from_all (...) Produces a Sqib.Seq by converting each parameter to a Sqib.Seq and concatenating the results.
from_array (a[, n]) Returns a Sqib.Seq based on an array or its first elements.
from_array_slice (a, start, limit) Returns a Sqib.Seq based on the elements of a subsequence of an array between two specified indexes.
from_iterate (iterate[, ...]) Returns a Sqib.Seq based on the supplied iterate function.
from_keys (t) Returns a Sqib.Seq based on the keys of a table.
from_packed (t) Returns a Sqib.Seq based on a packed list.
from_pairs (t[, result_selector]) Returns a Sqib.Seq based on the key-value pairs of a table.
from_values (t) Returns a Sqib.Seq based on the values of a table.
from_yielder (yielder[, ...]) Returns a Sqib.Seq based on the supplied yielder function.
over (...) Returns a Sqib.Seq over the supplied sequence of parameters.
range (start_value, limit_value[, step=1]) Returns a new Sqib.Seq over the specified range.
times (value, count) Returns a new Sqib.Seq that repeats a specified value a specified number of times.

Class Sqib.Seq

Sqib.Seq:all (predicate) Returns whether all elements of this sequence satisfy a predicate.
Sqib.Seq:any ([predicate]) Returns whether this sequence contains any elements or contains any elements that satisfy a predicate.
Sqib.Seq:append (...) Produces a Sqib.Seq consisting of this sequence followed by the specified elements.
Sqib.Seq:batch (block_size[, result_selector]) Produces a Sqib.Seq consisting of this sequence’s elements as blocks of a specified number of elements each.
Sqib.Seq:call (f[, ...]) Calls the specified function as if it were a method on this sequence.
Sqib.Seq:concat (...) Returns a Sqib.Seq consisting of this sequence followed by the specified additional sequences.
Sqib.Seq:copy_into_array (a[, start_index=1]) Copies all elements of this sequence into an existing array or object.
Sqib.Seq:count ([predicate]) Counts the number of elements, or the number of elements that satisfy a predicate, in this sequence.
Sqib.Seq:filter (predicate) Filters this sequence to only the elements that satisfy a predicate.
Sqib.Seq:flat_map ([selector[, convert_result=true]]) Maps this sequence by applying a sequence-producing selector, then returns a sequence from the concatenated results.
Sqib.Seq:force () Forces immediate evaluation of this sequence.
Sqib.Seq:is_sqib_seq () Returns whether this object should be treated as Sqib.Seq.
Sqib.Seq:iterate () Returns a closure-based iterator over this sequence.
Sqib.Seq:map (selector) Maps each element of this sequence by applying a selector.
Sqib.Seq:new ([o={}]) The constructor for an abstract Sqib.Seq.
Sqib.Seq:pack () Copies this sequence into a new packed list.
Sqib.Seq:pairs_to_hash (pair_selector) Creates a new dictionary-style table using the provided selector to determine each key-value pair.
Sqib.Seq:reversed () Returns a new Sqib.Seq that consists of the elements of this sequence in reverse order.
Sqib.Seq:skip (count) Skips a specified number of elements, then produces the remainder.
Sqib.Seq:skip_while (predicate) Skips all elements while a predicate is satisfied, then produces the remainder.
Sqib.Seq:sorted (...) Returns a new Sqib.Seq that consists of the elements of this sequence sorted according to the specified options.
Sqib.Seq:take (count) Passes a specified number of elements, then ends the sequence.
Sqib.Seq:take_while (predicate) Passes all elements while a predicate is satisfied, then ends the sequence.
Sqib.Seq:times (count) Returns a new Sqib.Seq that repeats this entire sequence a specified number of times.
Sqib.Seq:to_array ([include_length=false]) Copies this sequence into a new array.
Sqib.Seq:to_hash ([key_selector[, value_selector]]) Creates a new dictionary-style table using the provided selectors to determine the keys and values.
Sqib.Seq:to_sqib_seq () Returns this Sqib.Seq object.
Sqib.Seq:unique ([key_selector]) Filters this sequence to distinct elements by including only the first element having a selected key.
Sqib.Seq:unpack () Returns this entire sequence as a return value list.


Functions

empty ()
Returns a new Sqib.Seq containing zero elements.

Returns:

    A new, empty Sqib.Seq.
from (value)

Produces a Sqib.Seq by guessing the appropriate conversion for value.

  • If value is a table,
    • If value.is_sqib_seq exists as a function and value:is_sqib_seq() returns true, value is used directly.
    • If value.to_sqib_seq exists as a function, the result of value:to_sqib_seq() is used.
      • If the value seq returned by value:to_sqib_seq() is not a table, or seq.is_sqib_seq is not a function, or seq:is_sqib_seq() does not return true, an error is raised.
    • Otherwise, if value.n exists as a nonnegative integer, the result of Sqib.from_packed(value) is used.
    • Otherwise, the result of Sqib.from_array(value) is used.
  • If value is a function, the result of Sqib.from_yielder(value) is used.
  • Otherwise, an error is raised.

Parameters:

  • value A source of sequence data to be used as a sequence.

Returns:

    A Sqib.Seq obtained by automatically converting value.

Raises:

  • When value has no automatic conversion to a sequence.
  • When value.to_sqib_seq is a function but value:to_sqib_seq() returns a value that does not appear to be a sequence (i.e., does not pass the is_sqib_seq() test).

See also:

from_all (...)
Produces a Sqib.Seq by converting each parameter to a Sqib.Seq and concatenating the results.

Parameters:

  • ... Sequence-like values to be converted to sequences (using the same rules as Sqib.from) and concatenated.

Returns:

    A Sqib.Seq obtained by automatically converting every parameter to a Sqib.Seq, then concatenating the results.

Raises:

  • When any parameter has no automatic conversion to a sequence.
  • When, for any parameter v, v.to_sqib_seq is a function but v:to_sqib_seq() returns a value that does not appear to be a sequence (i.e., does not pass the is_sqib_seq() test).

See also:

from_array (a[, n])
Returns a Sqib.Seq based on an array or its first elements.

Parameters:

  • a An array on which to base the new sequence.
  • n The number of elements to include from a. If omitted, the length is recomputed from #a at the beginning of each new iteration. (optional)

Returns:

    A Sqib.Seq consisting of the first n elements of a, or, if n is omitted, the first #a elements of a.

See also:

from_array_slice (a, start, limit)
Returns a Sqib.Seq based on the elements of a subsequence of an array between two specified indexes.

Parameters:

  • a An array on which to base the new sequence.
  • start The inclusive index of a at which to start the sequence. Must be an integer, but need not be positive.
  • limit The inclusive index of a at which to end the sequence. Must be an integer, but need not be positive.

Returns:

    A Sqib.Seq consisting of the elements of a from a[start] to a[limit], inclusive, or an empty sequence if start is greater than limit.

See also:

from_iterate (iterate[, ...])
Returns a Sqib.Seq based on the supplied iterate function.

The function iterate is expected to return an iterator function and optionally stateless iterator parameters. iterate is used in a construction similar to for _, v in iterate() do … end and has a similar contract to the built-in ipairs() or pairs() functions.

The iteration is expected to produce each successive element of the represented sequence by returning either:

  • a pair x, v, where x is any non-nil value and v is the next element value, or
  • nil, signaling the end of the sequence.

The index values produced by the iterator need not be in any particular order; the requirement is only that each index value be non-nil if a value is being returned or nil once the sequence is exhausted. The sequence returned from this method discards the indexes from the iterator and provides its own indexes that comply with the contract of iterate.

function example_iterate(start, limit)
  local i = start - 1

  return function()
    if i < limit then
      i = i + 1
      return true, i
    end
  end
end

local seq = Sqib.from_iterate(example_iterate, 10, 13)
-- sequence is 10, 11, 12, 13

[Implementation detail: The number of parameters in … is subject to the same limitations as unpack.]

Parameters:

  • iterate A function which returns an iterator function.
  • ... Parameters that will be passed to iterate at the beginning of each new iteration. (optional)

Returns:

    A new Sqib.Seq based on the abstract sequence traversed by iterate, with renumbered indexes.

See also:

from_keys (t)
Returns a Sqib.Seq based on the keys of a table.

Parameters:

  • t A table whose keys to traverse.

Returns:

    A new Sqib.Seq representing the keys of t, in no particular order.
from_packed (t)
Returns a Sqib.Seq based on a packed list.

For the purposes of this method, a packed list is a table t which has a field t.n that is a nonnegative integer and which has elements t[1] through t[t.n] (any or all of which may be nil) that constitute a conceptual list. This method produces a Sqib.Seq representing this list.

Parameters:

  • t A packed list.

Returns:

    A new Sqib.Seq based on the elements of the packed list t.
from_pairs (t[, result_selector])
Returns a Sqib.Seq based on the key-value pairs of a table.

Parameters:

  • t A table whose key-value pairs to traverse.
  • result_selector A function (k, v) that selects the output element based on each key-value pair. If omitted, the selector produces a two-element array {k, v} containing the key and the value. (optional)

Returns:

    A new Sqib.Seq representing the key-value pairs of t, in no particular order.
from_values (t)
Returns a Sqib.Seq based on the values of a table.

Parameters:

  • t A table whose values to traverse.

Returns:

    A new Sqib.Seq representing the values of t, in no particular order.
from_yielder (yielder[, ...])
Returns a Sqib.Seq based on the supplied yielder function.

The function yielder is expected to call coroutine.yield(v) once for each successive value v in the iteration. yielder is called from a coroutine using the supplied parameters, if any, at the beginning of each new iteration.

function example_yielder(start, limit)
  for i = start, limit do
    for j = start, limit do
      coroutine.yield("(" .. i .. "," .. j .. ")")
    end
  end
end

local seq = Sqib.from_yielder(example_yielder, 1, 2)
-- seq is "(1,1)", "(1,2)", "(2,1)", "(2,2)"

[Implementation detail: The number of parameters in … is subject to the same limitations as unpack.]

Parameters:

  • yielder A function which returns an iterator function.
  • ... Parameters that will be passed to iterate at the beginning of each new iteration. (optional)

Returns:

    A new Sqib.Seq based on the abstract sequence traversed by iterate, with renumbered indexes.
over (...)
Returns a Sqib.Seq over the supplied sequence of parameters.

Parameters:

  • ... Elements to be traversed by the new sequence.

Returns:

    A new Sqib.Seq based on the values of ….
range (start_value, limit_value[, step=1])

Returns a new Sqib.Seq over the specified range.

The sequence produced is the same sequence produced by the for loop

 for i=start_value, limit_value, step do ... end

Parameters:

  • start_value The initial value of the range.
  • limit_value The limit for the final value of the range.
  • step The step value for iteration. (default 1)

Returns:

    A new Sqib.Seq with contents based on the specified range.
times (value, count)
Returns a new Sqib.Seq that repeats a specified value a specified number of times.

Parameters:

  • value The element value to be repeated.
  • count The number of times to repeat value.

Returns:

    A new Sqib.Seq consisting of value repeated count times.

Class Sqib.Seq

The abstract base class for Sqib sequences.

Derived classes must implement Sqib.Seq:iterate. If a derived class can determine its own size in less-than-linear time, it should also override Sqib.Seq:count.

Sqib.Seq:all (predicate)
Returns whether all elements of this sequence satisfy a predicate.

If this sequence is empty, returns true.

Parameters:

  • predicate A function (v, i) that returns true if the current element satisfies a condition or false otherwise.

Returns:

    true if all elements of this sequence satisfy predicate, or false otherwise.
Sqib.Seq:any ([predicate])
Returns whether this sequence contains any elements or contains any elements that satisfy a predicate.

If this sequence is empty, returns false.

Parameters:

  • predicate A function (v, i) that returns true if the current element satisfies a condition or false otherwise. (optional)

Returns:

    If predicate is supplied, true if any element in this sequence satisfies predicate, or false otherwise. If predicate is omitted, true if this sequence contains any elements, or false otherwise.
Sqib.Seq:append (...)
Produces a Sqib.Seq consisting of this sequence followed by the specified elements.

Parameters:

  • ... Elements to append to this sequence.

Returns:

    A Sqib.Seq consisting of the elements of this sequence followed by the specified additional elements.
Sqib.Seq:batch (block_size[, result_selector])

Produces a Sqib.Seq consisting of this sequence’s elements as blocks of a specified number of elements each.

Each block before the final block contains exactly block_size elements. The final block contains the remainder of the sequence, which is as few as one element or as many as block_size elements. No block will ever contain zero elements.

By default, the resulting sequence will produce each block as a packed list. If another form is more useful, specify a result_selector that accepts an array and size and produces the desired element.

-- Example: Produces each block as a new Sqib.Seq
local seq_of_seq = seq:batch(block_size, function(a, n) return Sqib.from_array(a, n) end)

Parameters:

  • block_size The number of elements to include in each block. Must be a positive integer.
  • result_selector A function (a, n) to be applied to each block before it is returned from the iterator, where a is an array containing the elements of the block and n is the number of elements in the block. If omitted, the result selector defaults to returning a packed list (i.e. by setting a.n to n and returning a). (optional)

Returns:

    A Sqib.Seq that iterates over this sequence block_size elements at a time.
Sqib.Seq:call (f[, ...])

Calls the specified function as if it were a method on this sequence.

This is a simple way to call custom sequence operations fluently without assigning them directly to to Sqib.Seq table.

function my_every_n(seq, n)
  return seq:filter(function(_,i) return i % n == 0 end)
end

-- Use call
local seq = Sqib.over(1,2,3,4,5,6,7,8,9,10)
  :call(my_every_n, 3)
-- seq is now the sequence 3, 6, 9

Parameters:

  • f A function to call as if it were a method.
  • ... Additional parameters for f. (optional)

Returns:

    The result of calling f(self, …), where self is this sequence.
Sqib.Seq:concat (...)
Returns a Sqib.Seq consisting of this sequence followed by the specified additional sequences.

Parameters:

  • ... Sequence-like values to be converted to sequences (using the same rules as Sqib.from) and concatenated to this sequence.

Returns:

    A Sqib.Seq consisting of the elements of this sequence followed by the elements of each of the specified additional sequences.

Raises:

  • When any parameter has no automatic conversion to a sequence.
  • When, for any parameter v, v:to_sqib_seq() is found but returns a value that does not appear to be a sequence (i.e., does not pass the is_sqib_seq() test).

See also:

Sqib.Seq:copy_into_array (a[, start_index=1])
Copies all elements of this sequence into an existing array or object.

The first element of this sequence is copied to a[start_index], the second to a[start_index + 1], and so on. Any values already in these positions are overwritten.

Parameters:

  • a An array or array-like object into which elements will be copied.
  • start_index The first index of a to use for copying elements. If provided, this must be an integer. The value need not be positive (the caveats of using non-1-based arrays in Lua are well documented elsewhere). (default 1)

Returns:

    The number of elements copied. (The copied elements are a[start_index] through a[start_index - 1 + <number of elements copied>].)
Sqib.Seq:count ([predicate])
Counts the number of elements, or the number of elements that satisfy a predicate, in this sequence.

Parameters:

  • predicate A function (v, i) that returns true if the current element satisfies a condition or false otherwise. If omitted, all elements are counted. (optional)

Returns:

    The total number of elements (if predicate is omitted) or the number of elements that satisfy predicate (if predicate is supplied) in this sequence.
Sqib.Seq:filter (predicate)
Filters this sequence to only the elements that satisfy a predicate.

Parameters:

  • predicate A function (v, i) that returns true if the current element satisfies a condition or false otherwise.

Returns:

    A new Sqib.Seq consisting of the elements of this sequence that satisfy predicate.
Sqib.Seq:flat_map ([selector[, convert_result=true]])
Maps this sequence by applying a sequence-producing selector, then returns a sequence from the concatenated results.

Parameters:

  • selector A sequence-returning function (v, i) to apply to each element in the sequence. If omitted, the selector returns the element value. (optional)
  • convert_result Indicates whether the value returned from the selector should be converted into a Sqib.Seq using Sqib.from, which allows the operation to flatten certain other non-Sqib.Seq sequences. Set to false if the selector always produces a Sqib.Seq and doesn’t need the additional conversion. (default true)

Returns:

    A new Sqib.Seq consisting of the concatenated elements of the sequences returned by selector as applied to each element from this sequence.
Sqib.Seq:force ()
Forces immediate evaluation of this sequence.

This method iterates this sequence completely, making an immutable copy, and returns a Sqib.Seq based on the copy.

The main effects of using the returned Sqib.Seq in place of the original sequence are:

  • The resulting sequence itself doesn’t need to perform any non-trivial computations. Any (potentially intensive) computation specified before the force only happens once.
  • The resulting sequence will not vary between iterations, even if
    • this source sequence is mutable (such as an array passed to Sqib.from, if anything other than the sequence still has a reference to it)
    • this source sequence is based on computations which use variables that are themselves mutable
  • The resulting sequence generally occupies more memory.

The effect of conversions such as Sqib.Seq:to_array or Sqib.Seq:pack is similar, except that those methods do not directly produce a Sqib.Seq while this method does not produce an object which can be accessed as a table.

Returns:

    A new Sqib.Seq based on an immutable copy of the values from an immediate, full iteration of this Sqib.Seq.
Sqib.Seq:is_sqib_seq ()
Returns whether this object should be treated as Sqib.Seq.

A function named is_sqib_seq on any object is assumed (e.g. by Sqib.from) to return true if the object is a Sqib.Seq (or close enough to one that it can be treated as one). This method exists for the purpose of identifying an object as a Sqib.Seq in absence of any reliable way to do so in Lua.

The is_sqib_seq method of Sqib.Seq is specified to always return true. This should not be overridden by derived types of Sqib.Seq.

Returns:

    true.

See also:

Sqib.Seq:iterate ()
Returns a closure-based iterator over this sequence.

Each time the returned iterator is called, it returns a pair of values i, v (an index and a value, respectively) that represent each successive element from the sequence, until the sequence is exhausted, at which point i will be nil.

The index i is defined to start at 1 and increase by 1 with each new element.

Returns:

    A closure-based (non-stateless) iterator over this sequence.
Sqib.Seq:map (selector)
Maps each element of this sequence by applying a selector.

Parameters:

  • selector A function (v, i) to apply to each element in the sequence.

Returns:

    A new Sqib.Seq consisting of the results of applying selector to each element of this sequence.
Sqib.Seq:new ([o={}])
The constructor for an abstract Sqib.Seq.

The implementation of this method does nothing beyond creating the object and setting the type’s index and the instance’s metatable.

See the functions of Sqib (for example, Sqib.from) for simple ways to create Sqib.Seq objects from actual data.

Parameters:

  • o A table to convert into this type. (default {})

Returns:

    o, having been converted to this type.
Sqib.Seq:pack ()
Copies this sequence into a new packed list.

Returns:

    A new table containing the elements of this sequence, with a field n containing the length of the list.
Sqib.Seq:pairs_to_hash (pair_selector)
Creates a new dictionary-style table using the provided selector to determine each key-value pair.

Parameters:

  • pair_selector Function (v, i) that returns k, v, the key and value for a pair.

Returns:

    The newly created table.

Raises:

  • When pair_selector is not provided.
  • When any key appears more than once.

See also:

Sqib.Seq:reversed ()
Returns a new Sqib.Seq that consists of the elements of this sequence in reverse order.

The reverse operation itself is deferred and occurs whenever the returned Sqib.Seq is actually iterated. When an iterator is retrieved, the entire contents of the source sequence are copied into an internal table. The resulting element values are iterated in reverse order.

Returns:

    A Sqib.Seq representing a copy of this sequence whose elements have been reversed.
Sqib.Seq:skip (count)
Skips a specified number of elements, then produces the remainder.

Parameters:

  • count A number of elements to skip. If this is zero or less, the result is the entire sequence. If this is the length of the sequence or greater, the result is empty.

Returns:

    A Sqib.Seq consisting of the elements of this sequence after the first count elements have been skipped.
Sqib.Seq:skip_while (predicate)
Skips all elements while a predicate is satisfied, then produces the remainder.

Parameters:

  • predicate A function (v, i) to test elements. Elements are skipped until the first element for which this returns false; the remaining elements are passed through untested.

Returns:

    A Sqib.Seq consisting of all elements of this sequence including and after the first element for which the predicate returns false.
Sqib.Seq:sorted (...)
Returns a new Sqib.Seq that consists of the elements of this sequence sorted according to the specified options.

With no options specified, the call

 local result = seq:sorted()

is equivalent to

 local result = seq:sorted({
   by = function(v) return v end,
   compare = function(a, b) return (a < b) and -1 or (a > b) and 1 or 0 end,
   ascending = true,
   stable = false,
   })

Otherwise, one or more orderings can be specified, each with its own full set of parameters. If two elements are tied according to the first ordering, then the second ordering is tried and so on until the tie is broken.

-- Example of sorting first by one field, then another, then another
-- (stable = true in any of the orderings causes the entire sort to be stable)
local result = seq:sorted(
  { by = function(v) return v.primary_field end, stable = true },
  { by = function(v) return v.secondary_field end, ascending = false },
  { by = function(v) return v.tertiary_field end, compare = some_compare_function }
  )

If all comparisons tie for two elements and stable is true for any of the orderings, then the element that occurred earlier in the input sequence will appear earlier in the output as well. If all comparisons tie for two elements and stable is not true for any of the orderings, the elements may appear in either order.

The sort operation itself is deferred and occurs at the beginning of each new iteration. All elements of this sequence are iterated at once, copied internally, and sorted, then this sorted copy is iterated.

Parameters:

  • ...

    Ordering specifications to be applied in order while comparing elements; each parameter is a table that may define any of the following:

    • by: A function (v) that returns a value that will be the subject of the sort. If omitted, the sort will be performed on the value itself.
    • compare: A ternary compare function (a, b) that returns a negative number if a comes before b, a positive number if a comes after b, or 0 if a and b are tied. As a backward compatibility measure, if this method returns a non-number value, such as true or false, it will be treated as an ordinary Lua comparer (returns truthy if a comes before b or falsy otherwise), but if stable is set to true or if multiple orderings are specified, then the comparer may need to be called twice (once in each order) to determine whether two elements are tied. If omitted, the comparison is equivalent to the expression (a < b) and -1 or (a > b) and 1 or 0.
    • ascending: If true, the elements are arranged in ascending order. If false, the elements are arranged in descending order. If omitted, defaults to true.
    • stable: If true, the sort is stable; that is, any two elements that are tied will be sorted in the same order in which they appear in the input. If false, the sort is not guaranteed to be stable. If omitted, defaults to false. If multiple orderings are specified and at least one specifies stable as true, the entire result will be stable.

Returns:

    A Sqib.Seq representing a copy of this sequence whose elements have been sorted as specified.
Sqib.Seq:take (count)
Passes a specified number of elements, then ends the sequence.

Parameters:

  • count A number of elements to take. If this is zero or less, the result is empty. If this is the length of the sequence or greater, the result is the entire sequence.

Returns:

    A Sqib.Seq consisting of the first count elements of this sequence.
Sqib.Seq:take_while (predicate)
Passes all elements while a predicate is satisfied, then ends the sequence.

Parameters:

  • predicate A function (v, i) to test elements. Elements are passed until the first element for which this returns false; the remaining elements are ignored.

Returns:

    A Sqib.Seq consisting of all elements of this sequence before, but not including, the first element for which the predicate returns false.
Sqib.Seq:times (count)
Returns a new Sqib.Seq that repeats this entire sequence a specified number of times.

Note that a new iteration of this sequence is started for every repetition. This may include reevaluating sequence contents, filters, mappings, orderings, and so forth each time. If this isn’t what you intended, use e.g. force to fully evaluate the sequence once before using this method.

Parameters:

  • count The number of times to repeat this sequence.

Returns:

    A new Sqib.Seq consisting of the elements of this sequence repeated count times.
Sqib.Seq:to_array ([include_length=false])
Copies this sequence into a new array.

Parameters:

  • include_length If true, this method returns the new array and the number of elements; otherwise, this method returns only the array. (default false)

Returns:

    a, n, if include_length, or a, otherwise, where a is the new array and n is the number of elements copied.
Sqib.Seq:to_hash ([key_selector[, value_selector]])
Creates a new dictionary-style table using the provided selectors to determine the keys and values.

Parameters:

  • key_selector Function (v, i) that selects the key for an item. If omitted, the value is selected. (optional)
  • value_selector Function (v, i) that selects the value for an item. If omitted, the value is selected. (optional)

Returns:

    The newly created table.

Raises:

When any key appears more than once.

See also:

Sqib.Seq:to_sqib_seq ()
Returns this Sqib.Seq object.

A method named to_sqib_seq on any object is assumed (e.g. by from) to return a Sqib sequence equivalent to the object.

The to_sqib_seq method of Sqib.Seq is specified to always return the implied self parameter. This should not be overridden by derived types of Sqib.Seq.

Returns:

    self (the object on which this method was called).

See also:

Sqib.Seq:unique ([key_selector])
Filters this sequence to distinct elements by including only the first element having a selected key.

This implementation is table-based; a table is used to keep track of the keys of already seen items.

Any two elements are considered distinct if their keys do not refer to the same item when used to index a table; that is, for a and b, for some table seen, seen[key_selector(a)] and seen[key_selector(b)] don’t refer to the same item.

A special case is implemented so that nil can be used as a key.

Parameters:

  • key_selector A function (v, i) that selects a key by which to determine uniqueness. If this is omitted, the key selector returns the value itself as a key. (optional)

Returns:

    A Sqib.Seq consisting of each element of this sequence for which the selected key has not already appeared.
Sqib.Seq:unpack ()
Returns this entire sequence as a return value list.

Similarly to the built-in unpack, this method produces the values from a sequence in a form suitable for multiple assignment or for appending to an array or parameter list.

local seq = Sqib.over(10, 20, 30)
local q, r, s = seq:unpack()  -- like q = 10, r = 20, s = 30
local a = {seq:unpack()}      -- like a = {10, 20, 30}
local a2 = {0, seq:unpack()}  -- like a = {0, 10, 20, 30}
print("values", seq:unpack()) -- like print("values", 10, 20, 30)

[Implementation detail: This implementation may cause a stack overflow condition for a very large number of elements (as determined during testing, a little over a million; may vary by target environment). The implementation of this method relies on a recursive function call that Lua 5.1 seems unable to tail-call optimize. The depth of the call stack is directly proportional to the number of elements.]

Returns:

    All elements of this sequence in order.
generated by LDoc 1.4.6 Last updated 2020-09-03 20:19:10