lists: Add ListRecursionDepth setting to map, reduce, filter

The `ListRecursionDepth` controls the recusion depth for the `map`,
`reduce` and `filter` operation. This defaults to `1`, meaning that we
apply these functions only to the top level of the lists.

The idea derives from work in PR #1649, but generalizing the approach
in the PR, which only had a binary setting, disabled recursion for
`filter` entirely, and did not consider the case of `reduce`.

Fixes: #1648

Signed-off-by: Christophe de Dinechin <christophe@dinechin.org>
Suggested-by: Ed@vanGasteren.net

Author: evgaster

doc/0-Overview.md

@@ -636,6 +636,9 @@ operate on these items when it makes sense. Therefore:
 * As indicated [earlier](#representation-of-objects), quoted names in lists
   remain quoted, whereas on HP calculators, the quotes are removed.
 
+* The `MAP` operation on the HP50G recurses on inner lists. On DB48x, it does
+  not by default. This is controlled by the `ListDepthIteration` setting.
+  A value of `0` restores HP50G-style infinite recursion.
 
 ### Vectors and matrices differences
 

doc/commands/lists.md

@@ -46,12 +46,34 @@ first level of the stack should take one argument and return a single value.
 
 `{ A B ... }` `F` ▶ `{ F(A) F(B) ... }`
 
-The operation applies recursively to inner lists.
+
+```rpl
+{ 1 2 A 42.2 [ 1 2 3 ]} « →STR » MAP
+@ Expecting { "1" "2" "A" "42.2" "[ 1 2 3 ]" }
+```
+
+Unlike on HP calculators, `Map` does not apply recursively to inner lists by default.
 
 ```rpl
 { 1 2 { 3 4 } } « →STR » MAP
+@ Expecting { "1" "2" "{ 3 4 }" }
+```
+
+This can be changed by setting `ListRecursionDepth` to `0`.
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 { 3 4 } }  « →STR » MAP
 @ Expecting { "1" "2" { "3" "4" } }
+```
 
+`Map` can also be constrained to a given depth.
+
+```rpl
+2 ListRecursionDepth
+{ 1 2 { 3 { 4 { 5 } } } }  « →STR » MAP
+@ Expecting { "1" "2" { "3" "{ 4 { 5 } }" } }
+'ListRecursionDepth' Purge
 ```
 
 ## Reduce
@@ -63,6 +85,22 @@ operation to all elements.
 
 `{ A B ... }` `F` ▶ `F(F(A, B), ...)`
 
+For example, to sum all the elements in a list as text, one can use:
+
+```rpl
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12{ Hello World }"
+```
+
+Reduce obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12HelloWorld"
+'ListRecursionDepth' Purge
+```
+
 
 ## Filter
 
@@ -72,6 +110,22 @@ resulting list is built with all elements where the predicate is true.
 
 `{ A B ... }` `P` ▶ `{ A ... }` if `P(A)` is true and `P(B)` is false.
 
+For example, to filter all odd numbers in an array, one can use:
+
+```rpl
+[ 1 2 3 4 5 6 42 ] « 2 MOD 0 = » FILTER
+@ Expecting [ 2 4 6 42 ]
+```
+
+`Filter` obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 3 4 { 5 6 { 42 } } } « 2 MOD 0 = » FILTER
+@ Expecting { 2 4 { 6 { 42 } } }
+'ListRecursionDepth' Purge
+```
+
 
 ## Get
 

doc/commands/settings.md

@@ -864,6 +864,17 @@ from the HP implementations of RPL.
 
 The opposite setting is `TruthLogicForIntegers`.
 
+## ListRecursionDepth
+
+This setting selects the depth of recursion for `Map`, `Reduce` or `Filter`.
+By default, it is set to `1`, indicating that recursion only applies to the
+top-level of the list. This matches the way `Map`, `Reduce` and `Filter` work in
+most programming languages.
+
+A value larger than `1` can be used to recurse beyond the first level.
+On the HP50G, `Map` applies recursively to all levels. This can be achieved by
+setting `ListRecursionDepth` to `0`.
+
 
 # Evaluation settings
 

help/db48x.md

@@ -578,6 +578,9 @@ operate on these items when it makes sense. Therefore:
 * As indicated [earlier](#representation-of-objects), quoted names in lists
   remain quoted, whereas on HP calculators, the quotes are removed.
 
+* The `MAP` operation on the HP50G recurses on inner lists. On DB48x, it does
+  not by default. This is controlled by the `ListDepthIteration` setting.
+  A value of `0` restores HP50G-style infinite recursion.
 
 ### Vectors and matrices differences
 
@@ -12592,12 +12595,34 @@ first level of the stack should take one argument and return a single value.
 
 `{ A B ... }` `F` ▶ `{ F(A) F(B) ... }`
 
-The operation applies recursively to inner lists.
+
+```rpl
+{ 1 2 A 42.2 [ 1 2 3 ]} « →STR » MAP
+@ Expecting { "1" "2" "A" "42.2" "[ 1 2 3 ]" }
+```
+
+Unlike on HP calculators, `Map` does not apply recursively to inner lists by default.
 
 ```rpl
 { 1 2 { 3 4 } } « →STR » MAP
