Find a value in the sequence offset from the current location.

Like Enum.at, this function retrieves the value at the given index, offset from the current location in the sequence. This does not advance the sequence iterator, and so provides different functionality than simply calling drop(n) |> take(1).

If a sequence is finite. and the index provided is beyond the end of the sequence, a nil value is returned.

This function uses a timeout during processing - if iterating to and retrieving the target value takes longer than the timeout, the return value from the function will be :timeout. The default timeout is 1,000 milliseconds.

Options

• timeout. Integer. Default 1_000. Number of milliseconds to iterate for a value before stopping

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.start()
iex> seq |> Sequence.at(10)
11
iex> seq.index
0
iex> seq.value
1

iex> seq = Sequence.create(Sequence.Basic, :decimal_digits) |> Sequence.start()
iex> seq |> Sequence.at(20)
nil
iex> seq.index
0
iex> seq.value
0

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.start()
iex> seq |> Sequence.at(1_000_000, timeout: 5)
:timeout

Scan all loaded applications and modules for sequences.

This is almost identical to the available/1 function, but it scans a selection of loaded applications and modules, excluding the core libraries, for sequences. The return values are the same as for available/1.

List available sequence in a specific module.

Sequences are organized into modules, with sequences of different sources or shapes in different modules. Sequences built or included via alternate packages can also be queried this way.

Example

 iex> Sequence.available(Sequence.Basic) |> length()
 3

 iex> Sequence.available(Sequence.Basic) |> List.last()
 %{description: "Whole numbers: [1, 2, 3, 4, 5, ...]", name: "Whole Numbers", sequence: :whole_numbers, module: Sequence.Basic}

Instantiate an instance of a sequence from a sequence bundle map.

The sequence bundle map is the set of data returned for each sequence by functions like Sequence.available/0 or Sequence.OEIS.find_sequence!/1. Actual instance initialization and creation is handed off to Sequence.create/3.

Examples

iex> seq = Sequence.OEIS.find_sequence!(:a000012) |> Sequence.create()
iex> seq |> Sequence.readable_name()
"The simplest sequence of positive numbers: the all 1's sequence."

Instantiate an instance of a sequence.

iex> seq = Sequence.create(Sequence.Basic, :empty)
iex> seq |> Sequence.readable_name()
"Empty sequence: []"

iex> seq = Sequence.create(Sequence.OEIS.Core, :fibonacci)
iex> seq |> Sequence.take!(10)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

Some sequences accept options, which change the progression or shape of the generated sequence data:

iex> Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.take!(5)
[1, 2, 3, 4, 5]

iex> Sequence.create(Sequence.Basic, :whole_numbers, [start: 13]) |> Sequence.take!(5)
[13, 14, 15, 16, 17]

Finding Available Sequences

Sequences are referenced by Module name and a sequence identifier.

The documentation for the Sequence sub-modules contains reference data for all available sequences. See:

• Chunky.Sequence.Basic
• Chunky.Sequence.OEIS

Available sequences can be found with available/1:

iex> Sequence.available(Sequence.Basic) |> List.first()
%{description: "Decimal digits: [0, 1, 2, 3, 4, ...]", name: "Decimal Digits", sequence: :decimal_digits, module: Sequence.Basic}

The function name within a module can also be used to identify a sequence, as all sequence generation functions follow the format create_sequence_*. The OEIS fibonacci sequence is indirectly created via the function Chunky.Sequence.OEIS.Core.create_sequence_fibonacci/1.

