refactor!: consistent inout order in borrow array (#2621)

BorrowArray::{borrow, is_borrowed} have had their return types switched
such that the array itself is first, matching the input signature. This
is more consistent with other ops that both take and return a type.


BREAKING CHANGE: BorrowArray::{borrow, is_borrowed} return types have
been swapped such that the array is first.

Author: ss2165

hugr-core/src/std_extensions/collections/borrow_array.rs

@@ -45,7 +45,7 @@ pub const BORROW_ARRAY_VALUENAME: TypeName = TypeName::new_inline("borrow_array"
 /// Reported unique name of the extension
 pub const EXTENSION_ID: ExtensionId = ExtensionId::new_unchecked("collections.borrow_arr");
 /// Extension version.
-pub const VERSION: semver::Version = semver::Version::new(0, 1, 2);
+pub const VERSION: semver::Version = semver::Version::new(0, 2, 0);
 
 /// A linear, unsafe, fixed-length collection of values.
 ///
@@ -153,7 +153,7 @@ impl BArrayUnsafeOpDef {
         match self {
             Self::borrow => PolyFuncTypeRV::new(
                 params,
-                FuncValueType::new(vec![array_ty.clone(), usize_t], vec![elem_ty_var, array_ty]),
+                FuncValueType::new(vec![array_ty.clone(), usize_t], vec![array_ty, elem_ty_var]),
             ),
             Self::r#return => PolyFuncTypeRV::new(
                 params,
@@ -172,7 +172,7 @@ impl BArrayUnsafeOpDef {
                 params,
                 FuncValueType::new(
                     vec![array_ty.clone(), usize_t],
-                    vec![crate::extension::prelude::bool_t(), array_ty],
+                    vec![array_ty, crate::extension::prelude::bool_t()],
                 ),
             ),
         }
@@ -644,6 +644,12 @@ pub trait BArrayOpBuilder: GenericArrayOpBuilder {
     /// * `input` - The wire representing the array.
     /// * `index` - The wire representing the index to get.
     ///
+    /// # Returns
+    ///
+    /// A tuple containing:
+    /// * The wire representing the updated array with the element marked as borrowed.
+    /// * The wire representing the borrowed element at the specified index.
+    ///
     /// # Errors
     ///
     /// Returns an error if building the operation fails.
@@ -655,10 +661,10 @@ pub trait BArrayOpBuilder: GenericArrayOpBuilder {
         index: Wire,
     ) -> Result<(Wire, Wire), BuildError> {
         let op = BArrayUnsafeOpDef::borrow.instantiate(&[size.into(), elem_ty.into()])?;
-        let [out, arr] = self
+        let [arr, out] = self
             .add_dataflow_op(op.to_extension_op().unwrap(), vec![input, index])?
             .outputs_arr();
-        Ok((out, arr))
+        Ok((arr, out))
     }
 
     /// Adds a borrow array put operation to the dataflow graph.
@@ -746,8 +752,8 @@ pub trait BArrayOpBuilder: GenericArrayOpBuilder {
     /// # Returns
     ///
     /// A tuple containing:
-    /// * The wire representing the boolean result (true if borrowed).
     /// * The wire representing the updated array.
+    /// * The wire representing the boolean result (true if borrowed).
     fn add_is_borrowed(
         &mut self,
         elem_ty: Type,
@@ -756,10 +762,10 @@ pub trait BArrayOpBuilder: GenericArrayOpBuilder {
         index: Wire,
     ) -> Result<(Wire, Wire), BuildError> {
         let op = BArrayUnsafeOpDef::is_borrowed.instantiate(&[size.into(), elem_ty.into()])?;
-        let [is_borrowed, arr] = self
+        let [arr, is_borrowed] = self
             .add_dataflow_op(op.to_extension_op().unwrap(), vec![input, index])?
             .outputs_arr();
-        Ok((is_borrowed, arr))
+        Ok((arr, is_borrowed))
     }
 }
 
@@ -799,7 +805,7 @@ mod test {
             let idx1 = builder.add_load_value(ConstUsize::new(11));
             let idx2 = builder.add_load_value(ConstUsize::new(11));
             let [arr] = builder.input_wires_arr();
-            let (el, arr_with_take) = builder
+            let (arr_with_take, el) = builder
                 .add_borrow_array_borrow(elem_ty.clone(), size, arr, idx1)
                 .unwrap();
             let arr_with_put = builder
@@ -819,7 +825,7 @@ mod test {
                 DFGBuilder::new(Signature::new(vec![arr_ty.clone()], vec![qb_t()])).unwrap();
             let idx = builder.add_load_value(ConstUsize::new(0));
             let [arr] = builder.input_wires_arr();
-            let (el, arr_with_borrowed) = builder
+            let (arr_with_borrowed, el) = builder
                 .add_borrow_array_borrow(elem_ty.clone(), size, arr, idx)
                 .unwrap();
             builder
@@ -857,10 +863,10 @@ mod test {
         let idx = builder.add_load_value(ConstUsize::new(2));
         let [arr] = builder.input_wires_arr();
         // Borrow the element at index 2
-        let (qb, arr_with_borrowed) = builder
+        let (arr_with_borrowed, qb) = builder
             .add_borrow_array_borrow(elem_ty.clone(), size, arr, idx)
             .unwrap();
-        let (_is_borrowed, arr_after_check) = builder
+        let (arr_after_check, _is_borrowed) = builder
             .add_is_borrowed(elem_ty.clone(), size, arr_with_borrowed, idx)
             .unwrap();
         builder

hugr-llvm/src/extension/collections/borrow_array.rs

@@ -1579,7 +1579,7 @@ pub fn emit_barray_unsafe_op<'c, H: HugrView<Node = Node>>(
             let elem_addr =
                 unsafe { builder.build_in_bounds_gep(elems_ptr, &[offset_index_v], "")? };
             let elem_v = builder.build_load(elem_addr, "")?;
-            outputs.finish(builder, [elem_v, array_v])
+            outputs.finish(builder, [array_v, elem_v])
         }
         BArrayUnsafeOpDef::r#return => {
             let [array_v, index_v, elem_v] = inputs
@@ -1631,7 +1631,7 @@ pub fn emit_barray_unsafe_op<'c, H: HugrView<Node = Node>>(
             let offset_index_v = ctx.builder().build_int_add(index_v, offset, "")?;
             // let bit = build_is_borrowed_check(ctx, mask_ptr, offset_index_v)?;
             let bit = build_is_borrowed_bit(ctx, mask_ptr, offset_index_v)?;
-            outputs.finish(ctx.builder(), [bit.into(), array_v])
+            outputs.finish(ctx.builder(), [array_v, bit.into()])
         }
         _ => todo!(),
     }
@@ -2555,7 +2555,7 @@ mod test {
                 let mut r = builder.add_load_value(ConstInt::new_u(6, 0).unwrap());
                 for &i in indices {
                     let i = builder.add_load_value(ConstUsize::new(i));
-                    let (val, arr) = builder
+                    let (arr, val) = builder
                         .add_borrow_array_borrow(int_ty.clone(), size, array, i)
                         .unwrap();
                     r = builder.add_iadd(6, r, val).unwrap();
@@ -2570,7 +2570,7 @@ mod test {
                 }
                 for &i in indices {
                     let i = builder.add_load_value(ConstUsize::new(i));
-                    let (val, arr) = builder
+                    let (arr, val) = builder
                         .add_borrow_array_borrow(int_ty.clone(), size, array, i)
                         .unwrap();
                     r = builder.add_iadd(6, r, val).unwrap();
@@ -2624,7 +2624,7 @@ mod test {
                 let mut r = builder.add_load_value(ConstInt::new_u(6, 0).unwrap());
                 for i in 0..size {
                     let i = builder.add_load_value(ConstUsize::new(i));
-                    let (val, arr) = builder
+                    let (arr, val) = builder
                         .add_borrow_array_borrow(int_ty.clone(), size, array, i)
                         .unwrap();
                     r = builder.add_iadd(6, r, val).unwrap();
@@ -2729,7 +2729,7 @@ mod test {
                 let mut r = builder.add_load_value(ConstInt::new_u(6, 0).unwrap());
                 for i in 0..size {
                     let i = builder.add_load_value(ConstUsize::new(i));
-                    let (val, arr) = builder
+                    let (arr, val) = builder
                         .add_borrow_array_borrow(int_ty.clone(), size, barray, i)
                         .unwrap();
                     r = builder.add_iadd(6, r, val).unwrap();
@@ -2786,13 +2786,13 @@ mod test {
                 array = builder
                     .add_borrow_array_borrow(int_ty.clone(), size, array, i1)
                     .unwrap()
-                    .1;
+                    .0;
                 array = build_pops(&mut builder, int_ty.clone(), size, array, num_pops);
                 size -= num_pops;
                 array = builder
                     .add_borrow_array_borrow(int_ty.clone(), size, array, i2)
                     .unwrap()
-                    .1;
+                    .0;
                 builder
                     .add_borrow_array_discard(int_ty.clone(), size, array)
                     .unwrap();
@@ -2951,7 +2951,7 @@ mod test {
                 );
                 let barray = builder.add_load_value(barray);
                 let idx = builder.add_load_value(ConstUsize::new(0));
-                let (_, barray) = builder
+                let (barray, _) = builder
                     .add_borrow_array_borrow(int_ty.clone(), size, barray, idx)
                     .unwrap();
                 let array = builder
@@ -2995,7 +2995,7 @@ mod test {
                 );
                 let barray = builder.add_load_value(barray);
                 let idx1 = builder.add_load_value(ConstUsize::new(1));
-                let (_, barray) = builder
+                let (barray, _) = builder
                     .add_borrow_array_borrow(int_ty.clone(), size, barray, idx1)
                     .unwrap();
 
@@ -3004,7 +3004,7 @@ mod test {
                     [idx0, idx1]
                         .iter()
                         .fold((barray, Vec::new()), |(arr, mut bools), idx| {
-                            let (b, arr) = builder
+                            let (arr, b) = builder
                                 .add_is_borrowed(int_ty.clone(), size, arr, *idx)
                                 .unwrap();
                             bools.push(b);

hugr-py/src/hugr/std/_json_defs/collections/borrow_arr.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.2",
+  "version": "0.2.0",
   "name": "collections.borrow_arr",
   "types": {
     "borrow_array": {
@@ -69,11 +69,6 @@
             }
           ],
           "output": [
-            {
-              "t": "V",
-              "i": 1,
-              "b": "A"
-            },
             {
               "t": "Opaque",
               "extension": "collections.borrow_arr",
@@ -97,6 +92,11 @@
                 }
               ],
               "bound": "A"
+            },
+            {
+              "t": "V",
+              "i": 1,
+              "b": "A"
             }
           ]
         }
@@ -539,11 +539,6 @@
             }
           ],
           "output": [
-            {
-              "t": "Sum",
-              "s": "Unit",
-              "size": 2
-            },
             {
               "t": "Opaque",
               "extension": "collections.borrow_arr",
@@ -567,6 +562,11 @@
                 }
               ],
               "bound": "A"
+            },
+            {
+              "t": "Sum",
+              "s": "Unit",
+              "size": 2
             }
           ]
         }

specification/std_extensions/collections/borrow_arr.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.2",
+  "version": "0.2.0",
   "name": "collections.borrow_arr",
   "types": {
     "borrow_array": {
@@ -69,11 +69,6 @@
             }
           ],
           "output": [
-            {
-              "t": "V",
-              "i": 1,
-              "b": "A"
-            },
             {
               "t": "Opaque",
               "extension": "collections.borrow_arr",
@@ -97,6 +92,11 @@
                 }
               ],
               "bound": "A"
+            },
+            {
+              "t": "V",
+              "i": 1,
+              "b": "A"
             }
           ]
         }
@@ -539,11 +539,6 @@
             }
           ],
           "output": [
-            {
-              "t": "Sum",
-              "s": "Unit",
-              "size": 2
-            },
             {
               "t": "Opaque",
               "extension": "collections.borrow_arr",
@@ -567,6 +562,11 @@
                 }
               ],
               "bound": "A"
+            },
+            {
+              "t": "Sum",
+              "s": "Unit",
+              "size": 2
             }
           ]
         }