doc: further details about iterator definition
This commit is contained in:
parent
1f57ba28dd
commit
d7dd628fc9
@ -1410,17 +1410,42 @@ Same as add() but returns the product of the values of the parameters.
|
||||
== Iterators
|
||||
Iterators are objects that can be used to traverse collections, such as lists and dictionaries. They are created by providing a _data-source_ object, the collection, in a `$(<data-source>)` expression. Once an iterator is created, it can be used to access the elements of the collection one by one.
|
||||
|
||||
Data-sources are objects that can be iterated over. They are defined as dictionaries having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator. The _next_ function must return a special value, [blue]_nil_, when there are no more elements to iterate over.
|
||||
In general, data-sources are objects that can be iterated over. They are defined as dictionaries having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator. The _next_ function must return a special value, [blue]_nil_, when there are no more elements to iterate over.
|
||||
|
||||
Lists and, soon, dictionaries, are implicit data-sources. The syntax for creating an iterator is as follows.
|
||||
|
||||
.Iterator creation syntax
|
||||
====
|
||||
*_iterator_* = "**$(**" _data-source_ "**)**" +
|
||||
_data-source_ = _list_ | _dict_ | _custom-data-source_ +
|
||||
_data-source_ = _explicit_ | _list-spec_ | _dict-spec_ | _custom-data-source_
|
||||
|
||||
_explicit_ = _any-expr_ { "," _any-expr_ } +
|
||||
_list-spec_ = _list_ _range-options_ +
|
||||
_list_ = "**[**" _any-expr_ { "," _any-expr_ } "**]**" +
|
||||
_range-options_ = [ "," _start-index_ [ "," _end-index_ [ "," _step_ ]]] +
|
||||
_start-index_, _end-index_, _step_ = _integer-expr_
|
||||
|
||||
_dict-spec_ = _dict_ _dict-options_ +
|
||||
_dict_ = "**{**" _key-value-pair_ { "," _key-value-pair_ } "**}**" +
|
||||
_key-value-pair_ = _scalar-value_ ":" _any-expr_ +
|
||||
_scalar-value_ = _string_ | _number_ | _boolean_ +
|
||||
_dict-options_ = [ "," _to-be-defined_ ]
|
||||
|
||||
_custom-data-source_ = _dict_ having the key `next` whose value is a function that returns the next element of the collection and updates the state of the iterator.
|
||||
====
|
||||
|
||||
.Example: iterator over an explicit list of elements
|
||||
`>>>` [blue]`it = $("A", "B", "C")` +
|
||||
[green]`$(#3)` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"A"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"B"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`"C"` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[red]`Eval Error: EOF`
|
||||
|
||||
.Example: iterator over a list
|
||||
`>>>` [blue]`it = $(["one", "two", "three"])` +
|
||||
[green]`$(#3)` +
|
||||
@ -1433,6 +1458,37 @@ _custom-data-source_ = _dict_ having the key `next` whose value is a function th
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[red]`Eval Error: EOF`
|
||||
|
||||
On a list-type iterator creation expression, it is possible to specify an index range and a step to iterate over a subset of the list.
|
||||
|
||||
Indexing starts at 0. If the start index is not specified, it defaults to 0. If the end index is not specified, it defaults to the index of the last element of the list. If the step is not specified, it defaults to 1.
|
||||
|
||||
Negative indexes are allowed. They are interpreted as offsets from the end of the list. For example, an end index of -1 means the index of the last element of the list, an end index of -2 means the index of the second to last element of the list, and so on.
|
||||
|
||||
Negative steps are also allowed. They are interpreted as reverse iteration. For example, a step of -1 means to iterate over the list in reverse order.
|
||||
|
||||
.Example: iterator over a list with index range and step
|
||||
`>>>` [blue]`it = $([1, 2, 3, 4, 5], 1, 4, 2)` +
|
||||
[green]`$(#5)` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`2` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`4` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[red]`Eval Error: EOF`
|
||||
|
||||
.Example: iterator over a list in reverse order
|
||||
`>>>` [blue]`it = $([1, 2, 3], -1, 0, -1)` +
|
||||
[green]`$(#3)` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`3` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`2` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[green]`1` +
|
||||
`>>>` [blue]`it{plusplus}` +
|
||||
[red]`Eval Error: EOF`
|
||||
|
||||
|
||||
=== Operators on iterators
|
||||
The above example shows the use of the [blue]`{plusplus}` operator to get the next element of an iterator. The [blue]`{plusplus}` operator is a postfix operator that can be used with iterators. It returns the next element of the collection and updates the state of the iterator. When there are no more elements to iterate over, it returns the error [red]_Eval Error: EOF_.
|
||||
|
||||
|
||||
115
doc/Expr.html
115
doc/Expr.html
@ -3144,13 +3144,51 @@ Computes and returns the value of the <span class="underline">string</span> expr
|
||||
</div>
|
||||
<div class="sect3">
|
||||
<h4 id="_module_math_arith"><a class="anchor" href="#_module_math_arith"></a><a class="link" href="#_module_math_arith">7.1.5. Module "math.arith"</a></h4>
|
||||
<div class="paragraph">
|
||||
<p>Currently, the "math.arith" module provides two functions, add() and mul(), that perform addition and multiplication of an arbitrary number of parameters. More functions will be added in the future.</p>
|
||||
</div>
|
||||
<div class="sect4">
|
||||
<h5 id="_add"><a class="anchor" href="#_add"></a><a class="link" href="#_add">add()</a></h5>
|
||||
|
||||
<div class="paragraph">
|
||||
<p>Syntax:<br>
|
||||
<code>    add(<num-expr1>, <num-expr2>, …​) → any</code><br>
|
||||
<code>    add(<list-of-num-expr>]) → any</code><br>
|
||||
<code>    add(<iterator-over-num-values>) → any</code></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Returns the sum of the values of the parameters. The parameters can be of any numeric type for which the <code class="blue">+</code> operator is defined. The result type depends on the types of the parameters. If all parameters are of the same type, the result is of that type. If the parameters are of different types, the result is of the type that can represent all the parameter types without loss of information. For example, if the parameters are a mix of integers and floats, the result is a float. If the parameters are a mix of number types, the result has the type of the most general one.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Examples</div>
|
||||
<p>>>> add(1,2,3)<br>
|
||||
6
|
||||
>>> add(1.1,2.1,3.1)<br>
|
||||
6.300000000000001<br>
|
||||
>>> add("1","2","3")<br>
|
||||
Eval Error: add(): param nr 1 (1 in 0) has wrong type string, number expected<br>
|
||||
>>> add(1:3, 2:3, 3:3)<br>
|
||||
2:1<br>
|
||||
>>> add(1, "2")<br>
|
||||
Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br>
|
||||
>>> add([1,2,3])<br>
|
||||
6<br>
|
||||
>>> iterator=$([1,2,3]); add(iterator)<br>
|
||||
6<br>
|
||||
>>> add($([1,2,3]))<br>
|
||||
6</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect4">
|
||||
<h5 id="_mul"><a class="anchor" href="#_mul"></a><a class="link" href="#_mul">mul()</a></h5>
|
||||
|
||||
<div class="paragraph">
|
||||
<p>Syntax:<br>
|
||||
<code>    mul(<num-expr1>, <num-expr2>, …​) → any</code><br>
|
||||
<code>    mul(<list-of-num-expr>]) → any</code><br>
|
||||
<code>    mul(<iterator-over-num-values>) → any</code></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Same as add() but returns the product of the values of the parameters.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect3">
|
||||
@ -3229,7 +3267,7 @@ Computes and returns the value of the <span class="underline">string</span> expr
|
||||
<p>Iterators are objects that can be used to traverse collections, such as lists and dictionaries. They are created by providing a <em>data-source</em> object, the collection, in a <code>$(<data-source>)</code> expression. Once an iterator is created, it can be used to access the elements of the collection one by one.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Data-sources are objects that can be iterated over. They are defined as dictionaries having the key <code>next</code> whose value is a function that returns the next element of the collection and updates the state of the iterator. The <em>next</em> function must return a special value, <em class="blue">nil</em>, when there are no more elements to iterate over.</p>
|
||||
<p>In general, data-sources are objects that can be iterated over. They are defined as dictionaries having the key <code>next</code> whose value is a function that returns the next element of the collection and updates the state of the iterator. The <em>next</em> function must return a special value, <em class="blue">nil</em>, when there are no more elements to iterate over.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Lists and, soon, dictionaries, are implicit data-sources. The syntax for creating an iterator is as follows.</p>
|
||||
@ -3239,12 +3277,41 @@ Computes and returns the value of the <span class="underline">string</span> expr
|
||||
<div class="content">
|
||||
<div class="paragraph">
|
||||
<p><strong><em>iterator</em></strong> = "<strong>$(</strong>" <em>data-source</em> "<strong>)</strong>"<br>
|
||||
<em>data-source</em> = <em>list</em> | <em>dict</em> | <em>custom-data-source</em><br>
|
||||
<em>custom-data-source</em> = <em>dict</em> having the key <code>next</code> whose value is a function that returns the next element of the collection and updates the state of the iterator.</p>
|
||||
<em>data-source</em> = <em>explicit</em> | <em>list-spec</em> | <em>dict-spec</em> | <em>custom-data-source</em></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p><em>explicit</em> = <em>any-expr</em> { "," <em>any-expr</em> }<br>
|
||||
<em>list-spec</em> = <em>list</em> <em>range-options</em><br>
|
||||
<em>list</em> = "<strong>[</strong>" <em>any-expr</em> { "," <em>any-expr</em> } "<strong>]</strong>"<br>
|
||||
<em>range-options</em> = [ "," <em>start-index</em> [ "," <em>end-index</em> [ "," <em>step</em> ]]]<br>
|
||||
<em>start-index</em>, <em>end-index</em>, <em>step</em> = <em>integer-expr</em></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p><em>dict-spec</em> = <em>dict</em> <em>dict-options</em><br>
|
||||
<em>dict</em> = "<strong>{</strong>" <em>key-value-pair</em> { "," <em>key-value-pair</em> } "<strong>}</strong>"<br>
|
||||
<em>key-value-pair</em> = <em>scalar-value</em> ":" <em>any-expr</em><br>
|
||||
<em>scalar-value</em> = <em>string</em> | <em>number</em> | <em>boolean</em><br>
|
||||
<em>dict-options</em> = [ "," <em>to-be-defined</em> ]</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p><em>custom-data-source</em> = <em>dict</em> having the key <code>next</code> whose value is a function that returns the next element of the collection and updates the state of the iterator.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: iterator over an explicit list of elements</div>
|
||||
<p><code>>>></code> <code class="blue">it = $("A", "B", "C")</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"A"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"B"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">"C"</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="red">Eval Error: EOF</code></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: iterator over a list</div>
|
||||
<p><code>>>></code> <code class="blue">it = $(["one", "two", "three"])</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
@ -3257,6 +3324,42 @@ Computes and returns the value of the <span class="underline">string</span> expr
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="red">Eval Error: EOF</code></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>On a list-type iterator creation expression, it is possible to specify an index range and a step to iterate over a subset of the list.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Indexing starts at 0. If the start index is not specified, it defaults to 0. If the end index is not specified, it defaults to the index of the last element of the list. If the step is not specified, it defaults to 1.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Negative indexes are allowed. They are interpreted as offsets from the end of the list. For example, an end index of -1 means the index of the last element of the list, an end index of -2 means the index of the second to last element of the list, and so on.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Negative steps are also allowed. They are interpreted as reverse iteration. For example, a step of -1 means to iterate over the list in reverse order.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: iterator over a list with index range and step</div>
|
||||
<p><code>>>></code> <code class="blue">it = $([1, 2, 3, 4, 5], 1, 4, 2)</code><br>
|
||||
<code class="green">$(#5)</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">2</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">4</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="red">Eval Error: EOF</code></p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<div class="title">Example: iterator over a list in reverse order</div>
|
||||
<p><code>>>></code> <code class="blue">it = $([1, 2, 3], -1, 0, -1)</code><br>
|
||||
<code class="green">$(#3)</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">3</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">2</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="green">1</code><br>
|
||||
<code>>>></code> <code class="blue">it++</code><br>
|
||||
<code class="red">Eval Error: EOF</code></p>
|
||||
</div>
|
||||
<div class="sect2">
|
||||
<h3 id="_operators_on_iterators"><a class="anchor" href="#_operators_on_iterators"></a><a class="link" href="#_operators_on_iterators">8.1. Operators on iterators</a></h3>
|
||||
<div class="paragraph">
|
||||
@ -3354,7 +3457,7 @@ Iterators built on custom data-sources can provide additional named operators, d
|
||||
</div>
|
||||
<div id="footer">
|
||||
<div id="footer-text">
|
||||
Last updated 2026-04-18 12:01:15 +0200
|
||||
Last updated 2026-04-19 08:18:50 +0200
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user