Drop values from the front of the sequence, returning the updated sequence struct. Like Enum.drop/2.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers)
iex> seq |> Sequence.drop(10) |> Sequence.take!(10)
[11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

Retrieve sequence reference data from a sequence description dictionary, like those returned by available/1 and available/0.

Examples

iex> %{module: Chunky.Sequence.OEIS.Factors, sequence: :a052486} |> Sequence.get_references()
[{:oeis, :a052486, "https://oeis.org/A052486"}, {:wikipedia, :achilles_number, "https://en.wikipedia.org/wiki/Achilles_number"}]

Check that a sequence has more values.

Some sequences are finite, and have distinct end points. For finite sequences it can make sense to check for additional values before trying to access more data:

iex> seq = Sequence.create(Sequence.Basic, :empty) |> Sequence.next!()
iex> seq |> Sequence.has_next?()
false

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.next!()
iex> seq |> Sequence.has_next?()
true

Check if a sequence instance has a reference to a specific source.

See also get_references/1.

Examples

iex> Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.has_reference?(:wolfram)
true

iex> Sequence.create(Sequence.OEIS.Core, :a000045) |> Sequence.has_reference?(:oeis)
true

iex> Sequence.create(Sequence.OEIS.Core, :a000045) |> Sequence.has_reference?(:wolfram)
false

Determine if a specific sequence is available.

Example

iex> Sequence.is_available?(Sequence.OEIS.Core, :fibonacci)
true

iex> Sequence.is_available?(Sequence.OEIS.Core, :quadronacci)
false

Determine if a sequence is finite or infinite.

A sequence being finite or infinite is not a reflection of the absolute computability or theoretical limits of a sequence, but is determined by the quantity of values available in the Sequence library implementation.

Examples

iex> Sequence.create(Sequence.OEIS.Core, :fibonacci) |> Sequence.is_finite?()
false

iex> Sequence.create(Sequence.OEIS.Core, :a000001) |> Sequence.is_finite?()
true

Check if a sequence struct is an instance of a specific sequence.

See also is_instance?/3.

Example

iex> seq = Sequence.create(Sequence.OEIS.Core, :a000045)
iex> seq |> Sequence.is_instance?({Sequence.OEIS, :a000066})
false
iex> seq |> Sequence.is_instance?({Sequence.OEIS.Core, :a000045})
true

Check if a sequence struct is an instance of a specific sequence.

See also is_instance?/2.

Example

iex> seq = Sequence.create(Sequence.OEIS.Core, :a000045)
iex> seq |> Sequence.is_instance?(Sequence.OEIS, :a000066)
false
iex> seq |> Sequence.is_instance?(Sequence.OEIS.Core, :a000045)
true

Apply a function to every value in a Sequence. Like Enum.map/2.

For infinite sequences, this will never complete. Use Sequence.take/2 and apply a normal map.

Examples

iex> Sequence.create(Sequence.Test, :list_medium) |> Sequence.map(fn v -> v * 3 end)
[3, 6, 9, 12, 15, 18, 21, 24, 27, 30]

Iterate a sequence, returning the sequence value and updated sequence struct.

The sequence struct needs to be maintained in order to iterate a sequence; with the next/1 function, you can access the iterated value and the updated struct with the same call.

Example

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers)
iex> {val, _updated_seq} = seq |> Sequence.next()
iex> val
1

Iterate a sequence, returning only the updated Sequence structure.

The Sequence structure maintains the last index and value seen in a sequence, so is a useful shorthand when explictly returning the sequence value isn't necessary. This also makes it possible to chain together calls to next!/1 and other sequence methods.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers)
iex> updated_seq = seq |> Sequence.next!()
iex> updated_seq.value
1

Get a human readable name for a sequence.

Example

iex> Sequence.create(Sequence.OEIS.Core, :a000045) |> Sequence.readable_name()
"OEIS A000045 - Fibonacci Numbers [0, 1, 1, 2, 3, 5, ...]"

Restart a sequence that has already been iterated.

This returns a new instance of the sequence, as it would be initialized from create/3.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.start() |> Sequence.drop(30)
iex> seq.value
31
iex> seq = seq |> Sequence.restart!()
iex> seq.value
1

Create a new sequence from a simple function and an information function.

The simple sequence function should take one or more parameters, corresponding to the last N values of the sequence.

Configuration

Configuration values for the sequence function can be provided as @doc string attributes on the function. Supported attributes are:

• fill_value - Integer. Optional. Default 0. Filler value used as parameters to sequence function when existing values haven't yet been calculated
• sequence - String. Required. Short sequence summary.
• data - Map. Optional. Static information to add to sequence data attribute

Sequence Function

The sequence function will be called with the index of the current value to calculate, and the last N values of the function, where N is the function arity minus one. For example, to setup a function that adds the last three values in the sequence, with the first three values being 1, 1, 1, we could write the function:

