feat(builtin): add clamped_view for FixedArray/ReadOnlyArray

Completes the total view variant across the whole family. `FixedArray` mirrors
`Array::clamped_view` through
`unsafe_cast_fixedarray_to_uninitializedarray`; `ReadOnlyArray` delegates to
`FixedArray::clamped_view` via `unsafe_reinterpret_to_fixed_array()`, the same
way its existing `view` and `get_view` delegate.

Contract is unchanged: both offsets are clamped independently into
`[0, length()]`, an inverted range yields an empty view at the clamped `start`,
and the result aliases the backing storage.

Codex CLI review: "No blocking issues in the uncommitted diff. `ReadOnlyArray`
correctly forwards `start` in both arms. Omitting `end` produces exactly the
same bounds as explicitly passing `length()` [...] Clamping guarantees
`0 <= lo <= len` and `0 <= count <= len - lo`; subtraction cannot overflow."

It also spotted a real gap: with the `end=None` arm exercised only at starts 0,
-5 and 100, a `start * 2` mutation there survived the suite. The added test
"clamped_view with `end` omitted forwards `start` unchanged" compares the
omitted-`end` result against an explicit `end=5` across every start in -1..=6,
including `start_offset()`; that mutation now fails 1 test.

Signed-off-by: Codex CLI <codex@openai.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F4N5Hc1TYuJW5oRDTY19Wf

Author: bobzhang

builtin/arrayview.mbt

@@ -636,6 +636,44 @@ pub fn[T] FixedArray::get_view(
   )
 }
 
+///|
+/// Creates a view of a portion of the fixed array, clamping the requested
+/// range instead of rejecting it. Same contract as `Array::clamped_view`.
+///
+/// Example:
+///
+/// ```mbt check
+/// test {
+///   let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
+///   debug_inspect(
+///     arr.clamped_view(start=3, end=10),
+///     content=(
+///       #|<ArrayView: [4, 5]>
+///     ),
+///   )
+///   debug_inspect(
+///     arr.clamped_view(start=4, end=1),
+///     content=(
+///       #|<ArrayView: []>
+///     ),
+///   )
+/// }
+/// ```
+pub fn[T] FixedArray::clamped_view(
+  self : FixedArray[T],
+  start? : Int = 0,
+  end? : Int,
+) -> ArrayView[T] {
+  let len = self.length()
+  let lo = clamp_offset(start, len)
+  let hi = match end {
+    None => len
+    Some(end) => clamp_offset(end, len)
+  }
+  let count = if hi > lo { hi - lo } else { 0 }
+  ArrayView::make(unsafe_cast_fixedarray_to_uninitializedarray(self), lo, count)
+}
+
 ///|
 /// Return an iterator over suffix views of this array view.
 ///

builtin/clamped_view_test.mbt

@@ -203,3 +203,115 @@ test "clamped_view saturates at the extremes of Int" {
   inspect(bv.clamped_view(start=lo, end=hi) == bv, content="true")
   inspect(bv.clamped_view(start=hi, end=lo).start_offset(), content="4")
 }
+
+///|
+test "FixedArray::clamped_view clamps out-of-range and inverted offsets" {
+  let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
+  json_inspect(arr.clamped_view().to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=1, end=4).to_owned(), content=[2, 3, 4])
+  json_inspect(arr.clamped_view(end=100).to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=-5).to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=100).to_owned(), content=[])
+  json_inspect(arr.clamped_view(start=4, end=1).to_owned(), content=[])
+  json_inspect(arr.clamped_view(start=-9, end=-3).to_owned(), content=[])
+  json_inspect(
+    arr.clamped_view(start=@int.MIN_VALUE, end=@int.MAX_VALUE).to_owned(),
+    content=[1, 2, 3, 4, 5],
+  )
+  json_inspect(
+    arr.clamped_view(start=@int.MAX_VALUE, end=@int.MIN_VALUE).to_owned(),
+    content=[],
+  )
+  json_inspect(([] : FixedArray[Int]).clamped_view(end=10).to_owned(), content=[])
+  // empty results sit at the clamped start
+  inspect(arr.clamped_view(start=4, end=1).start_offset(), content="4")
+  inspect(arr.clamped_view(start=100).start_offset(), content="5")
+  inspect(arr.clamped_view(start=-9, end=-3).start_offset(), content="0")
+}
+
+///|
+test "FixedArray::clamped_view aliases the backing array" {
+  let arr : FixedArray[Int] = [1, 2, 3, 4, 5]
+  let v = arr.clamped_view(start=1, end=100)
+  arr[1] = 20
+  json_inspect(v.to_owned(), content=[20, 3, 4, 5])
+}
+
+///|
+test "ReadOnlyArray::clamped_view clamps out-of-range and inverted offsets" {
+  let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
+  json_inspect(arr.clamped_view().to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=1, end=4).to_owned(), content=[2, 3, 4])
+  json_inspect(arr.clamped_view(end=100).to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=-5).to_owned(), content=[1, 2, 3, 4, 5])
+  json_inspect(arr.clamped_view(start=100).to_owned(), content=[])
+  json_inspect(arr.clamped_view(start=4, end=1).to_owned(), content=[])
+  json_inspect(arr.clamped_view(start=-9, end=-3).to_owned(), content=[])
+  json_inspect(
+    arr.clamped_view(start=@int.MIN_VALUE, end=@int.MAX_VALUE).to_owned(),
+    content=[1, 2, 3, 4, 5],
+  )
+  json_inspect(
+    arr.clamped_view(start=@int.MAX_VALUE, end=@int.MIN_VALUE).to_owned(),
+    content=[],
+  )
+  json_inspect(([] : ReadOnlyArray[Int]).clamped_view(end=10).to_owned(), content=[])
+  // the `end=None` arm delegates separately; it must clamp `start` too
+  inspect(arr.clamped_view(start=100).start_offset(), content="5")
+  inspect(arr.clamped_view(start=4, end=1).start_offset(), content="4")
+}
+
+///|
+test "clamped_view with `end` omitted forwards `start` unchanged" {
+  // `ReadOnlyArray::clamped_view` handles `end=None` in a separate arm, so an
+  // interior start is what catches a mangled `start` there: 0 / negative /
+  // past-the-end starts all survive a doubled `start`.
+  let ro : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
+  let fixed : FixedArray[Int] = [1, 2, 3, 4, 5]
+  json_inspect(ro.clamped_view(start=1).to_owned(), content=[2, 3, 4, 5])
+  json_inspect(fixed.clamped_view(start=1).to_owned(), content=[2, 3, 4, 5])
+  for start in -1..<=6 {
+    // omitting `end` must equal passing the full length explicitly
+    let ro_omitted = ro.clamped_view(start~)
+    let ro_explicit = ro.clamped_view(start~, end=5)
+    json_inspect(
+      ro_omitted.to_owned(),
+      content=ro_explicit.to_owned().to_json(),
+    )
+    inspect(
+      ro_omitted.start_offset() == ro_explicit.start_offset(),
+      content="true",
+    )
+    let fixed_omitted = fixed.clamped_view(start~)
+    let fixed_explicit = fixed.clamped_view(start~, end=5)
+    json_inspect(
+      fixed_omitted.to_owned(),
+      content=fixed_explicit.to_owned().to_json(),
+    )
+    inspect(
+      fixed_omitted.start_offset() == fixed_explicit.start_offset(),
+      content="true",
+    )
+  }
+}
+
+///|
+test "FixedArray/ReadOnlyArray clamped_view agree with get_view" {
+  let fixed : FixedArray[Int] = [1, 2, 3, 4, 5]
+  let ro : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
+  for start in -1..<=6 {
+    for end in -1..<=6 {
+      // get_view rejects out-of-range and inverted ranges; clamped_view
+      // answers the same on every range get_view accepts.
+      guard fixed.get_view(start~, end~) is Some(v) else { continue }
+      json_inspect(
+        fixed.clamped_view(start~, end~).to_owned(),
+        content=v.to_owned().to_json(),
+      )
+      json_inspect(
+        ro.clamped_view(start~, end~).to_owned(),
+        content=v.to_owned().to_json(),
+      )
+    }
+  }
+}

