phpmlkit · CodeWithKyrian · Jun 6, 2026 · Jun 6, 2026
diff --git a/docs/guide/fundamentals/data-types.md b/docs/guide/fundamentals/data-types.md
@@ -117,6 +117,10 @@ $f32 = $float_arr->astype(DType::Float32);
 // Convert to bool (non-zero = true)
 $bool_arr = $float_arr->astype(DType::Bool);
 print_r($bool_arr->toArray());  // [true, true, true]
+
+// Or use cast() when you only want to copy if needed:
+$same = $float_arr->cast(DType::Float64);  // No copy, same instance
+$converted = $float_arr->cast(DType::Int32);  // Copy required, delegates to astype()
 ```
 
 ## Type Properties

diff --git a/docs/guide/fundamentals/views-vs-copies.md b/docs/guide/fundamentals/views-vs-copies.md
@@ -104,6 +104,7 @@ Copies are created by operations that **transform** or **compute** new data:
 |-----------------|---------------------|-------------------|
 | Math ops        | `$arr->multiply(2)` | New allocation    |
 | Type cast       | `$arr->astype()`     | New allocation    |
+| Conditional cast| `$arr->cast()`       | Same instance if dtype matches, copy otherwise |
 | Explicit copy   | `$arr->copy()`       | New allocation    |
 | Flatten         | `$arr->flatten()`    | New allocation    |
 
@@ -125,6 +126,8 @@ $result = $arr->matmul($b);       // COPY
 $arr = NDArray::array([1, 2, 3]);
 
 $converted = $arr->astype(DType::Int32);  // COPY
+$casted = $arr->cast(DType::Int32);        // COPY (dtype differs)
+$same = $arr->cast(DType::Int64);          // NO COPY (already Int64)
 ```
 
 ### Explicit Copy
@@ -512,6 +515,7 @@ function safeModify(NDArray $arr): NDArray {
 | `$arr->reshape([...])` | View* | Yes (if modified) |
 | `$arr->mergeaxes(0, 1)` | View | Yes (if modified) |
 | `$arr->astype(...)` | Copy | No |
+| `$arr->cast(...)` | Same instance or Copy | Yes if same dtype, No otherwise |
 | `$arr->add($b)` | Copy | No |
 | `$arr->set([0,0], 5)` | N/A | Yes |
 | `$view = $view->multiply(2)` | Copy | No (reassignment) |

diff --git a/src/Functions.php b/src/Functions.php
@@ -345,6 +345,19 @@ function astype(NDArray $a, DType $dtype): NDArray
         return $a->astype($dtype);
     }
 
+    /**
+     * Cast an array to a different dtype, returning the same instance when possible.
+     *
+     * Unlike {@see astype()} which always copies, this function returns the
+     * input array unchanged (zero-cost) when the dtype already matches.
+     *
+     * @see NDArray::cast()
+     */
+    function cast(NDArray $a, DType $dtype): NDArray
+    {
+        return $a->cast($dtype);
+    }
+
     // =============================================================================
     // HasMath — element-wise arithmetic, ufuncs, bitwise, clamp, min/max, softmax
     // =============================================================================

diff --git a/src/Traits/CreatesArrays.php b/src/Traits/CreatesArrays.php
@@ -842,6 +842,23 @@ public function astype(DType $dtype): self
         return new self($outHandle, new ArrayMetadata($this->shape()), $dtype);
     }
 
+    /**
+     * Cast the array to a different dtype, without copy when already the target type.
+     *
+     * Unlike {@see astype()} which always creates a new copy, this method
+     * returns the same array instance (zero-cost) when the current dtype
+     * already matches the requested one. Only when an actual type conversion
+     * is needed does it delegate to astype() and allocate new memory.
+     *
+     * @param DType $dtype Target data type
+     *
+     * @return self The array in the target dtype (may be the same instance)
+     */
+    public function cast(DType $dtype): self
+    {
+        return $this->dtype === $dtype ? $this : $this->astype($dtype);
+    }
+
     // =========================================================================
     // Private Helpers
     // =========================================================================