doc: more details about iterators over dicts
This commit is contained in:
parent
d7dd628fc9
commit
0d44b8697b
@ -1419,7 +1419,8 @@ Lists and, soon, dictionaries, are implicit data-sources. The syntax for creatin
|
||||
*_iterator_* = "**$(**" _data-source_ "**)**" +
|
||||
_data-source_ = _explicit_ | _list-spec_ | _dict-spec_ | _custom-data-source_
|
||||
|
||||
_explicit_ = _any-expr_ { "," _any-expr_ } +
|
||||
_explicit_ = _any-expr_ { "," _any-expr_ }
|
||||
|
||||
_list-spec_ = _list_ _range-options_ +
|
||||
_list_ = "**[**" _any-expr_ { "," _any-expr_ } "**]**" +
|
||||
_range-options_ = [ "," _start-index_ [ "," _end-index_ [ "," _step_ ]]] +
|
||||
@ -1429,11 +1430,25 @@ _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_ ]
|
||||
_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**" | ""
|
||||
|
||||
_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)` +
|
||||
@ -1512,7 +1527,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, if it can be determined.
|
||||
* *_.count_*: returns the number of elements in the iterator already visited.
|
||||
* *_.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.
|
||||
|
||||
@ -3280,8 +3280,10 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<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> }<br>
|
||||
<em>list-spec</em> = <em>list</em> <em>range-options</em><br>
|
||||
<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>
|
||||
@ -3291,13 +3293,47 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<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>
|
||||
<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>
|
||||
</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>>>></code> <code class="blue">it = $("A", "B", "C")</code><br>
|
||||
@ -3397,7 +3433,7 @@ Eval Error: add(): param nr 2 (2 in 0) has wrong type string, number expected<br
|
||||
<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, if it can be determined.</p>
|
||||
<p><strong><em>.count</em></strong>: returns the number of elements in the iterator already visited.</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>
|
||||
@ -3457,7 +3493,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 08:18:50 +0200
|
||||
Last updated 2026-04-19 15:03:48 +0200
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user