docs: Add collection extension ops to the spec by tatiana-s · Pull Request #2767 · Quantinuum/hugr

tatiana-s · 2025-12-18T13:47:54Z

codecov · 2025-12-18T13:52:41Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.69%. Comparing base (afc7845) to head (8b7ab12).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2767   +/-   ##
=======================================
  Coverage   83.69%   83.69%           
=======================================
  Files         261      261           
  Lines       52561    52561           
  Branches    47307    47307           
=======================================
  Hits        43991    43991           
  Misses       6183     6183           
  Partials     2387     2387

Flag	Coverage Δ
python	`88.84% <ø> (ø)`
rust	`83.12% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cqc-alec · 2026-01-06T10:40:19Z

specification/hugr.md

+
+There are multiple extensions defining types, values and operations to work with collections of data:
+
+- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.


Suggested change

- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.

- `collections.array`: The standard linear and fixed-length array type, parametrized by length and element type.

For consistency.

cqc-alec · 2026-01-06T10:41:07Z

specification/hugr.md

+There are multiple extensions defining types, values and operations to work with collections of data:
+
+- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.
+- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parameterised by length and element type.


Suggested change

- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parameterised by length and element type.

- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parametrized by length and element type.

cqc-alec · 2026-01-06T10:41:46Z

specification/hugr.md

+
+- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.
+- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parameterised by length and element type.
+- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parameterised only by element type.


Suggested change

- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parameterised only by element type.

- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parametrized only by element type.

cqc-alec · 2026-01-06T10:42:57Z

specification/hugr.md

+- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.
+- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parameterised by length and element type.
+- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parameterised only by element type.
+- `collections.list`: A variable-length list type, paramterised by element type.


Suggested change

- `collections.list`: A variable-length list type, paramterised by element type.

- `collections.list`: A variable-length list type, parametrized by element type.

cqc-alec · 2026-01-06T10:44:45Z

specification/hugr.md

+- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parameterised only by element type.
+- `collections.list`: A variable-length list type, paramterised by element type.
+
+The array and borrow array extensions are implemented using a generic `ArrayKind` trait that allows different array implementations to share parts of their implementation.


This is an implementation detail so I don't think it should go in the spec document.

cqc-alec · 2026-01-06T11:06:47Z

specification/hugr.md

+| `scan`          | `array<SIZE, elemty_src>`,  `(elemty_src, list<acc_ty> -> elemty_dest, list<acc_ty)`, `list<acc_ty>` | `array<SIZE, elemty_dest>`, `list<acc_ty>`  | A combination of map and foldl. Apply a function to each element of the array with an accumulator that is passed through from start to finish. Return the resulting array and the final state of the accumulator. |
+
+
+#### `collections.borrow_arr`


I wonder why we decided on this abbreviated name, which seems out of keeping with static_array.

It was because extensions names are limited in length (they are stored in a SmolStr)

cqc-alec · 2026-01-06T11:08:01Z

specification/hugr.md

+| Operation    | Inputs       | Outputs      | Meaning      |
+|--------------|--------------|--------------|--------------|
+| `get`        | `static_array<elemty>`, `usize` | `option<elemty>`| Get the element at the given index. Return none if the index is out of bounds. |
+| `len`        | `static_array<elemty>` | `usize` | Get sthe length of the array. |


cqc-alec · 2026-01-06T11:09:32Z

specification/hugr.md

+
+| Operation | Inputs | Outputs | Meaning |
+|-----------|--------|---------|---------|
+| `pop`     | `list<elemty>` | `list<elemty>`, `option<elemty>` | Pop from the end of list. Return an optional value. |


cqc-alec · 2026-01-06T11:10:50Z

specification/hugr.md

+| Operation | Inputs | Outputs | Meaning |
+|-----------|--------|---------|---------|
+| `pop`     | `list<elemty>` | `list<elemty>`, `option<elemty>` | Pop from the end of list. Return an optional value. |
+| `push`    | `list<elemty>`, `elemty` | `list<elemty>` | Push to end of list. Return the new list. |


cqc-alec · 2026-01-06T11:11:27Z

specification/hugr.md

+|-----------|--------|---------|---------|
+| `pop`     | `list<elemty>` | `list<elemty>`, `option<elemty>` | Pop from the end of list. Return an optional value. |
+| `push`    | `list<elemty>`, `elemty` | `list<elemty>` | Push to end of list. Return the new list. |
+| `get`     | `list<elemty>`, `usize` | `option<elemty>` | Lookup an element in a list by index. |


cqc-alec

Thanks!

## 🤖 New release * `hugr-model`: 0.25.2 -> 0.25.3 (✓ API compatible changes) * `hugr-core`: 0.25.2 -> 0.25.3 (✓ API compatible changes) * `hugr-llvm`: 0.25.2 -> 0.25.3 (✓ API compatible changes) * `hugr-passes`: 0.25.2 -> 0.25.3 (✓ API compatible changes) * `hugr-persistent`: 0.4.2 -> 0.4.3 (✓ API compatible changes) * `hugr`: 0.25.2 -> 0.25.3 (✓ API compatible changes) * `hugr-cli`: 0.25.2 -> 0.25.3 (✓ API compatible changes) <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.25.0](hugr-model-v0.24.3...hugr-model-v0.25.0) - 2025-12-22 ### Bug Fixes - *(model)* avoid non abi-compatible pyo3 calls ([#2679](#2679)) ### New Features - [**breaking**] Upgrade pyo3 dependency to 0.27 ([#2736](#2736)) ### Refactor - Direct import of model representation to Python ([#2683](#2683)) </blockquote> ## `hugr-core` <blockquote> ## [0.25.3](hugr-core-v0.25.2...hugr-core-v0.25.3) - 2026-01-09 ### Bug Fixes - more nondeterminism in linking ([#2792](#2792)) ### Documentation - Add collection extension ops to the spec ([#2767](#2767)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.25.0](hugr-llvm-v0.24.3...hugr-llvm-v0.25.0) - 2025-12-22 ### New Features - *(llvm)* [**breaking**] upgrade to inkwell 0.7 ([#2695](#2695)) ### Refactor - Deprecate Value::Function and inline_constant_functions ([#2770](#2770)) </blockquote> ## `hugr-passes` <blockquote> ## [0.25.3](hugr-passes-v0.25.2...hugr-passes-v0.25.3) - 2026-01-09 ### Bug Fixes - *(hugr-passes)* Recursive replacement on NodeTemplate::LinkedHugr ([#2800](#2800)) ### Refactor - *(ReplaceTypes)* [tiny] correct computation of containing_func ([#2807](#2807)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.4.0](hugr-persistent-v0.3.4...hugr-persistent-v0.4.0) - 2025-12-22 ### New Features - [**breaking**] Remove `RootCheckable` ([#2704](#2704)) - [**breaking**] Bump MSRV to Rust 1.89 ([#2747](#2747)) - [**breaking**] Type-safe access for node metadata ([#2755](#2755)) ### Refactor - [**breaking**] Remove multiple deprecated definitions ([#2751](#2751)) </blockquote> ## `hugr` <blockquote> ## [0.25.3](hugr-v0.25.2...hugr-v0.25.3) - 2026-01-09 ### Bug Fixes - *(hugr-passes)* Recursive replacement on NodeTemplate::LinkedHugr ([#2800](#2800)) - more nondeterminism in linking ([#2792](#2792)) ### Documentation - Add collection extension ops to the spec ([#2767](#2767)) ### Refactor - *(ReplaceTypes)* [tiny] correct computation of containing_func ([#2807](#2807)) </blockquote> ## `hugr-cli` <blockquote> ## [0.25.0](hugr-cli-v0.24.3...hugr-cli-v0.25.0) - 2025-12-22 ### New Features - *(cli, python)* programmatic interface to cli with python bindings ([#2677](#2677)) - return description output to python on error ([#2681](#2681)) - [**breaking**] Type-safe access for node metadata ([#2755](#2755)) - [**breaking**] GeneratorDesc metadata definition ([#2759](#2759)) ### Refactor - [**breaking**] move envelope reading to dedicated module with dedicated errors ([#2689](#2689)) - *(cli)* [**breaking**] remove deprecated hugr_json handling ([#2690](#2690)) - [**breaking**] Remove multiple deprecated definitions ([#2751](#2751)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

## 🤖 New release * `hugr-model`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr-core`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr-llvm`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr-passes`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr-cli`: 0.25.3 -> 0.25.4 (✓ API compatible changes) * `hugr-persistent`: 0.4.3 -> 0.4.4 <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.25.0](hugr-model-v0.24.3...hugr-model-v0.25.0) - 2025-12-22 ### Bug Fixes - *(model)* avoid non abi-compatible pyo3 calls ([#2679](#2679)) ### New Features - [**breaking**] Upgrade pyo3 dependency to 0.27 ([#2736](#2736)) ### Refactor - Direct import of model representation to Python ([#2683](#2683)) </blockquote> ## `hugr-core` <blockquote> ## [0.25.3](hugr-core-v0.25.2...hugr-core-v0.25.3) - 2026-01-09 ### Bug Fixes - more nondeterminism in linking ([#2792](#2792)) ### Documentation - Add collection extension ops to the spec ([#2767](#2767)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.25.0](hugr-llvm-v0.24.3...hugr-llvm-v0.25.0) - 2025-12-22 ### New Features - *(llvm)* [**breaking**] upgrade to inkwell 0.7 ([#2695](#2695)) ### Refactor - Deprecate Value::Function and inline_constant_functions ([#2770](#2770)) </blockquote> ## `hugr-passes` <blockquote> ## [0.25.4](hugr-passes-v0.25.3...hugr-passes-v0.25.4) - 2026-01-14 ### Bug Fixes - UnpackTuple error on disconnected outputs ([#2813](#2813)) </blockquote> ## `hugr` <blockquote> ## [0.25.4](hugr-v0.25.3...hugr-v0.25.4) - 2026-01-14 ### Bug Fixes - UnpackTuple error on disconnected outputs ([#2813](#2813)) </blockquote> ## `hugr-cli` <blockquote> ## [0.25.0](hugr-cli-v0.24.3...hugr-cli-v0.25.0) - 2025-12-22 ### New Features - *(cli, python)* programmatic interface to cli with python bindings ([#2677](#2677)) - return description output to python on error ([#2681](#2681)) - [**breaking**] Type-safe access for node metadata ([#2755](#2755)) - [**breaking**] GeneratorDesc metadata definition ([#2759](#2759)) ### Refactor - [**breaking**] move envelope reading to dedicated module with dedicated errors ([#2689](#2689)) - *(cli)* [**breaking**] remove deprecated hugr_json handling ([#2690](#2690)) - [**breaking**] Remove multiple deprecated definitions ([#2751](#2751)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.4.0](hugr-persistent-v0.3.4...hugr-persistent-v0.4.0) - 2025-12-22 ### New Features - [**breaking**] Remove `RootCheckable` ([#2704](#2704)) - [**breaking**] Bump MSRV to Rust 1.89 ([#2747](#2747)) - [**breaking**] Type-safe access for node metadata ([#2755](#2755)) ### Refactor - [**breaking**] Remove multiple deprecated definitions ([#2751](#2751)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

Add collection extension ops to spec

e2f6ee6

tatiana-s requested a review from a team as a code owner December 18, 2025 13:47

tatiana-s requested a review from doug-q December 18, 2025 13:47

Merge remote-tracking branch 'origin/main' into ts/array-spec

6cb7a93

tatiana-s requested review from cqc-alec and removed request for doug-q January 6, 2026 10:19

cqc-alec reviewed Jan 6, 2026

View reviewed changes

tatiana-s added 2 commits January 6, 2026 13:54

Change based on comments

5e20c53

Merge remote-tracking branch 'origin/main' into ts/array-spec

8b7ab12

tatiana-s requested a review from cqc-alec January 6, 2026 16:03

cqc-alec approved these changes Jan 6, 2026

View reviewed changes

tatiana-s added this pull request to the merge queue Jan 7, 2026

Merged via the queue into main with commit 7b5add8 Jan 7, 2026
30 checks passed

tatiana-s deleted the ts/array-spec branch January 7, 2026 09:09

hugrbot mentioned this pull request Jan 7, 2026

chore: release #2798

Merged

hugrbot mentioned this pull request Jan 13, 2026

chore: release #2812

Merged

hugrbot mentioned this pull request Jan 15, 2026

chore: release #2815

Closed


		There are multiple extensions defining types, values and operations to work with collections of data:

		- `collections.array`: The standard linear and fixed-length array type, parameterised by length and element type.

	- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parameterised by length and element type.
	- `collections.borrow_arr`: A linear and fixed-length array type that provides additional unsafe operations for borrowing elements from the array, parametrized by length and element type.

	- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parameterised only by element type.
	- `collections.static_array`: An array type for modeling globally available constant arrays of copyable values, parametrized only by element type.

	- `collections.list`: A variable-length list type, paramterised by element type.
	- `collections.list`: A variable-length list type, parametrized by element type.

		\| `scan` \| `array<SIZE, elemty_src>`, `(elemty_src, list<acc_ty> -> elemty_dest, list<acc_ty)`, `list<acc_ty>` \| `array<SIZE, elemty_dest>`, `list<acc_ty>` \| A combination of map and foldl. Apply a function to each element of the array with an accumulator that is passed through from start to finish. Return the resulting array and the final state of the accumulator. \|


		#### `collections.borrow_arr`

	\| `len` \| `static_array<elemty>` \| `usize` \| Get sthe length of the array. \|
	\| `len` \| `static_array<elemty>` \| `usize` \| Gets the length of the array. \|

	\| `pop` \| `list<elemty>` \| `list<elemty>`, `option<elemty>` \| Pop from the end of list. Return an optional value. \|
	\| `pop` \| `list<elemty>` \| `list<elemty>`, `option<elemty>` \| Pop from the end of a list. Return the new list and the popped value (or none if the list was empty). \|

	\| `push` \| `list<elemty>`, `elemty` \| `list<elemty>` \| Push to end of list. Return the new list. \|
	\| `push` \| `list<elemty>`, `elemty` \| `list<elemty>` \| Push to the end of a list. Return the new list. \|

	\| `get` \| `list<elemty>`, `usize` \| `option<elemty>` \| Lookup an element in a list by index. \|
	\| `get` \| `list<elemty>`, `usize` \| `option<elemty>` \| Look up an element in a list by index. \|

Conversation

tatiana-s commented Dec 18, 2025

Uh oh!

codecov bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tatiana-s Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cqc-alec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Dec 18, 2025 •

edited

Loading

tatiana-s Jan 6, 2026 •

edited

Loading