colon — Generate arithmetic progressions with MATLAB and RunMat colon semantics.
colon(start, stop) and colon(start, step, stop) build row vectors like the MATLAB colon operator. The sequence starts at start, advances by step (defaulting to +1), and stops before exceeding stop under MATLAB/RunMat rules.
Syntax
x = colon(start, stop)
x = colon(start, step, stop)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
start | Any | Yes | — | Start scalar value. |
stop | Any | Yes | — | Stop scalar value (implicit step = 1). |
step | Any | Yes | — | Increment; zero returns an empty row vector. |
stop | Any | Yes | — | Stop scalar value. |
Returns
| Name | Type | Description |
|---|---|---|
x | Any | Arithmetic progression row vector (numeric or character). |
Errors
| Identifier | When | Message |
|---|---|---|
| — | More than three input arguments are provided. | colon: expected two or three input arguments |
| — | At least one input is not scalar. | colon: expected scalar input |
| — | At least one input scalar is non-finite. | colon: inputs must be finite numeric scalars |
| — | Complex inputs have non-zero imaginary parts. | colon: complex inputs must have zero imaginary part |
| — | String-like values are used as scalar bounds/step. | colon: inputs must be real scalar values; received a string-like argument |
| — | Character sequence values are non-integer. | colon: character sequence requires integer code points |
| — | Character sequence values are outside valid Unicode range. | colon: character code point out of range |
| — | Computed progression span/ratio is non-finite. | colon: sequence length exceeds representable range |
| — | Computed progression length exceeds platform limits. | colon: sequence length exceeds platform limits |
| — | Internal tensor/character output construction failed. | colon: internal error |
How colon works
- Inputs must be real scalars (numeric, logical, scalar tensors, or single-character arrays). Imaginary parts must be zero.
colon(start, stop)always uses an increment of+1; whenstart > stop, the result is empty and descending sequences require an explicit negative step.colon(start, step, stop)uses the supplied increment. A zero increment returns a1×0empty row vector in the selected output class.- When any operand is a typed integer, all typed-integer operands must use the same class and the result retains that class in exact native storage. An integral full scalar double may supply another operand, including a signed step for unsigned endpoints. Character endpoints return a character row vector; ordinary floating inputs return a floating row vector. Empty progressions are
1×0. stopis included only when it lies on the arithmetic progression; otherwise the sequence stops at the last admissible value before overshooting.- Arguments may be resident scalar arrays and the result stays with the owning provider. Resident int64 and uint64 operands are a mode-gated RunMat extension; other documented integer classes use exact resident storage.
- Logical operands and zero-imaginary complex operands are deliberate RunMat extensions and are rejected in compatibility mode.
- Floating-point tolerance follows MATLAB’s rules, so values that should land on
stopare preserved even when rounding noise accumulates.
GPU memory and residency
Resident floating inputs use the owning provider's linspace hook when available and otherwise upload the host-generated floating vector through that owner. Resident typed integers gather exact scalar storage, build the progression, and upload it through the owning provider; resident int64 and uint64 require RunMat mode. Typed complex-integer resident buffers remain an explicit provider-contract gap tracked separately.
Examples
Generating consecutive integers
x = colon(1, 5)Expected output:
x = [1 2 3 4 5]Counting down without specifying a step
y = colon(5, -1, 1)Expected output:
y = [5 4 3 2 1]Using a custom increment
z = colon(0, 0.5, 2)Expected output:
z = [0 0.5 1.0 1.5 2.0]Stopping before overshooting the end point
vals = colon(0, 2, 5)Expected output:
vals = [0 2 4]Working with fractional radians
theta = colon(-pi, pi/4, pi/2)Expected output:
theta = [-3.1416 -2.3562 -1.5708 -0.7854 0.0000 0.7854 1.5708]Keeping sequences on the GPU
g = gpuArray(0);
h = colon(g, 0.25, 1);
result = gather(h)Expected output:
result = [0 0.25 0.5 0.75 1.0]Building character ranges
letters = colon('a', 'f')
odds = colon('a', 2, 'g')Expected output:
letters = 'abcdef';
odds = 'aceg'Using colon with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how colon changes the result.
Run a small colon example, explain the result, then change one input and compare the output.
FAQ
What happens when start == stop?⌄
The output is a single-element vector containing start. With two arguments the implicit step is +1, so the result is [start].
Why is stop sometimes missing from the result?⌄
stop is included only when it aligns with the arithmetic progression. For example, colon(0, 2, 5) produces [0 2 4] because 6 would overshoot the upper bound.
Can I use zero or complex increments?⌄
A zero increment returns an empty 1×0 row vector. A complex increment with a non-zero imaginary part raises an error.
Can I generate character sequences?⌄
Yes. When both start and stop are single-character arrays, colon returns a character row vector. Step values can still be numeric (for example, colon('a', 2, 'g') produces 'aceg').
Does the function accept logical inputs?⌄
Only in RunMat mode. Logical scalar support is an explicit RunMat extension; compatibility mode accepts the documented numeric and character domains instead.
How does this differ from linspace?⌄
linspace(start, stop, n) lets you pick the number of points directly, whereas colon fixes the increment (start:step:stop). When stop is not exactly reachable, colon stops short instead of nudging the final value.
Related Array functions
Creation
createArray · empty · eye · false · full · inf · linspace · logspace · magic · meshgrid · nan · nchoosek · ndgrid · nonzeros · ones · peaks · perms · rand · randi · randn · randperm · range · sparse · spdiags · speye · spones · sprand · true · zeros
Grouping
accumarray · combinations · discretize · findgroups · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how colon is executed, line by line, in Rust.
- View the source for colon 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.