+@ Expecting { "1" "2" "{ 3 4 }" }
+```
+
+This can be changed by setting `ListRecursionDepth` to `0`.
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 { 3 4 } }  « →STR » MAP
 @ Expecting { "1" "2" { "3" "4" } }
+```
+
+`Map` can also be constrained to a given depth.
 
+```rpl
+2 ListRecursionDepth
+{ 1 2 { 3 { 4 { 5 } } } }  « →STR » MAP
+@ Expecting { "1" "2" { "3" "{ 4 { 5 } }" } }
+'ListRecursionDepth' Purge
 ```
 
 ## Reduce
@@ -12609,6 +12634,22 @@ operation to all elements.
 
 `{ A B ... }` `F` ▶ `F(F(A, B), ...)`
 
+For example, to sum all the elements in a list as text, one can use:
+
+```rpl
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12{ Hello World }"
+```
+
+Reduce obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12HelloWorld"
+'ListRecursionDepth' Purge
+```
+
 
 ## Filter
 
@@ -12618,6 +12659,22 @@ resulting list is built with all elements where the predicate is true.
 
 `{ A B ... }` `P` ▶ `{ A ... }` if `P(A)` is true and `P(B)` is false.
 
+For example, to filter all odd numbers in an array, one can use:
+
+```rpl
+[ 1 2 3 4 5 6 42 ] « 2 MOD 0 = » FILTER
+@ Expecting [ 2 4 6 42 ]
+```
+
+`Filter` obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 3 4 { 5 6 { 42 } } } « 2 MOD 0 = » FILTER
+@ Expecting { 2 4 { 6 { 42 } } }
+'ListRecursionDepth' Purge
+```
+
 
 ## Get
 
@@ -15120,6 +15177,17 @@ from the HP implementations of RPL.
 
 The opposite setting is `TruthLogicForIntegers`.
 
+## ListRecursionDepth
+
+This setting selects the depth of recursion for `Map`, `Reduce` or `Filter`.
+By default, it is set to `1`, indicating that recursion only applies to the
+top-level of the list. This matches the way `Map`, `Reduce` and `Filter` work in
+most programming languages.
+
+A value larger than `1` can be used to recurse beyond the first level.
+On the HP50G, `Map` applies recursively to all levels. This can be achieved by
+setting `ListRecursionDepth` to `0`.
+
 
 # Evaluation settings
 

help/db50x.md

@@ -587,6 +587,9 @@ operate on these items when it makes sense. Therefore:
 * As indicated [earlier](#representation-of-objects), quoted names in lists
   remain quoted, whereas on HP calculators, the quotes are removed.
 
+* The `MAP` operation on the HP50G recurses on inner lists. On DB48x, it does
+  not by default. This is controlled by the `ListDepthIteration` setting.
+  A value of `0` restores HP50G-style infinite recursion.
 
 ### Vectors and matrices differences
 
@@ -12600,12 +12603,34 @@ first level of the stack should take one argument and return a single value.
 
 `{ A B ... }` `F` ▶ `{ F(A) F(B) ... }`
 
-The operation applies recursively to inner lists.
+
+```rpl
+{ 1 2 A 42.2 [ 1 2 3 ]} « →STR » MAP
+@ Expecting { "1" "2" "A" "42.2" "[ 1 2 3 ]" }
+```
+
+Unlike on HP calculators, `Map` does not apply recursively to inner lists by default.
 
 ```rpl
 { 1 2 { 3 4 } } « →STR » MAP
+@ Expecting { "1" "2" "{ 3 4 }" }
+```
+
+This can be changed by setting `ListRecursionDepth` to `0`.
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 { 3 4 } }  « →STR » MAP
 @ Expecting { "1" "2" { "3" "4" } }
