RunMat
GitHub

View all functions

CategoryArray: Creation
GPUYes

What does the colon function do in MATLAB / RunMat?

colon(start, stop) and colon(start, step, stop) build row vectors that mirror the MATLAB colon operator. The function returns an arithmetic progression that begins at start, advances by step (default +1 or -1 depending on the bounds), and stops before exceeding stop.

How does the colon function behave in MATLAB / RunMat?

  • Inputs must be real scalars (numeric, logical, scalar tensors, or single-character arrays). Imaginary parts must be zero.
  • colon(start, stop) picks an increment of +1 when stop ≥ start, otherwise -1.
  • colon(start, step, stop) uses the supplied increment. A zero increment raises an error.
  • When the endpoints are character scalars, the result is a row vector of characters; otherwise a double-precision row vector. Empty progressions are 1×0.
  • stop is included only when it lies on the arithmetic progression; otherwise the sequence stops at the last admissible value before overshooting.
  • Arguments may be gpuArray scalars; the result stays on the GPU when a provider is active.
  • Floating-point tolerance follows MATLAB’s rules, so values that should land on stop are preserved even when rounding noise accumulates.

Examples of using the colon function in MATLAB / RunMat

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);

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 behaviour:

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';

GPU residency in RunMat (Do I need gpuArray?)

RunMat automatically keeps the output on the GPU when any input scalar already resides there and an acceleration provider is active. Providers that implement the linspace hook (such as the wgpu backend) generate the progression entirely on device. Other providers still return a GPU tensor by uploading the host-generated vector, so downstream kernels can fuse without an extra gather.

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?

No. The increment must be a finite, non-zero real scalar. Supplying 0 or a value 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?

Yes. Logical scalars are promoted to doubles (true → 1, false → 0) before building the sequence.

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.

See Also

linspace, logspace, range, gpuArray, gather

Source & Feedback