ccalc

A fast terminal calculator with Octave/MATLAB syntax and script support — one binary, no runtime.

Current version: 0.48.0 — see CHANGELOG for history.

📖 Documentation

Why ccalc?

Octave is hundreds of megabytes. Python requires a runtime. ccalc is a single self-contained binary that starts instantly and works anywhere: interactive sessions, shell scripts, CI pipelines, Docker containers.

It speaks Octave/MATLAB syntax — familiar to engineers and scientists — without requiring a full language installation.

Installation

git clone https://github.com/holgertkey/ccalc
cd ccalc
cargo build --release

The binary is placed at target/release/ccalc. Copy it anywhere on your PATH.

Usage

ccalc [OPTIONS]           start interactive REPL
ccalc "EXPR"              evaluate expression and print result
ccalc script.m            run a script file
echo "EXPR" | ccalc       pipe mode — silent, result only
ccalc < formulas.txt      read expressions from file

Modes

Interactive REPL

Run without arguments:

$ ccalc
[ 0 ]:

Single expression

Pass an expression as a command-line argument:

$ ccalc "2 ^ 32"
4294967296

$ ccalc "sqrt(144)"
12

Script file

Pass a script file as an argument — any file that exists on disk:

$ ccalc script.m
$ ccalc script.calc
$ ccalc examples/mortgage.calc

Pipe / non-interactive mode

When stdin is not a terminal, ccalc runs silently — no prompt, one result per line. ans carries over across lines, so you can chain calculations:

$ echo "sin(pi / 6)" | ccalc
0.5

$ printf "10\n+ 5\n* 2" | ccalc
10
15
30

$ ccalc < formulas.txt

All commands work in script/pipe mode: exit/quit stop processing, who/clear/ws/wl/save/load manage variables, format controls number display, hex/dec/bin/oct/base control number base. cls is ignored.

How it works

The prompt shows ans — the result of the last expression. Every new expression updates it. Expressions that start with an operator automatically use ans as the left-hand operand (partial expressions):

[ 0 ]: 100
[ 100 ]: / 4
[ 25 ]: + 5
[ 30 ]: ^ 2
[ 900 ]:

Arithmetic

Operators

[ 0 ]: 2 + 3 * 4
[ 14 ]:

[ 0 ]: 2 ^ 3 ^ 2
[ 512 ]:               (right-associative: 2^(3^2) = 2^9)

Grouping

[ 0 ]: (2 + 3) * 4
[ 20 ]:

Unary minus

[ 0 ]: -5
[ -5 ]:

[ 0 ]: -(3 + 2)
[ -5 ]:

Ergonomics

Implicit multiplication