builtin/pkg.generated.mbti

@@ -998,6 +998,7 @@ pub fn FixedArray::blit_from_bytes(Self[Byte], Int, Bytes, Int, Int) -> Unit
 pub fn FixedArray::blit_from_bytesview(Self[Byte], Int, BytesView) -> Unit
 pub fn FixedArray::blit_from_string(Self[Byte], Int, String, Int, Int) -> Unit
 pub fn[A] FixedArray::blit_to(Self[A], Self[A], len~ : Int, src_offset? : Int, dst_offset? : Int) -> Unit
+pub fn[T] FixedArray::clamped_view(Self[T], start? : Int, end? : Int) -> ArrayView[T]
 pub fn[T : Compare] FixedArray::compare(Self[T], Self[T]) -> Int
 pub fn[T : Eq] FixedArray::contains(Self[T], T) -> Bool
 #alias(clone, deprecated)
@@ -1072,6 +1073,7 @@ pub fn[T : Compare] ReadOnlyArray::binary_search(Self[T], T) -> Result[Int, Int]
 pub fn[T] ReadOnlyArray::binary_search_by(Self[T], (T) -> Int raise?) -> Result[Int, Int] raise?
 pub fn[T] ReadOnlyArray::chunk_by(Self[T], (T, T) -> Bool raise?) -> Array[ArrayView[T]] raise?
 pub fn[T] ReadOnlyArray::chunks(Self[T], Int) -> Array[ArrayView[T]]
+pub fn[T] ReadOnlyArray::clamped_view(Self[T], start? : Int, end? : Int) -> ArrayView[T]
 pub fn[T : Compare] ReadOnlyArray::compare(Self[T], Self[T]) -> Int
 pub fn[T : Eq] ReadOnlyArray::contains(Self[T], T) -> Bool
 pub fn[T] ReadOnlyArray::each(Self[T], (T) -> Unit raise?) -> Unit raise?

builtin/readonlyarray.mbt

@@ -913,6 +913,40 @@ pub fn[T] ReadOnlyArray::get_view(
   }
 }
 
+///|
+/// Creates a view of a subarray, clamping the requested range instead of
+/// rejecting it. Same contract as `Array::clamped_view`.
+///
+/// # Example
+/// ```mbt check
+/// test {
+///   let arr : ReadOnlyArray[Int] = [1, 2, 3, 4, 5]
+///   debug_inspect(
+///     arr.clamped_view(start=3, end=10),
+///     content=(
+///       #|<ArrayView: [4, 5]>
+///     ),
+///   )
+///   debug_inspect(
+///     arr.clamped_view(start=4, end=1),
+///     content=(
+///       #|<ArrayView: []>
+///     ),
+///   )
+/// }
+/// ```
+pub fn[T] ReadOnlyArray::clamped_view(
+  self : ReadOnlyArray[T],
+  start? : Int = 0,
+  end? : Int,
+) -> ArrayView[T] {
+  let fixed = self.unsafe_reinterpret_to_fixed_array()
+  match end {
+    None => fixed.clamped_view(start~)
+    Some(end) => fixed.clamped_view(start~, end~)
+  }
+}
+
 ///|
 /// Joins the string-renderable elements with a separator.
 ///