From 4c5394b367562ccca37f66ef64cb2b3978c0c283 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Thu, 25 Jun 2026 16:28:27 -0700
Subject: [PATCH] langref: make section for slice by length

---
 doc/langref.html.in               | 20 +++++++++++++++++++-
 doc/langref/slicing_by_length.zig | 12 ++++++++++++
 doc/langref/test_basic_slices.zig |  9 ---------
 3 files changed, 31 insertions(+), 10 deletions(-)
 create mode 100644 doc/langref/slicing_by_length.zig

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 92c4076322a1d5ac55f44288721a1407b8f98945..9315e9764d08e79202ea6325a292a2a6804740d5 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -1955,7 +1955,7 @@ or
       TODO talk about C ABI interop<br>
       TODO consider suggesting std.MultiArrayList
       </p>
-      {#see_also|@splat|@shuffle|@select|@reduce#}
+      {#see_also|@splat|@shuffle|@select|@reduce|Slicing by Length#}
 
       {#header_open|Relationship with Arrays#}
       <p>Vectors and {#link|Arrays#} each have a well-defined <strong>bit layout</strong>
@@ -2150,6 +2150,24 @@ or
 
       {#see_also|Pointers|for|Arrays#}
 
+      {#header_open|Slicing by Length#}
+      <p>Even though Zig only has syntax for slicing based on start and end indices, by slicing twice,
+      one can express a <strong>slice by length</strong> operation.</p>
+      <p>The pattern {#syntax#}[a .. a + b]{#endsyntax#} is always better expressed
+      {#syntax#}[a..][0..b]{#endsyntax#} because:</p>
+      <ul>
+        <li>Slices are represented in memory as a pointer and length. Despite
+        syntactically appearing as twice the work, it is actually one less
+        subtraction in machine code.</li>
+        <li>If {#syntax#}a{#endsyntax#} is known at runtime and
+        {#syntax#}b{#endsyntax#} is known at {#link|comptime#}, the former
+        results in a slice but the latter results in a single-item
+        {#link|pointer|Pointers#} to an {#link|array|Arrays#}, a generally more
+        safe type because the length is compile-time known.</li>
+      </ul>
+      {#code|slicing_by_length.zig#}
+      {#header_close#}
+
       {#header_open|Sentinel-Terminated Slices#}
       <p>
       The syntax {#syntax#}[:x]T{#endsyntax#} is a slice which has a runtime-known length
diff --git a/doc/langref/slicing_by_length.zig b/doc/langref/slicing_by_length.zig
new file mode 100644
index 0000000000000000000000000000000000000000..abb7d9394fd3978f694e9a58796a65926584e087
--- /dev/null
+++ b/doc/langref/slicing_by_length.zig
@@ -0,0 +1,12 @@
+const expectEqual = @import("std").testing.expectEqual;
+
+test "example" {
+    var array = [_]i32{ 1, 2, 3, 4 };
+    var runtime_start: usize = 1;
+    _ = &runtime_start;
+    const length = 2;
+    const array_ptr_len = array[runtime_start..][0..length];
+    try expectEqual(*[length]i32, @TypeOf(array_ptr_len));
+}
+
+// test
diff --git a/doc/langref/test_basic_slices.zig b/doc/langref/test_basic_slices.zig
index 28013148352eba7c5b9e6c0849e778c1ebc0b5ed..d627b7d0a6c1347ccebbf2f773de59630c91d063 100644
--- a/doc/langref/test_basic_slices.zig
+++ b/doc/langref/test_basic_slices.zig
@@ -21,15 +21,6 @@ test "basic slices" {
     const array_ptr = array[0..array.len];
     try expectEqual(*[array.len]i32, @TypeOf(array_ptr));
 
-    // You can perform a slice-by-length by slicing twice. This allows the compiler
-    // to perform some optimisations like recognising a comptime-known length when
-    // the start position is only known at runtime.
-    var runtime_start: usize = 1;
-    _ = &runtime_start;
-    const length = 2;
-    const array_ptr_len = array[runtime_start..][0..length];
-    try expectEqual(*[length]i32, @TypeOf(array_ptr_len));
-
     // Using the address-of operator on a slice gives a single-item pointer.
     try expectEqual(*i32, @TypeOf(&slice[0]));
     // Using the `ptr` field gives a many-item pointer.
-- 
2.54.0