doc/Expr.adoc

@@ -1410,57 +1410,17 @@ 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.
 
-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.
+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_ = _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_ = [ "," _sort-order_ [ "," _iter-mode_ ] ] +
-_sort-order_ = _asc-order_ | _desc-order_ | _no-sort_ | _default-order_ +
-_asc-order_ = "**asc**" | "**a**" +
-_desc-order_ = "**desc**" | "**d**" +
-_no-sort_ = "**none**" | "**nosort**" | "**no-sort**" | "**n**" +
-_default-order_ = "**default**" | "" +
-_iter-mode_ = _keys-iter_ | _values-iter_ | _items-iter_ | _default-iter_ +
-_keys-iter_ = "**key**" | "**keys**" | "**k**" +
-_values-iter_ = "**value**" | "**values**" | "**v**" +
-_items-iter_ = "**item**" | "**items**" | "**i**" +
-_default-iter_ = "**default**" | ""
-
+_data-source_ = _list_ | _dict_ | _custom-data-source_ +
 _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.
 ====
 
-NOTE: Currently, _default-order_ is the same as _asc-order_. In the future, it will be possible to specify a custom sorting function to define the default order.
-
-NOTE: Currently, _default-iter_ is the same as _keys-iter_. In the future, it will be possible to specify a custom iteration function to define the default iteration mode.
-
-.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)` +
@@ -1473,37 +1433,6 @@ NOTE: Currently, _default-iter_ is the same as _keys-iter_. In the future, it wi
 `>>>` [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_.
 
@@ -1527,7 +1456,7 @@ Named operators are operators that are identified by a name instead of a symbol.
 * *_.next_*: same as [blue]`{plusplus}`.
 * *_.current_*: same as [blue]`{star}`.
 * *_.reset_*: resets the state of the iterator to the initial state.
-* *_.count_*: returns the number of elements in the iterator already visited.
+* *_.count_*: returns the number of elements in the iterator, if it can be determined.
 * *_.index_*: returns the index of the current element in the iterator. Before the first use of the [blue]`{plusplus}` operator, it returns the error [red]_-1_.
 
 TIP: Iterators built on custom data-sources can provide additional named operators, depending on the functionality they want to expose. For example, an iterator over a list could provide a named operator called [blue]`.reverse` that returns the next element of the collection in reverse order.

doc/Expr.html

@@ -3144,51 +3144,13 @@ 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>&#160;&#160;&#160;&#160;add(&lt;num-expr1&gt;, &lt;num-expr2&gt;, &#8230;&#8203;) &#8594; any</code><br>
-<code>&#160;&#160;&#160;&#160;add(&lt;list-of-num-expr&gt;]) &#8594; any</code><br>
-<code>&#160;&#160;&#160;&#160;add(&lt;iterator-over-num-values&gt;) &#8594; 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>&gt;&gt;&gt; add(1,2,3)<br>
-6
-&gt;&gt;&gt; add(1.1,2.1,3.1)<br>
-6.300000000000001<br>
-&gt;&gt;&gt; add("1","2","3")<br>
-Eval Error: add(): param nr 1 (1 in 0) has wrong type string, number expected<br>
-&gt;&gt;&gt; add(1:3, 2:3, 3:3)<br>
-2:1<br>
-&gt;&gt;&gt; add(1, "2")<br>
-Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br>
-&gt;&gt;&gt; add([1,2,3])<br>
-6<br>
-&gt;&gt;&gt; iterator=$([1,2,3]); add(iterator)<br>
-6<br>
-&gt;&gt;&gt; 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>&#160;&#160;&#160;&#160;mul(&lt;num-expr1&gt;, &lt;num-expr2&gt;, &#8230;&#8203;) &#8594; any</code><br>
-<code>&#160;&#160;&#160;&#160;mul(&lt;list-of-num-expr&gt;]) &#8594; any</code><br>
-<code>&#160;&#160;&#160;&#160;mul(&lt;iterator-over-num-values&gt;) &#8594; 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">
@@ -3267,7 +3229,7 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
 <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>$(&lt;data-source&gt;)</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>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>
+<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>
 </div>
 <div class="paragraph">
 <p>Lists and, soon, dictionaries, are implicit data-sources. The syntax for creating an iterator is as follows.</p>
@@ -3277,76 +3239,11 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
 <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>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> }</p>
-</div>
-<div class="paragraph">
-<p><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>sort-order</em> [ "," <em>iter-mode</em> ] ]<br>
-<em>sort-order</em> = <em>asc-order</em> | <em>desc-order</em> | <em>no-sort</em> | <em>default-order</em><br>
-<em>asc-order</em> = "<strong>asc</strong>" | "<strong>a</strong>"<br>
-<em>desc-order</em> = "<strong>desc</strong>" | "<strong>d</strong>"<br>
-<em>no-sort</em> = "<strong>none</strong>" | "<strong>nosort</strong>" | "<strong>no-sort</strong>" | "<strong>n</strong>"<br>
-<em>default-order</em> = "<strong>default</strong>" | ""<br>
-<em>iter-mode</em> = <em>keys-iter</em> | <em>values-iter</em> | <em>items-iter</em> | <em>default-iter</em><br>
-<em>keys-iter</em> = "<strong>key</strong>" | "<strong>keys</strong>" | "<strong>k</strong>"<br>
-<em>values-iter</em> = "<strong>value</strong>" | "<strong>values</strong>" | "<strong>v</strong>"<br>
-<em>items-iter</em> = "<strong>item</strong>" | "<strong>items</strong>" | "<strong>i</strong>"<br>
-<em>default-iter</em> = "<strong>default</strong>" | ""</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>
+<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>
 </div>
 </div>
 </div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-Currently, <em>default-order</em> is the same as <em>asc-order</em>. In the future, it will be possible to specify a custom sorting function to define the default order.
-</td>
-</tr>
-</table>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-Currently, <em>default-iter</em> is the same as <em>keys-iter</em>. In the future, it will be possible to specify a custom iteration function to define the default iteration mode.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<div class="title">Example: iterator over an explicit list of elements</div>
-<p><code>&gt;&gt;&gt;</code> <code class="blue">it = $("A", "B", "C")</code><br>
-<code class="green">$(#3)</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">"A"</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">"B"</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">"C"</code><br>
-<code>&gt;&gt;&gt;</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>&gt;&gt;&gt;</code> <code class="blue">it = $(["one", "two", "three"])</code><br>
@@ -3360,42 +3257,6 @@ Currently, <em>default-iter</em> is the same as <em>keys-iter</em>. In the futur
 <code>&gt;&gt;&gt;</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>&gt;&gt;&gt;</code> <code class="blue">it = $([1, 2, 3, 4, 5], 1, 4, 2)</code><br>
-<code class="green">$(#5)</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">2</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">4</code><br>
-<code>&gt;&gt;&gt;</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>&gt;&gt;&gt;</code> <code class="blue">it = $([1, 2, 3], -1, 0, -1)</code><br>
-<code class="green">$(#3)</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">3</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">2</code><br>
-<code>&gt;&gt;&gt;</code> <code class="blue">it++</code><br>
-<code class="green">1</code><br>
-<code>&gt;&gt;&gt;</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">
@@ -3433,7 +3294,7 @@ Currently, <em>default-iter</em> is the same as <em>keys-iter</em>. In the futur
 <p><strong><em>.reset</em></strong>: resets the state of the iterator to the initial state.</p>
 </li>
 <li>
-<p><strong><em>.count</em></strong>: returns the number of elements in the iterator already visited.</p>
+<p><strong><em>.count</em></strong>: returns the number of elements in the iterator, if it can be determined.</p>
 </li>
 <li>
 <p><strong><em>.index</em></strong>: returns the index of the current element in the iterator. Before the first use of the <code class="blue">++</code> operator, it returns the error <em class="red">-1</em>.</p>
@@ -3493,7 +3354,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-19 15:03:48 +0200
+Last updated 2026-04-18 12:01:15 +0200
 </div>
 </div>
 </body>