def add_last_three(_idx, a, b, c) do
    case {a, b, c} do
        {0, 0, 0} -> 1
        {0, 0, _} -> 2
        {0, _, _} -> 3
        {va, vb, vc} -> va+vb+vc
    end
end

In this case we don't use the index of the function at all. Using the sequence_for_function/1 call we could register this sequence inside a create function (so that it can be properly instantiated):

def create_sequence_add_last_three(_opts) do
    sequence_for_function(&add_last_three/4)
end

Note that the create_sequence_add_last_three/1 function should have proper sequence and references attributes. See the Developing Sequences section for more details.

Attributes

For the @doc attributes of the sequence function to readable, the function reference passed to the sequence_for_function/1 function must be scoped to a module or module alias, not a bare referene. This means that this will work:

sequence_for_function(&Sequence.Test.seq_last_three/4)

but the following will not:

sequence_for_function(&seq_last_three/4)

Offset Attribute

Some sequences don't start counting at index 0. When a different offset is required than the default 0, the offset attribute can be used. This attribute needs to be set on the create_sequence_* function as well as the simple sequence function:

@doc offset: 2
def create_sequence_count_from_two(_opts) do

end

@doc offset: 2
def seq_count_from_two(idx) do
    # first _idx_ received will be 2
end

Data attribute

If the sequence function uses a data attribute, the call signature of the sequence function changes. For example, a simple function using the last two values, with no data attribute, will have a function signature like:

def seq_no_data_last_two(idx, a, b) do
    ...
end

While a sequence function that has a data attribute will look like:

@doc data: %{start_values: [1, 2, 3]}
def seq_with_data_last_two(data, idx, a, b) do
    ...
end

Fill Value attribute

Sequence functions that reference past values are normally called with 0 if some of the past values haven't yet been created. The fill_value doc attribute can be used to change the default value.

For instance, on the first call to iterate the sequence:

def seq_defaults_last_two(idx, a, b) do
    # a == 0
    # b == 0
end

but when we change the fill_value:

@doc fill_value: 17
def seq_fill_last_two(idx, a, b) do
    # a == 17
    # b == 17
end

Create a sequence that references a static list of data.

In the case of suitable small finite sequences, it is significantly easier to use a static list of data as a sequence. The sequence_for_list/1 function provides a simple way to do this. For example, to create a sequence for a short list of 5 numbers:

def create_sequence_my_short_list(_opts) do
    sequence_for_list([3, 7, 11, 27, 47])
end

Like with the sequence_for_function/1 example, the above example create_sequence_* function should include full sequence and references doc attributes. See the Developing Sequences section for more details.

Sequences generated from a list behave just like any other sequence.

Attributes of List Sequences

Finite Sequence

A sequence created from a list is automatically marked as finite. See is_finite?/1.

Offset Attribute

Some sequences don't start counting at index 0. When a different offset is required than the default 0, the offset attribute can be used. This attribute needs to be set on the create_sequence_* function.

@doc offset: 2
def create_sequence_count_from_two(_opts) do
    sequence_from_list([0, 0, 200, 201, 203, 204])
end

Start iteration of a created sequence. This is an alias of next!/1.

For readability it can be useful to have a separate start function to call on a newly generated sequence.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers) |> Sequence.start()
iex> seq.value
1
iex> seq.index
0

Retrieve the first N values from a sequence, like Enum.take/2.

This version of the take function returns a separate list of values and the sequence state. See also Sequence.take!/2.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers)
iex> {values, _n_seq} = seq |> Sequence.take(10)
iex> values
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

iex> seq = Sequence.create(Sequence.OEIS.Core, :fibonacci)
iex> {values, _n_seq} = seq |> Sequence.take(10)
iex> values
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]

Retrieve the next count values from a sequence, without retaining sequence state.

This function behaves similarly to the take/2 function, but the state of the sequence isn't maintained, so any subsequent calls to the same sequence will still contain the values retrieved with take!.

Examples

iex> seq = Sequence.create(Sequence.Basic, :whole_numbers)
iex> seq |> Sequence.take!(5)
[1, 2, 3, 4, 5]
iex> seq |> Sequence.take!(10)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]