From 78d71c70a8a477afc34478471b8a0822da81f50f Mon Sep 17 00:00:00 2001 From: Mateusz Gancarz Date: Fri, 22 May 2026 12:52:43 +0200 Subject: [PATCH] docs: update enumerate docs --- docs_src/dslx_reference.md | 2 +- docs_src/dslx_std.md | 17 +++++++++-------- docs_src/tutorials/crc32.md | 6 +++--- docs_src/tutorials/index.md | 2 +- docs_src/tutorials/prefix_scan.md | 13 ++++--------- 5 files changed, 18 insertions(+), 22 deletions(-) diff --git a/docs_src/dslx_reference.md b/docs_src/dslx_reference.md index c76c6817c2..4a51fb7587 100644 --- a/docs_src/dslx_reference.md +++ b/docs_src/dslx_reference.md @@ -1610,7 +1610,7 @@ ranging from 0 to 7 and the value at the index `e = x[i]`. ``` fn prefix_scan_eq(x: u32[8]) -> u3[8] { let (_, _, result) = - for ((i, e), (prior, count, result)) in enumerate(x) {... + for ((i, e), (prior, count, result)) in std::enumerate(x) {... ``` ### `for` Expression diff --git a/docs_src/dslx_std.md b/docs_src/dslx_std.md index 5b127573be..b525ec6cc3 100644 --- a/docs_src/dslx_std.md +++ b/docs_src/dslx_std.md @@ -312,14 +312,6 @@ Example usage: See also the [IR semantics for the `encode` op](./ir_semantics.md#encode). -### `enumerate` - -Decorates elements of an array with indices. Has the following signature: - -``` -fn enumerate(x: T[N]) -> (u32, T)[N] -``` - ### `one_hot` Converts a value to one-hot form. Has the following signature: @@ -1573,6 +1565,15 @@ fn test_distinct_with_invalid() { } ``` +### `std::enumerate` + +Takes an array and produces an array of `(index, value)` tuples, where index is +the position of each element in the input array. Has the following signature: + +```dslx-snippet +pub fn enumerate(x: T[N]) -> (u32, T)[N] +``` + ## Rounding functions: `import round` XLS provides rounding primitives that implement the rounding behavior defined by the [IEEE diff --git a/docs_src/tutorials/crc32.md b/docs_src/tutorials/crc32.md index a240bf884d..482f62b74f 100644 --- a/docs_src/tutorials/crc32.md +++ b/docs_src/tutorials/crc32.md @@ -25,9 +25,9 @@ A DSLX `for` loop has the following structure: but it should be able to hold all possible loop index values). 3. An [iterable](../dslx_reference.md), - which can be a range expression `start..limit`, `enumerate()`, or an - array object. This dictates the number of iterations of the loop to - complete. + which can be a range expression `start..limit`, `std::enumerate()`, + or an array object. This dictates the number of iterations of the loop + to complete. 2. The loop body: this has the same general form as a DSLX function. Particularly noteworthy is that the loop body ends by stating the "return" value. In a `for` loop, this "return" value is either used as the input to diff --git a/docs_src/tutorials/index.md b/docs_src/tutorials/index.md index b8a4ef61eb..bae6ff6a65 100644 --- a/docs_src/tutorials/index.md +++ b/docs_src/tutorials/index.md @@ -16,7 +16,7 @@ design techniques. Here they are, grouped by topic: * [`for` expressions](crc32.md) : Explains how to understand and write looping constructs in DSLX. * [`enumerate` and `match` expressions](prefix_scan.md) : Explains how to use - `enumerate()` expressions to control loop iteration and how to use the + `std::enumerate()` expressions to control loop iteration and how to use the `match` pattern-matching expression for selecting between alternatives. * [What is a proc?](what_is_a_proc.md): A step-by-step introduction to procs, XLS's answer to how to write modules with state and explicit communication diff --git a/docs_src/tutorials/prefix_scan.md b/docs_src/tutorials/prefix_scan.md index aaa4115c7c..dc4a0e45b7 100644 --- a/docs_src/tutorials/prefix_scan.md +++ b/docs_src/tutorials/prefix_scan.md @@ -81,12 +81,12 @@ loop-carried values: ```dslx-snippet for ((i, elem), (prior, count, result)): ((u32, u32), (u32, u3, u3[8])) - in enumerate(x) { + in std::enumerate(x) { ``` -The iterable of this loop is `enumerate(x)`. On each iteration, this construct -delivers a tuple consisting of current index and current element. This is -represented as the tuple `(i, elem)` in the `for` construct. +The iterable of this loop is created by `std::enumerate(x)`. On each iteration, +this construct delivers a tuple consisting of current index and current element. +This is represented as the tuple `(i, elem)` in the `for` construct. The loop next specifies the accumulator, which is a 3-tuple consisting of the values named `prior`, `count`, and `result`. @@ -205,8 +205,3 @@ xls$ bazel run -c opt //xls/dslx:interpreter_main -- \ [ OK ] [===============] 2 test(s) ran; 0 failed; 0 skipped. ``` - -(Note that `--compare=none` is currently required because `enumerate` ranges are -not currently convertable to IR, otherwise running the DSLX interpreter would do -implicit comparison to IR interpreter -- see -[google/xls#164](https://github.com/google/xls/issues/164).)