range — Compute the span of array data as max - min, with MATLAB-compatible dimension and NaN controls.
range(X) returns the span (maximum minus minimum) of the elements in X. For arrays, it operates along the first non-singleton dimension unless you specify dim or 'all', and it follows MATLAB-compatible output-shape conventions.
Syntax
y = range(X)
y = range(X, dim)
y = range(X, vecdim)
y = range(X, "all")
y = range(X, nanflag)
y = range(X, dim_or_vecdim, nanflag)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | NumericArray | Yes | — | Input data. |
dim | IntegerScalar | No | — | Reduction dimension. |
vecdim | SizeArg | No | — | Vector of reduction dimensions. |
all_kw | StringScalar | No | "all" | Reduce over all elements. |
nanflag | StringScalar | No | "includenan" | NaN handling flag ('omitnan'|'includenan'). |
dim_or_vecdim | SizeArg | No | — | Dimension selector. |
Returns
| Name | Type | Description |
|---|---|---|
y | NumericArray | Range result (max-min). |
Errors
| Identifier | When | Message |
|---|---|---|
| — | 'all' is combined with an explicit dimension. | range: 'all' cannot be combined with an explicit dimension |
| — | More than one explicit dimension selector is provided. | range: too many dimension arguments |
| — | Dimension arguments are non-integer, non-finite, or < 1. | range: dimension must be >= 1 |
| — | Dimension selector is GPU-resident. | range: dimension arguments must reside on the host (numeric or string) |
| — | Dimension selector has unsupported value type or shape. | range: unsupported dimension argument type |
How range works
- Operates on scalars, vectors, matrices, and N-D tensors.
range(X)measures the spread along the first non-singleton dimension.range(X, dim)targets a specific dimension.range(X, vecdim)reduces across multiple dimensions at once.range(X, 'all')collapses all elements to a single scalar result.range(___)is equivalent tomax(___) - min(___)over the requested slice.vecdimaccepts a row or column vector of positive integers; duplicate entries are ignored.range(___, 'omitnan')ignoresNaNvalues (resulting inNaNif a slice has no finite values).range(___, 'includenan')(default) returnsNaNfor any slice containingNaN.- Works with
gpuArrayinputs; the runtime keeps residency on the GPU when provider hooks are available.
GPU memory and residency
You generally do not need to call gpuArray explicitly in RunMat. When the input is already on the GPU, the planner keeps the result on-device if the active provider exposes reduce_min, reduce_max, the corresponding *_dim reductions, and elementwise subtraction. Current providers specialise 2-D reductions; multi-axis reductions, tensors with more than two dimensions, or 'omitnan' requests gather back to the host for correctness. When a required hook is missing, RunMat gathers the data automatically, computes on the CPU, and returns a standard tensor.
Examples
Measuring column-wise range of a matrix
A = [1 4 2; 3 7 5];
spread = range(A)Expected output:
% Each column's maximum minus minimum
spread = [2 3 3]Selecting a dimension explicitly
A = [1 4 2; 3 7 5];
row_spread = range(A, 2)Expected output:
row_spread = [3; 4]Collapsing all elements with 'all'
temperatures = [68 72 75; 70 74 78];
overall = range(temperatures, 'all')Expected output:
overall = 10Ignoring NaNs when computing range
samples = [2 NaN 5; 4 6 NaN];
spread = range(samples, 1, 'omitnan')Expected output:
spread = [2 0 0]Keeping gpuArray results on the device
G = gpuArray([1 10 3; 2 8 4]);
column_spread = range(G);
gather(column_spread)Expected output:
ans =
1 2 1Handling higher-dimensional inputs
data = reshape(1:24, [3, 4, 2]);
slice_spread = range(data, [1 2])Expected output:
slice_spread(:,:,1) =
11
slice_spread(:,:,2) =
11Using range with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how range changes the result.
Run a small range example, explain the result, then change one input and compare the output.
FAQ
What does range(X) return for scalars?⌄
The range of a scalar is always 0, because the maximum and minimum coincide.
How are NaN values treated by default?⌄
By default ('includenan'), any slice containing NaN yields NaN. Use 'omitnan' to ignore them.
Can I supply multiple dimensions?⌄
Yes. Pass a vector such as [1 3] to reduce across both the first and third dimensions simultaneously.
What happens if I request a dimension larger than ndims(X)?⌄
RunMat mirrors MATLAB: a size-1 dimension produces zeros (or NaN when the lone value is NaN).
Does range support integer and logical inputs?⌄
Yes. The inputs are promoted to double precision internally, matching MATLAB semantics.
How does range interact with gpuArray?⌄
The runtime asks the active provider for min/max reductions. When unavailable, it gathers the data and computes on the CPU.
Why is the output sometimes a scalar and sometimes a vector?⌄
The output collapses the selected dimensions to size 1, leaving other dimensions unchanged. A single remaining element becomes a scalar.
How can I inspect the range across all elements quickly?⌄
Use range(X, 'all') to flatten all dimensions into a single scalar spread.
Related Array functions
Creation
colon · eye · false · fill · inf · linspace · logspace · magic · meshgrid · nan · ones · peaks · rand · randi · randn · randperm · true · zeros
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how range is executed, line by line, in Rust.
- View the source for range in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.