A number or closing parenthesis immediately before ( multiplies without an explicit *:

[ 0 ]: 2(3 + 1)
[ 8 ]:

[ 0 ]: (2 + 1)(4 - 1)
[ 9 ]:

Constants

ans is the implicit accumulator — it is updated after every expression and can be used anywhere in an expression:

[ 9 ]: ans * 2 + 1
[ 19 ]:

[ 25 ]: sqrt(ans)
[ 5 ]:

Math functions

If called with empty parentheses, ans is used as the argument.

One-argument

Two-argument

[ 0 ]: sqrt(144)
[ 12 ]:

[ 0 ]: sin(pi / 6)
[ 0.5 ]:

[ 0 ]: hypot(3, 4)
[ 5 ]:

[ 0 ]: atan2(1, 1) * 180 / pi
[ 45 ]:

[ 0 ]: mod(-1, 3)
[ 2 ]:

[ 16 ]: sqrt()          same as sqrt(16)
[ 4 ]:

Functions can be nested and combined:

[ 0 ]: sqrt(abs(-25))
[ 5 ]:

[ 0 ]: max(hypot(3, 4), 6)
[ 6 ]:

Variables

Any identifier can be used as a variable. ans is the implicit variable updated after every standalone expression.

Assignment

name = expr shows the assigned value and does not update ans. Append ; to suppress output.

[ 0 ]: rate = 0.06 / 12
rate = 0.005
[ 0 ]: n = 360
n = 360
[ 0 ]: 200000 * 0.005
[ 1000 ]:

Using variables

[ 0 ]: rate = 0.07
rate = 0.07
[ 0 ]: 1000 * (1 + rate) ^ 10
[ 1967.1513573 ]:

View and clear

[ 0 ]: rate = 0.05
[ 0 ]: n = 12
[ 0 ]: rate + n
[ 12.05 ]: who
ans = 12.05
n = 12
rate = 0.05
[ 12.05 ]: clear rate
[ 12.05 ]: clear

Matrices

Create matrices using bracket syntax. Separate elements with spaces or commas; separate rows with ; or a bare newline (both work inside [...]):

[ 0 ]: A = [1 2; 3 4]
A =
   1   2
   3   4

[ [2×2] ]: B = [5 6; 7 8]
B =
   5   6
   7   8

[ [2×2] ]: A + B
ans =
    6    8
   10   12

Scalar operations are element-wise:

[ [2×2] ]: 2 * A
ans =
   2   4
   6   8

Matrix multiplication and transpose

[ [2×2] ]: A * B          matrix multiplication
[ [2×2] ]: A'             transpose
[ [2×2] ]: v' * v         dot product (row × column)

Element-wise operators

[ [2×2] ]: A .* B         element-wise multiply
[ [2×2] ]: A ./ B         element-wise divide
[ [2×2] ]: A .^ 2         element-wise power

Matrix built-ins

The REPL prompt shows the matrix dimensions when ans is a matrix. who displays dimensions: A = [2×2 double]. ws saves only scalar variables; matrices are not persisted.

Range operator

Generate row vectors with the : operator:

1:5              % [1 2 3 4 5]
1:2:9            % [1 3 5 7 9]   (start:step:stop)
0:0.5:2          % [0 0.5 1 1.5 2]
5:-1:1           % [5 4 3 2 1]

Ranges work inside matrix literals and can be mixed with scalars:

[ 0 ]: v = 1:4
v =
   1   2   3   4

[ [1×4] ]: [0, 1:3, 10]
ans =
    0   1   2   3   10

linspace(a, b, n) generates n evenly spaced values between a and b:

linspace(0, 1, 5)    % [0  0.25  0.5  0.75  1]
linspace(1, 5, 5)    % [1  2  3  4  5]

Indexing

All indices are 1-based (Octave convention). A name that exists as a variable always indexes — variables shadow built-in function names.

[ 0 ]: v = 1:5
v =
   1   2   3   4   5

[ [1×5] ]: v(3)
[ 3 ]: v(2:4)
ans =
   2   3   4

[ [1×3] ]: A = [1 2 3; 4 5 6; 7 8 9]
[ [3×3] ]: A(2,3)
[ 6 ]: A(:,2)
ans =
   2
   5
   8

[ [3×1] ]: A(1:2, 2:3)
ans =
   2   3
   5   6

Indexed assignment

All read forms work as write targets. A scalar RHS is broadcast to all selected positions:

v = zeros(1, 6);
v(3) = 42;            % set element 3
v(1:2) = [10, 20];    % slice assignment
v(4:6) = 99;          % broadcast scalar to three positions
v(:) = 0;             % reset all elements

A = zeros(4);
A(2, 3) = 7;               % 2-D element
A(:, 1) = [1; 2; 3; 4];   % full column
A(2:3, 2:3) = eye(2);      % submatrix

Growing vectors — assigning beyond the current length pads with zeros. end+1 is the idiomatic append:

v = [];
for k = 1:8
  v(end+1) = k^2;     % append k-squared
end
% v = [1 4 9 16 25 36 49 64]

Logical (boolean mask) indexing — a 0/1 mask selects positions for reading or writing:

temps = [18, 22, 35, 12, 29, 41, 8, 33];
hot   = temps(temps >= 30);   % read: [35 41 33]
temps(temps >= 30) = 30;      % write: cap all hot values at 30

Vector & Data Utilities

Special constants and predicates

Reductions

For vectors (1×N or N×1) these return a scalar. For M×N matrices (M>1, N>1) they operate column-wise and return a 1×N row vector.

Data manipulation

end in index expressions

Inside (...) index positions, end resolves to the length of that dimension. Arithmetic on end is fully supported:

[ 0 ]: v = [10 20 30 40 50];
[ [1×5] ]: v(end)
[ 50 ]: v(end-1)
[ 40 ]: v(3:end)
ans =
   30   40   50

[ [1×3] ]: A = [1:4; 5:8; 9:12];
[ [3×4] ]: A(end, :)
ans =
    9   10   11   12

[ [1×4] ]: A(1:end-1, 2:end)
ans =
   2   3   4
   6   7   8

[ 0 ]: data = [3 1 4 1 5 9 2 6];
[ [1×8] ]: sort(data)
ans =
   1   1   2   3   4   5   6   9

[ [1×8] ]: find(data > 4)
ans =
   5   6   8

[ [1×3] ]: cumsum(data)
ans =
    3   4   8   9   14   23   25   31

Statistics & Random Numbers

Random number generation

rng(42)
x = randn(1, 5)         % reproducible 5-element sequence
d = randi(6, 1, 10)     % ten dice rolls

Descriptive statistics

All functions operate column-wise on M×N matrices and collapse to a scalar for vectors.

Normal distribution

normcdf(1) - normcdf(-1)   % 0.6827  (68% rule)
normcdf(2) - normcdf(-2)   % 0.9545  (95% rule)

See examples/statistics.calc for a full worked example.

Matrix Utilities & Set Operations

Triangular extraction and tiling

Vector products

Set operations

Results are always sorted ascending and deduplicated. NaN is never a member (IEEE semantics).

Index conversion and element repetition

Polynomial Operations & Interpolation

Polynomials are row vectors of coefficients in descending degree order: p(x) = x² − 3x + 2 → [1, -3, 2]

p = [1 0 1];              % x² + 1
polyval(p, [0 1 2])       % → [1 2 5]

x = [0 1 2 3 4];
y = [1 2 5 10 17];
c = polyfit(x, y, 2)      % → [1.0  0.0  1.0]  (≈ x² + 1)

roots([1 2 1])            % → [-1; -1]  (repeated root)
roots([1 0 1])            % → {0+1i; 0-1i}  (complex pair — Cell)

poly([1 2 3])             % → [1 -6 11 -6]  (x-1)(x-2)(x-3)
poly([2 1; 0 3])          % → [1 -5 6]  characteristic polynomial

conv([1 2 3], [1 1])      % → [1 3 5 3]
[q, r] = deconv([1 3 5 3], [1 1])   % q=[1 2 3], r=[0 0 0 0]

xi = [0 1 2 3]; yi = [0 1 4 9];
interp1(xi, yi, 1.5)               % → 2.5  (linear)
interp1(xi, yi, 1.5, 'nearest')    % → 1

See examples/polynomials.m and help poly for full documentation.

FFT & Signal Processing

Requires the fft feature flag:

cargo build --release --features fft

fftshift, ifftshift, and fftfreq are always available.

x = [1 2 3 4];
X = fft(x);
% X(1) = 10 + 0i  (DC = sum of all samples)
% X(2) = -2 + 2i
% X(3) = -2 + 0i
% X(4) = -2 - 2i

mag = abs(X)       % → real Matrix of bin magnitudes
y   = ifft(X)      % → [1 2 3 4]  (real matrix; roundtrip)

fftshift([1 2 3 4 5 6])   % → [4 5 6 1 2 3]

n = 8; fs = 1000;
f = fftfreq(n, 1/fs)      % → [0 125 250 375 -500 -375 -250 -125]

See examples/fft_demo.calc and help fft for a full worked example.

Plot Functions

Feature flags — at least one is required for rendering:

cargo build --release --features plot          # ASCII terminal charts
cargo build --release --features plot-svg      # SVG + PNG file export
cargo build --release --features plot-all      # both

Annotation functions (title, xlabel, ylabel, zlabel, xlim, ylim, zlim, legend, grid) work without any feature.

Chart types

Style strings and colors

Color specification forms (accepted by all styled plot functions):

An optional style string argument (before the file path) sets color, marker, and line style for plot, scatter, fill, area — MATLAB-compatible:

plot(x, y, 'r--')                % red dashed line
plot(x, y, 'orange')             % full color name
plot(x, y, '#1A6ECC')            % hex color
plot(x, y, [0.8 0.2 0.1])        % RGB matrix
bar([1 3 2 5], 'color', 'purple')  % 'color' named arg
hist(v, 20, 'color', '#FF8800')    % hex via named arg

Style strings affect SVG/PNG output only; ASCII charts are always monochrome.

Append a file path to save instead of print to terminal:

Annotations

Set annotations before the render call — they are consumed and cleared by the next render:

x = linspace(0, 2*pi, 80);

% ASCII line chart
title('sin(x)')
xlabel('x (radians)')
plot(x, sin(x))

% Multi-series SVG with legend and grid
M = [sin(x); cos(x)];
legend('sin', 'cos')
grid('on')
plot(x, M, 'trig.svg')

% Dark theme with custom line width
theme('dark')
linewidth(2)
plot(x, sin(x), 'sin_dark.svg')

% Equal-scale axes (circles appear as circles)
t = linspace(0, 2*pi, 120);
axis('equal')
plot(cos(t), sin(t), 'circle.svg')

% Histogram with explicit edges
hist(randn(1, 500), -3:0.5:3, 'dist.png')

% 3D helix to SVG
t2 = linspace(0, 4*pi, 120);
title('3D helix')
zlabel('z = t/(4π)')
plot3(cos(t2), sin(t2), t2/(4*pi), 'helix.svg')

See examples/plot_demo.calc (ASCII), examples/plot_file/plot_file.calc (file export), examples/plot_extended.calc (bar/stem/stairs/hist/loglog), examples/plot3_demo.calc (3D ASCII), examples/plot3_file/plot3_file.calc (3D file export), examples/colormap/imagesc_demo.calc (imagesc/colormap heat-maps), examples/subplot_demo/subplot_demo.calc (2×2 subplot grid), examples/hold_demo/hold_demo.calc (hold on/off overlay), examples/color_system_demo/color_system_demo.calc (unified color system), and examples/figure_appearance_demo/figure_appearance_demo.calc (figure appearance — Phase 30.6) for full worked examples. Run help plot in the REPL for a quick reference.

Bitwise Functions

All require non-negative integer arguments — combine naturally with 0xFF, 0b1010, 0o17 literals.

[ 0 ]: bitand(0xFF, 0x0F)
[ 15 ]: bitxor(0xFF, 0x0F)
[ 240 ]: bitshift(1, 8)
[ 256 ]: bitnot(5, 8)
[ 250 ]:

Comparison & Logical Operators

Comparison operators return 1 (true) or 0 (false):

Logical operators:

! and != are C/shell-style aliases for ~ and ~=.

Precedence (low → high): || → && → comparisons → : → +/- → *// → ^ → unary (-, ~) → primary

[ 0 ]: 3 > 2
[ 1 ]:

[ 0 ]: 3 == 3
[ 1 ]:

[ 0 ]: 5 ~= 5
[ 0 ]:

[ 0 ]: ~0
[ 1 ]:

[ 0 ]: 2 > 1 && 3 > 2
[ 1 ]:

Element-wise on matrices — comparisons produce a 0/1 mask of the same shape:

[ 0 ]: v = [1 2 3 4 5];
[ 0 ]: v > 3
ans =
   0   0   0   1   1

[ [1×5] ]: v .* (v > 3)    % zero out elements <= 3
ans =
   0   0   0   4   5

Strings

ccalc supports two string types, matching MATLAB/Octave:

Char arrays — single quotes

[ 0 ]: greeting = 'Hello!'
greeting = Hello!
[ 'Hello!' ]: length(greeting)
[ 6 ]:

Char arrays are numeric-compatible — arithmetic converts each character to its ASCII code:

[ 0 ]: 'a' + 0        % ASCII of 'a'
[ 97 ]:
[ 0 ]: 'abc' + 1      % shift each code by 1
ans =
   98   99   100

String objects — double quotes

[ 0 ]: s = "Hello"
s = Hello
[ '"Hello"' ]: s + ", World!"
[ '"Hello, World!"' ]:

String objects use + for concatenation.

String built-ins

length(s), numel(s), and size(s) all work on strings.

Datetime & Duration

UTC datetime and duration values are first-class types. Timestamps are stored as seconds since the Unix epoch (1970-01-01 00:00:00 UTC).

Constructors

datetime('2024-06-01')                      % from ISO 8601 date string
datetime('2024-06-01 09:30:00')             % date + time
datetime(2024, 6, 1)                        % from year, month, day
datetime(2024, 6, 1, 9, 30, 0)             % from six components
datetime(ts, 'ConvertFrom', 'posixtime')    % from Unix timestamp

duration(1, 30, 0)    % 1 h 30 min → Duration
hours(2)              % 2 hours
minutes(90)           % 90 minutes
seconds(45)           % 45 seconds
days(1)               % 1 day
milliseconds(500)     % 500 ms
years(1)              % 365.2425 days

NaT is the Not-a-Time constant (analogous to NaN for numbers). Durations display as HH:MM:SS.

Arithmetic

t  = datetime(2024, 1, 1);
t2 = t + hours(3);           % 2024-01-01 03:00:00
elapsed = t2 - t;            % Duration: 03:00:00
fprintf('%g minutes\n', minutes(elapsed))   % 180

Component and duration extractors

year(dt)   month(dt)   day(dt)    % DateTime → Scalar
hour(dt)   minute(dt)  second(dt)

hours(d)   minutes(d)  seconds(d)  days(d)  milliseconds(d)  % Duration → Scalar

Predicates

isdatetime(x)   % 1 if DateTime or DateTimeArray
isduration(x)   % 1 if Duration or DurationArray
isnat(x)        % 1 if NaT; 0 for any other value

Formatting

datestr(dt)                     % '15-Jun-2024 09:30:00'
datestr(dt, 'yyyy/MM/dd')       % custom pattern
datevec(dt)                     % [y m d H M S] row vector
datenum(dt)                     % MATLAB serial date number
posixtime(dt)                   % Unix timestamp as scalar
fprintf('%s\n', dt)             % ISO: '2024-06-01 09:30:00'
fprintf('%s\n', dur)            % HH:MM:SS: '01:30:00'

Array operations

% Matrix literals produce DateTimeArray / DurationArray
dates = [datetime(2024,1,1); datetime(2024,2,1); datetime(2024,3,1)];
durs  = [hours(1); hours(2); hours(3)];

% diff — successive differences
d = diff(dates);    % DurationArray  (each element = next − prev)
fprintf('%g days\n', days(d))

Complex Numbers

i and j are pre-set to the imaginary unit 0 + 1i. Complex numbers work with the same operators and functions as real numbers:

[ 0 ]: 3 + 4*i
[ 3 + 4i ]: abs(ans)
[ 5 ]: angle(3 + 4*i) * 180/pi
[ 53.1301023542 ]:

Create, decompose, and manipulate:

z = complex(3, 4)    % 3 + 4i
real(z)              % 3
imag(z)              % 4
conj(z)              % 3 - 4i
z'                   % 3 - 4i  (conjugate transpose)
isreal(z)            % 0

Arithmetic works for all combinations of complex and real scalars:

(3 + 4*i) * (1 - 2*i)   % 11 - 2i
i^2                       % -1    (exact integer exponentiation)
i^4                       %  1

Complex built-ins

Complex matrices

Any matrix literal with at least one complex element becomes a ComplexMatrix. Real elements are promoted automatically. Full arithmetic, Hermitian transpose (A'), plain transpose (A.'), element-wise built-ins (real, imag, abs, conj, angle, isreal), and reductions (trace, diag, sum, prod, mean) all work on ComplexMatrix.

A = [1+2i, 3-4i; 5, 6+1i]    % 2×2 ComplexMatrix
A'                              % conjugate transpose
abs(A)                          % real Matrix of element-wise moduli
trace(A)                        % Complex scalar (sum of diagonal)

% Indexed assignment: real Matrix auto-upcasts to ComplexMatrix
B = zeros(3, 3)
B(2, 2) = 1 + 2i               % B is now ComplexMatrix

eig(A) returns a ComplexMatrix column vector when a real non-symmetric matrix has complex conjugate eigenvalue pairs, enabling stability analysis:

d = eig([0, 1; -4, -1.2])      % ComplexMatrix [complex pair]
fprintf('stable: %d\n', all(real(d) < 0))

Since Phase 27, fft() returns a ComplexMatrix instead of a Cell array. Access bins with X(k) and get the magnitude spectrum with abs(X).

See examples/complex_matrix.m, examples/complex_matrix_ext.m, and help complex for more details.

Formatted Output

fprintf — print to stdout

fprintf(fmt, v1, v2, ...) prints formatted output using C-style conversion specifiers:

Width, precision, and alignment flags follow standard C printf conventions:

fprintf('%8.3f\n', pi)      %     3.142
fprintf('%-10s|\n', 'hi')   % hi        |
fprintf('%+.4e\n', 1000)    % +1.0000e+03
fprintf('%05d\n', 42)       % 00042

Escape sequences: \n (newline), \t (tab), \\ (backslash).

When there are more arguments than conversion specifiers, the format string repeats (Octave behaviour):

fprintf('%d ', 1, 2, 3)     % 1 2 3

sprintf — format to string

Same as fprintf but returns the result as a char array instead of printing:

label = sprintf('R = %.1f Ohm', R);
disp(label)

File I/O

File handles

fd = fopen('log.txt', 'w');         % open for writing; returns fd (≥3) or -1 on failure
fprintf(fd, 'x = %.4f\n', x);      % write formatted text to file
fclose(fd);                         % close; returns 0 or -1

fd = fopen('data.txt', 'r');        % open for reading
line = fgetl(fd);                   % read one line, newline stripped; -1 at EOF
raw  = fgets(fd);                   % read one line, newline kept
fclose(fd);

fclose('all');                      % close all open file handles

Modes: 'r' read, 'w' write (create/truncate), 'a' append, 'r+' read+write.
File descriptor 1 = stdout, 2 = stderr.

Delimiter-separated data

dlmwrite('results.csv', A);         % write matrix, comma-separated
dlmwrite('results.tsv', A, '\t');   % explicit delimiter

data = dlmread('results.csv');      % read; auto-detect ',' / '\t' / whitespace
data = dlmread('results.tsv', '\t');

CSV tables — readmatrix / readtable / writetable

Higher-level CSV functions with header row support and type inference.

% readmatrix — numeric data, auto-skip non-numeric header
A = readmatrix('sensor.csv')                   % header skipped automatically
A = readmatrix('data.tsv', 'Delimiter', '\t')  % explicit delimiter

% readtable — first row always the header; returns Struct of columns
T = readtable('grades.csv')
scores = T.score      % Matrix N×1  (numeric column)
names  = T.name       % Cell         (string column)

% writetable — write Struct to CSV with header row
T.name  = {'Alice', 'Bob', 'Carol'};
T.score = [91; 85; 78];
writetable(T, 'out.csv')
writetable(T, 'out.tsv', 'Delimiter', '\t')

Column type inference in readtable: if every cell in a column is parseable as a number (empty cells → NaN), the column becomes a Matrix N×1; otherwise a Cell of Str. writetable accepts the same column types and applies RFC 4180 quoting automatically for values containing the delimiter or quotes.

Filesystem queries

isfile('data.csv')          % 1 if the path is an existing file, else 0
isfolder('output/')         % 1 if the path is an existing directory, else 0
pwd()                       % current working directory as a char array

exist('x', 'var')           % 1 if variable x is in the workspace
exist('x', 'file')          % 2 if file exists on disk (MATLAB numeric code)
exist('x')                  % checks workspace first, then filesystem

Directory listing

dir returns a struct array; each element has fields name, folder (absolute path), isdir, and bytes.

entries = dir('.')           % list current directory (.  and .. always first)
entries = dir('*.csv')       % glob — only matching files (no . or ..)
entries = dir()              % same as dir('.')

% Walk a directory
for k = 1:numel(entries)
    if ~entries(k).isdir
        fprintf('%s  %d bytes\n', entries(k).name, entries(k).bytes);
    end
end

Non-existent path → empty struct array, no error.

Workspace with explicit path

save                            % save all variables to default path
save('session.mat')             % save all variables to named file
save('session.mat', 'x', 'y')  % save specific variables only
load('session.mat')             % load variables from named file

path = 'session.mat';
save(path)                      % variable reference also accepted

Scalars, char arrays, and string objects are persisted. Matrices, complex values, and functions are always skipped.

JSON

Requires the json feature flag:

cargo build --release --features json

Without this flag, calling either built-in returns an informative error. Both names always appear in tab completion.

% Decode — JSON string → ccalc Value
s = jsondecode('{"name":"Alice","scores":[88,92,75]}')
s.name       % → 'Alice'  (Str)
s.scores     % → [88  92  75]  (Matrix 1×3)

jsondecode('[1, 2, 3]')          % → [1  2  3]  (all-numeric → Matrix)
jsondecode('[1, "two", true]')   % → {1, 'two', 1}  (mixed → Cell)
jsondecode('null')               % → NaN
jsondecode('true')               % → 1

% Encode — ccalc Value → compact JSON string
jsonencode(42)                   % → '42.0'
jsonencode('hello')              % → '"hello"'
jsonencode([1 2 3])              % → '[1.0,2.0,3.0]'
jsonencode(s)                    % → '{"name":"Alice","scores":[88.0,92.0,75.0]}'
jsonencode(nan)                  % → 'null'

Type mapping:

Reading a JSON file (combine with fgetl for single-line JSON):

fid = fopen('data.json', 'r');
raw = fgetl(fid);
fclose(fid);
data = jsondecode(raw);

MAT Files

Requires the mat feature flag:

cargo build --release --features mat

Without this flag, calling load('*.mat') returns an informative error. load always appears in tab completion.

% Assignment form — returns a Struct of all variables in the file
data = load('results.mat');
data.score        % Scalar
data.readings     % Matrix
data.label        % Str (char array)
data.sensor.gain  % nested Struct field

% Bare form — injects all variables directly into the workspace
load('results.mat')
score             % now a workspace variable

Type mapping:

Backed by matrw = "=0.1.4". Complex and sparse matrices are not yet supported.

Control Flow

Multi-line control flow blocks are supported in both REPL and script mode.

REPL multi-line input

The REPL detects unclosed blocks and buffers lines with a continuation prompt until end is seen. Press Ctrl+C to cancel an incomplete block.

[ 0 ]:   for k = 1:3
  >>   fprintf('%d\n', k)
  >> end
1
2
3

if / elseif / else

score = 73;
if score >= 90
  grade = 'A';
elseif score >= 70
  grade = 'C';
else
  grade = 'F';
end
fprintf('grade: %s\n', grade)

for

Iterates over a range (or matrix columns):

total = 0;
for k = 1:10
  total += k ^ 2;
end
fprintf('sum of squares: %d\n', total)   % 385

while

x = 1.0;
while abs(x ^ 2 - 2) > 1e-12
  x = (x + 2 / x) / 2;
end
fprintf('sqrt(2) ≈ %.15f\n', x)

break and continue

for n = 1:20
  if mod(n, 2) == 0
    continue       % skip even numbers
  end
  if n > 9
    break          % stop after 9
  end
  fprintf('%d ', n)
end

switch / case / otherwise

switch code
  case 200
    msg = 'OK';
  case 404
    msg = 'Not Found';
  otherwise
    msg = 'Unknown';
end
fprintf('%d: %s\n', code, msg)

No fall-through — only the first matching case runs. Works with scalars and strings. otherwise is optional.

do ... until

Octave post-test loop — the body always runs at least once, then the condition is checked:

x = 1;
do
  x *= 2;
until (x > 100)
fprintf('%d\n', x)   % 128

break and continue work inside do...until.

User-defined functions

Named functions use the function ... end block syntax:

function result = factorial_r(n)
  if n <= 1
    result = 1;
    return
  end
  result = n * factorial_r(n - 1);
end

factorial_r(7)   % 5040

Multiple return values are separated with [...]:

function [mn, mx, avg] = stats(v)
  mn  = min(v);
  mx  = max(v);
  avg = mean(v);
end

data = [4 7 2 9 1 5 8];
[lo, hi, mu] = stats(data);   % lo=1  hi=9  mu=5.14...

Use ~ to discard individual outputs:

[~, top, ~] = stats([10 30 20]);   % top = 30

nargin — number of arguments actually passed; useful for optional parameters:

function y = power_fn(base, exp)
  if nargin < 2
    exp = 2;
  end
  y = base ^ exp;
end

power_fn(5)     % 25   (default exponent)
power_fn(2, 8)  % 256

Functions are recursive. They see all other Function/Lambda values defined in the workspace at the time of the call.

Anonymous functions (lambdas)

sq   = @(x) x ^ 2;
hyp  = @(a, b) sqrt(a^2 + b^2);

sq(7)        % 49
hyp(3, 4)    % 5

Lambdas capture the enclosing environment at definition time (lexical closure):

rate = 0.05;
interest = @(p, n) p * (1 + rate) ^ n;
rate = 0.99;                        % does not affect the lambda
interest(1000, 10)                  % 1628.89  (uses captured 5%)