+```
+
+`Map` can also be constrained to a given depth.
 
+```rpl
+2 ListRecursionDepth
+{ 1 2 { 3 { 4 { 5 } } } }  « →STR » MAP
+@ Expecting { "1" "2" { "3" "{ 4 { 5 } }" } }
+'ListRecursionDepth' Purge
 ```
 
 ## Reduce
@@ -12617,6 +12642,22 @@ operation to all elements.
 
 `{ A B ... }` `F` ▶ `F(F(A, B), ...)`
 
+For example, to sum all the elements in a list as text, one can use:
+
+```rpl
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12{ Hello World }"
+```
+
+Reduce obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ X Y Z T 12 { Hello World } } « →STR + » REDUCE
+@ Expecting "XYZT12HelloWorld"
+'ListRecursionDepth' Purge
+```
+
 
 ## Filter
 
@@ -12626,6 +12667,22 @@ resulting list is built with all elements where the predicate is true.
 
 `{ A B ... }` `P` ▶ `{ A ... }` if `P(A)` is true and `P(B)` is false.
 
+For example, to filter all odd numbers in an array, one can use:
+
+```rpl
+[ 1 2 3 4 5 6 42 ] « 2 MOD 0 = » FILTER
+@ Expecting [ 2 4 6 42 ]
+```
+
+`Filter` obeys the `ListRecursionDepth` setting:
+
+```rpl
+0 ListRecursionDepth
+{ 1 2 3 4 { 5 6 { 42 } } } « 2 MOD 0 = » FILTER
+@ Expecting { 2 4 { 6 { 42 } } }
+'ListRecursionDepth' Purge
+```
+
 
 ## Get
 
@@ -15128,6 +15185,17 @@ from the HP implementations of RPL.
 
 The opposite setting is `TruthLogicForIntegers`.
 
+## ListRecursionDepth
+
+This setting selects the depth of recursion for `Map`, `Reduce` or `Filter`.
+By default, it is set to `1`, indicating that recursion only applies to the
+top-level of the list. This matches the way `Map`, `Reduce` and `Filter` work in
+most programming languages.
+
+A value larger than `1` can be used to recurse beyond the first level.
+On the HP50G, `Map` applies recursively to all levels. This can be achieved by
+setting `ListRecursionDepth` to `0`.
+
 
 # Evaluation settings
 

src/array.h

@@ -43,24 +43,24 @@ struct array : list
 {
     array(id type, gcbytes bytes, size_t len): list(type, bytes, len) {}
 
-    static array_g map(algebraic_fn fn, array_r x)
+    static array_g map(algebraic_fn fn, array_r x, size_t recurse = ~0U)
     {
-        return x->map(fn);
+        return x->map(fn, recurse);
     }
 
-    array_p map(algebraic_fn fn) const
+    array_p map(algebraic_fn fn, size_t recurse = ~0U) const
     {
-        return array_p(list::map(fn));
+        return array_p(list::map(fn, recurse));
     }
 
-    array_p map(arithmetic_fn fn, algebraic_r y) const
+    array_p map(arithmetic_fn fn, algebraic_r y, size_t recurse = ~0U) const
     {
-        return array_p(list::map(fn, y));
+        return array_p(list::map(fn, y, recurse));
     }
 
-    array_p map(algebraic_r x, arithmetic_fn fn) const
+    array_p map(algebraic_r x, arithmetic_fn fn, size_t recurse = ~0U) const
     {
-        return array_p(list::map(x, fn));
+        return array_p(list::map(x, fn, recurse));
     }
 
     // Append data

src/ids.tbl

@@ -1058,6 +1058,8 @@ FLAG(TVMPayAtBeginningOfPeriod, TVMPayAtEndOfPeriod)
 FLAG(TruthLogicForIntegers,     BitwiseLogicForIntegers)
 FLAG(LaxArrayResizing,          StrictArrayResizing)
 
+SETTING_BITS(ListRecursionDepth, uint, 16, 0U, 65535U,    1U)
+
 ALIAS(HardwareFloatingPoint,    "HFP")
 ALIAS(HardwareFloatingPoint,    "HardFP")
 ALIAS(SoftwareFloatingPoint,    "SFP")