ccalc

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

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.

Quick start

# Interactive REPL
ccalc

# Single expression
ccalc "2 ^ 32"

# Script file
ccalc script.m

# Pipe mode
echo "sqrt(2)" | ccalc

Who is it for?

Project structure

The engine crate is the computation foundation. It has no I/O dependencies and is the target for all Octave/MATLAB compatibility work (Phases 1–10).

Compatibility standard

Where MATLAB and Octave differ, ccalc follows the modern MATLAB standard (R2016b+). See Architecture → Overview for design principles.

Source

• Repository: https://github.com/holgertkey/ccalc
• Changelog: see CHANGELOG.md in the repository root

User Guide

This guide covers everything you need to use ccalc effectively: from the first expression in the REPL to scripts with functions, matrices, structs, and plots.

Contents

Getting Started

Installation

Build from source (requires Rust):

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

Usage modes

Interactive REPL

ccalc

A prompt shows the current value of ans. Type an expression and press Enter. Type help for a reference, or help <topic> for a specific section.

[ 0 ]: 2 ^ 32
[ 4294967296 ]: / 1024
[ 4194304 ]: sqrt()
[ 2048 ]: help functions
...
[ 2048 ]: exit

Single expression (argument mode)

ccalc "EXPR"

Evaluates the expression, prints the result, and exits. Useful for shell scripts.

$ ccalc "2 ^ 32"
4294967296

$ ccalc "sqrt(2)"
1.4142135624

Script file

Pass a .m or .ccalc file as an argument:

ccalc script.m
ccalc examples/mortgage.ccalc

Pipe / non-interactive mode

When stdin is not a terminal, ccalc reads lines one by one and prints one result per line. ans carries over across lines.

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

$ printf "100\n/ 4\n+ 5" | ccalc
100
25
30

$ ccalc < formula.txt

Command-line options

REPL Mode

Start with ccalc (no arguments, stdin is a terminal).

Prompt

The prompt always shows the current value of ans:

[ 0 ]:
[ 42 ]:
[ 0xFF ]:

ans

Every expression result is stored in ans. Expressions that start with an operator use ans as the left-hand operand (partial expressions):

[ 0 ]: 100
[ 100 ]: * 2
[ 200 ]: + 50
[ 250 ]: / 5
[ 50 ]:

REPL commands

Help topics for help <topic>: syntax functions userfuncs testing bases vars script matrices highlight prompt examples

Tab completion

Press Tab in the REPL to complete the current word:

• Variable names defined in the current session.
• Built-in function names (sqrt, mean, assert, …).

When multiple candidates match, they are listed and the longest common prefix is inserted. Press Tab again to cycle or type more characters to narrow down.

>> inv<Tab>       → inv(
>> my_fun<Tab>    → my_function   (if defined)

Inline help for user functions

Place %-comment lines immediately after the function header (MATLAB H1-line style) to attach a doc string. help <name> prints it:

function t = tri(n)
% Return the nth triangular number T(n) = n*(n+1)/2.
% Usage: t = tri(n)
  t = n * (n + 1) / 2;
end

>> help tri
Return the nth triangular number T(n) = n*(n+1)/2.
Usage: t = tri(n)

help <name> searches the current workspace first, then — for functions on the session path — loads the file on demand, so help bisect works even before bisect() has been called.

“Did you mean?” error hints

When a name is not found, ccalc compares it against known variables and built-in names using edit distance. If a close match exists (at most 2 edits), it is shown as a suggestion:

>> sqrtt(4)
Error: Unknown function 'sqrtt'; did you mean 'sqrt'?

>> my_valu + 1
Error: Undefined variable 'my_valu'; did you mean 'my_value'?

Keyboard shortcuts

Silencing a line

Append ; to suppress output. For expressions, ans is still updated. For assignments, ans is never updated regardless of ;.

[ 0 ]: 0.06 / 12;          % expression — ans updated, output suppressed
[ 0.005 ]: rate = 0.07;    % assignment — silent, ans unchanged
[ 0.005 ]:

Multiple ;-separated statements on one line — all but the last are silent:

[ 0 ]: a = 1; b = 2; c = 3;    % all silent
[ 0 ]: a = 1; b = 2             % a = 1 silent, b = 2 shown
b = 2
[ 0 ]:

Configuration

Settings that persist across sessions (precision, default base, prompt) live in config.toml. The config command shows the active values; config reload applies any edits without restarting.

[ 0 ]: config
config file: /home/user/.config/ccalc/config.toml
precision:   10
base:        dec

Syntax highlighting

ccalc highlights the current input line in real time as you type:

Highlighting is active by default. To disable it, set enabled = false in the [highlight] section of config.toml:

[highlight]
enabled = false

To change a colour, add the corresponding key:

[highlight]
keywords = "bold:blue"
numbers  = "color256(208)"
comments = "#808080"

Supported formats: named ("yellow"), 8-bit ("color256(N)"), 24-bit truecolor ("#RRGGBB"), and a "bold:" prefix for any of them. See Configuration for the full reference.

Custom prompt

Edit ~/.config/ccalc/config.toml to customise the prompt:

[repl]
prompt1 = "{gray}({line}){reset} [ {ans} ]: "

Supported placeholders: {ans}, {line}, {user}, {host}, {cwd}, {cwd_short}, {time}, color names ({red}, {green}, {reset}, …), and 24-bit truecolor ({#FF8800}). See Configuration for the full placeholder reference and examples.

History

Input history is saved to ~/.config/ccalc/history and restored on the next session. Each session is marked with a timestamp comment:

% --- Session: 2026-04-01 14:22:07 UTC ---
rate = 0.06 / 12
n = 360
% --- Session: 2026-04-01 15:10:44 UTC ---
hypot(3, 4)

The marker uses % so it is harmless if accidentally recalled and executed.

Pipe & Script Mode

When stdin is not a terminal (pipe or file redirect), or when a script file is passed as an argument, ccalc runs in non-interactive mode: no prompts, one result printed per line.

Pipe

echo "1 + 1" | ccalc
printf "100\n/ 4\n+ 5" | ccalc

Script files

Pass a file as an argument:

ccalc script.m
ccalc examples/mortgage.ccalc

Or redirect stdin:

ccalc < formula.txt

The entire file is parsed before execution begins, so helper functions may be defined at the bottom of the script and called from code above them — the same layout used by MATLAB/Octave scripts. See Function hoisting for details.

Comments

% starts a line comment (Octave/MATLAB convention):

% full-line comment — line is skipped entirely
10 * 5  % inline comment — expression still evaluates
# hash-style comment — same behaviour

Multi-line block comments use %{ … %} (or #{ … #}). The opening and closing markers must be the leading non-whitespace content on their line:

%{
  This entire block is ignored by the parser.
  Useful for commenting out sections of code.
%}
x = 42;   % this line executes normally

%{ also works on a single line %}

Semicolon — suppress output

A trailing ; suppresses output. Expressions still update ans; assignments never update ans regardless of ;.

rate = 0.06 / 12;    % silent assignment — ans unchanged
n = 360;             % silent assignment — ans unchanged
factor = (1 + rate) ^ n;

Multiple ;-separated statements on one line are also supported:

a = 1; b = 2; c = 3;    % all silent
a = 1; b = 2            % a = 1 silent, b = 2 printed

disp(expr) — print value

disp(expr) evaluates the expression and prints the result. It does not update ans.

disp(ans)               % print current ans value
disp(rate * 12)         % print expression result

fprintf('fmt') — print formatted text

fprintf('fmt') prints a string with escape sequences (\n, \t, \\). No newline is added automatically — include \n explicitly.

fprintf('=== Monthly mortgage ===\n')
fprintf('Result: ')
disp(ans)

Output:

=== Monthly mortgage ===
Result: 1199.1010503

Supported commands in pipe mode

All REPL commands except cls (which is ignored): exit, quit, who, clear, clear <name>, ws, wl, p, p<N>, hex, dec, bin, oct, base.

Example — mortgage script

% Monthly mortgage payment
% Principal: 200 000, annual rate: 6%, term: 30 years

rate = 0.06 / 12;         % monthly interest rate
n = 360;                  % 30 years * 12 months
p = 200000;               % principal

factor = (1 + rate) ^ n;

p * rate * factor / (factor - 1)
fprintf('Monthly payment ($): ')
disp(ans)

Output:

1199.1010503
Monthly payment ($): 1199.1010503

Arithmetic & Operators

Scalar operators

For modulo use the mod(a, b) function. % is a comment character, not a modulo operator.

Comments

% and # start line comments. Everything to the right is ignored:

% full-line comment
x = 5;   % inline comment — x is still assigned

Multi-line block comments span from %{ to %} (each on its own line):

%{
  Everything inside this block is ignored.
  The %{ and %} must be the only non-whitespace content on their line.
%}
y = 10;

A same-line form %{ text %} is also valid. Hash-style #{ … #} works identically.

Comparison operators

Return 1.0 (true) or 0.0 (false). Work element-wise on matrices.

Logical operators

See Comparison & Logical Operators for full details.

Precedence (high → low)

1. postfix ' — transpose
2. ^, .^ — right-associative
3. unary -, ~ — negation, logical NOT
4. *, /, .*, ./, .^, implicit multiplication
5. +, -
6. : — range
7. ==, ~=, <, >, <=, >= — comparison (non-associative)
8. && — logical AND
9. || — logical OR (lowest)

Use parentheses to override: (2 + 3) * 4 → 20.

Special values: Inf, NaN, and division by zero

Division by zero follows IEEE 754 — it produces Inf or NaN rather than an error:

1 / 0      % Inf
-1 / 0     % -Inf
0 / 0      % NaN
0 \ 1      % Inf  (left division: 1/0)

These values propagate through arithmetic in the expected way:

Inf + 1    % Inf
Inf - Inf  % NaN
1 / Inf    % 0
isnan(NaN) % 1
isinf(Inf) % 1

Partial expressions

An expression starting with an operator uses ans as the left operand:

[ 100 ]: / 4
[ 25 ]: ^ 2
[ 625 ]:

Implicit multiplication

A number, variable, or closing parenthesis immediately before ( multiplies:

2(3 + 1)      →   8      (same as 2 * (3 + 1))
(2 + 1)(4)    →  12
2(3)(4)       →  24

Unary minus

-5
-(3 + 2)      →  -5
--5           →   5

Unary minus has lower precedence than ^ and .^, matching MATLAB/Octave:

-3 ^ 2        →  -9    % same as -(3^2), not (-3)^2
-x .^ 2       →  -(x .^ 2)
(-3) ^ 2      →   9    % use parentheses to negate before raising

Matrix operators

When one or both operands are matrices, the same operators apply with element-wise or broadcast semantics:

See Matrices for full details.

Functions & Constants

One-argument functions

Notes

sqrt(x) — x must be ≥ 0. Passing a negative value returns NaN (no error is raised).

floor, ceil, round — All three return a floating-point result, not an integer type.
round uses round-half-away-from-zero: round(0.5) → 1, round(-0.5) → -1.
Compare: floor(-2.5) → -3, ceil(-2.5) → -2, round(-2.5) → -3.

sign(x) — Returns NaN when x is NaN (sign of NaN is undefined).

log(x) — Natural logarithm (base e), MATLAB/Octave-compatible. Returns NaN for x < 0 and -Inf for x = 0. No error is raised.
log2(x) — Base-2 logarithm. log10(x) — Base-10 logarithm.
For an arbitrary base see log(x, base).

sin, cos, tan — Expect x in radians. To convert from degrees: deg * pi / 180.
tan(x) is undefined at x = π/2 + n·π; it returns ±Inf at those points.

asin(x), acos(x) — Domain is [−1, 1]; values outside return NaN.
To get degrees: multiply the result by 180/pi.

atan(x) — Handles all finite inputs; returns a value in the open interval (−π/2, π/2).
It cannot determine the quadrant because it only sees the ratio y/x. Use atan2(y, x) when you need a four-quadrant result.

sqrt(144)           →   12
abs(-7)             →    7
floor(2.9)          →    2
ceil(2.1)           →    3
round(2.5)          →    3
sign(-5)            →   -1
log(e)              →    1     (natural log)
log2(8)             →    3
log10(1000)         →    3
exp(log(5))         →    5     (round-trip)
sin(pi / 6)         →    0.5
cos(pi / 3)         →    0.5
tan(pi / 4)         →    1
asin(0.5) * 180/pi  →   30
acos(0.5) * 180/pi  →   60
atan(1)   * 180/pi  →   45

Two-argument functions

Notes

atan2(y, x) — First argument is y (numerator), second is x (denominator).
Returns a value in the range (−π, π], correctly determining the quadrant from the signs of both arguments.
atan2(0, -1) * 180/pi → 180, whereas atan(-0/-1) * 180/pi → 0.

mod(a, b) vs rem(a, b) — Both compute the remainder after division, but differ in sign when the operands have opposite signs:

mod(-1, 3)   →   2    (result has the sign of 3, in range [0, 3))
rem(-1, 3)   →  -1    (result has the sign of -1)

mod guarantees the result is in [0, b) for positive b, making it useful for angle wrapping and modular arithmetic. rem follows IEEE 754 remainder convention. b = 0 produces NaN.

max(a, b), min(a, b) — These two-argument forms work with scalars only. To find the maximum or minimum element of a vector or matrix, use the one-argument form max(v) / min(v) (see Vector & Data Utilities).

hypot(a, b) — Computes √(a²+b²) without intermediate overflow or underflow. Prefer hypot over sqrt(a^2 + b^2) when the values may be very large or very small.

log(x, base) — Both x and base must be positive; base must not equal 1. Negative or zero values return NaN or -Inf as with the single-argument form.

atan2(1, 1) * 180/pi   →   45
atan2(0, -1) * 180/pi  →  180
mod(370, 360)          →   10
mod(-1, 3)             →    2     (result in [0, 3))
rem(-1, 3)             →   -1     (same sign as dividend)
max(3, 7)              →    7
min(3, 7)              →    3
hypot(3, 4)            →    5
hypot(5, 12)           →   13
log(8, 2)              →    3     (log base 2 of 8)
log(100, 10)           →    2     (same as log10(100))

mod vs rem

Both compute the remainder after division, but differ in sign when the operands have opposite signs:

mod(-1, 3)   →   2    (result has the sign of 3)
rem(-1, 3)   →  -1    (result has the sign of -1)

Use mod when you want a value always in [0, b), e.g. for angle wrapping. Use rem when you need the IEEE 754 remainder.

Bitwise functions

All bitwise functions require non-negative integer arguments. They pair naturally with hex (0xFF), binary (0b1010), and octal (0o17) input literals.

Notes

bitand, bitor, bitxor — Both arguments must be non-negative integers. Floating-point values are truncated toward zero before the operation.

bitshift(a, n) — Positive n shifts left (multiply by 2ⁿ); negative n shifts right (logical, fills with zeros). Returns 0 when |n| ≥ 64. The shift count n may be negative; a must be non-negative.

bitnot(a) — Flips all bits within a 32-bit window (Octave uint32 default). Result is 2³² − 1 − a for values that fit in 32 bits.

bitnot(a, bits) — Flips bits within a window of bits width. bits must be in [1, 53] (limited to the integer precision of IEEE 754 doubles). Result is 2^bits − 1 − a.

bitand(0xFF, 0x0F)      →   15
bitor(0b1010, 0b0101)   →   15
bitxor(0xFF, 0x0F)      →  240     (0xF0)
bitshift(1, 8)          →  256     (1 << 8)
bitshift(256, -4)       →   16     (256 >> 4)
bitnot(5, 8)            →  250     (~5 within 8 bits = 0b11111010)
bitnot(0, 32)           →  4294967295   (0xFFFFFFFF)

Combining shifts and masks:

bitshift(1, 4) - 1      →   15     (0b00001111 — 4-bit all-ones mask)
bitand(0xDEAD, 0xFF00)  →  56832   (0xDE00 — extract high byte)

Empty-argument shorthand

Calling a function with empty parentheses uses ans as the argument:

[ 144 ]: sqrt()      →  12     (same as sqrt(144))
[ -7 ]:  abs()       →   7
[ 0 ]:   sin()       →   0

Constants

nan — Not a number. Any arithmetic operation involving nan returns nan. nan == nan evaluates to 0 (IEEE 754: NaN is never equal to itself). Use isnan(x) to test for NaN (see Vector & Data Utilities).

inf — Positive infinity. -inf is negative infinity. 1 / inf → 0, -inf < inf → 1, inf + inf → inf, inf - inf → nan.

ans — Holds the result of the most recent expression (assignments do not update it). ans can appear anywhere in an expression.

nan and inf are parser-level constants and cannot be overwritten by assignment.

nan + 5         % → NaN
nan == nan      % → 0   (IEEE 754: NaN is never equal to itself)
1 / inf         % → 0
-inf < inf      % → 1

ans can appear anywhere in an expression:

[ 9 ]: ans * 2 + 1    →  19
[ 9 ]: sqrt(ans)      →   3

Nesting

Functions can be nested freely:

sqrt(abs(-16))          →    4
log(exp(1))             →    1
floor(sqrt(10))         →    3
max(hypot(3,4), 6)      →    6

Functions in expressions

sqrt(144) + 3           →   15
2 * sin(pi / 6)         →    1
log10(1000) ^ 2         →    9
hypot(3, 4) * 2         →   10
atan2(1, 1) * 180 / pi  →   45

See also: Vector & Data Utilities for sum, prod, mean, norm, sort, find, and related functions.

Number Bases

Input literals

Any numeric literal can be written in hex, binary, or octal:

Mixed-base expressions work naturally:

0xFF + 0b1010        →  265
0x10 + 0o10 + 0b10   →   26

Display base

By default results are shown in decimal. Switch with a command (session-local):

The display base persists until changed and affects both the prompt and all results. To make a non-decimal base the default across all sessions, set it in config.toml.

[ 0 ]: 255
[ 255 ]: hex
[ 0xFF ]: + 1
[ 0x100 ]: dec
[ 256 ]:

Inline base suffix

Write a base keyword after an expression to evaluate it and switch the display in one step:

[ 0 ]: 0xFF + 0b1010 hex
[ 0x109 ]:

base — show all representations

[ 10 ]: base
2  - 0b1010
8  - 0o12
10 - 10
16 - 0xA

base can also be used as an inline suffix to show one result in all four bases without changing the active display base:

[ 0 ]: 255 base
2  - 0b11111111
8  - 0o377
10 - 255
16 - 0xFF
[ 255 ]:

Mixed-base display conversion

When the active display base is non-decimal and the input contains literals in other bases, the expression is automatically reprinted with all literals converted to the active base before the result is shown:

[ 0b110 ]: 2 + 0b110 + 0xa
0b10 + 0b110 + 0b1010
[ 0b10010 ]:

Variables

ccalc supports named variables. Any valid identifier can store a value.

Assignment

Use name = expr to assign. Assignments never update ans (MATLAB semantics).

Without ;, the result is displayed:

[ 0 ]: rate = 0.06 / 12
rate = 0.005
[ 0 ]: n = 360
n = 360
[ 0 ]: factor = (1 + rate) ^ n
factor = 10.9357
[ 0 ]: 200000 * rate * factor / (factor - 1)
[ 1199.10 ]:

Append ; to suppress output:

rate = 0.06 / 12;
n = 360;

Using variables

Any defined variable can appear inside an expression:

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

ans

ans is the implicit result variable — set automatically after every standalone expression (not after assignments). It is initialized to 0 at startup.

Expressions starting with an operator use ans as the left-hand operand:

[ 0 ]: 100
[ 100 ]: / 4
[ 25 ]: + 5
[ 30 ]:

Empty-argument function calls use ans as the argument:

[ 144 ]: sqrt()      →  12     (same as sqrt(144))

Constants

pi and e are pre-defined read-only constants:

View and clear

[ 0 ]: x = 10
[ 0 ]: y = 3.14
[ 0 ]: x + y
[ 13.14 ]: who
ans = 13.14
x = 10
y = 3.14
[ 13.14 ]: clear x
[ 13.14 ]: who
ans = 13.14
y = 3.14
[ 13.14 ]: clear

Workspace persistence

The workspace file is plain text, one name = value entry per line:

ans = 13.14
n = 360
rate = 0.005

Example — monthly mortgage

% REPL session
[ 0 ]: rate = 0.06 / 12;
[ 0 ]: n = 360;
[ 0 ]: factor = (1 + rate) ^ n;
[ 0 ]: 200000 * rate * factor / (factor - 1)
[ 1199.10 ]:

As a script file (assignments print unless ; suppresses them):

% Monthly mortgage payment
rate = 0.06 / 12;
n = 360;
factor = (1 + rate) ^ n;
200000 * rate * factor / (factor - 1)
fprintf('Monthly payment ($): ')
disp(ans)

Number Display Format

The format command controls how numbers are displayed in the REPL and script/pipe output. It does not affect computation — all arithmetic is done in f64 (IEEE 754 double precision).

Commands

Examples

>> format short
>> pi
3.1416

>> format long
>> pi
3.14159265358979

>> format shortE
>> pi
3.1416e+00

>> format bank
>> 1/3
0.33

>> format rat
>> pi
355/113

>> format hex
>> 1.0
3FF0000000000000

>> format +
>> [-2 0 5]
- +

>> format 4
>> 1/3
0.3333

Scope

format affects:

• disp() output
• Variable assignment display (x = 3.1416)
• The REPL prompt value

format does not affect fprintf / sprintf — those functions use their own per-call format specifiers (e.g. %f, %e, %.3f).

Automatic scientific notation

In short and long modes, numbers switch to scientific notation when:

• The exponent is less than −3 (e.g. 0.001 → 1e-03)
• The exponent is ≥ the number of significant digits

Persistent default

The default precision (used by format N and the startup default) is set in config.toml:

[display]
precision = 10

Note: format hex vs hex

These are different commands:

• format hex — shows the IEEE 754 raw bit pattern of any floating-point number as 16 uppercase hex digits (e.g. 400921FB54442D18 for pi).
• hex — switches the display base to hexadecimal for integer values (e.g. 0xFF → 255 shown as 0xFF).

Formatted Output

ccalc supports C-style formatted output via fprintf and sprintf, matching Octave/MATLAB semantics.

fprintf — print to stdout

fprintf(fmt, v1, v2, ...)

Prints formatted text to stdout. No return value — result display is suppressed. No newline is added automatically; include \n explicitly.

fprintf('pi = %.4f\n', pi)         % pi = 3.1416
fprintf('n = %d items\n', 42)      % n = 42 items

sprintf — format to string

s = sprintf(fmt, v1, v2, ...)

Same format engine as fprintf, but returns the result as a char array instead of printing it.

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

Format specifiers

Width, precision, and flags

The general form is:

%[flags][width][.precision]specifier

Examples:

fprintf('%8.3f\n',   pi)     %      3.142
fprintf('%-10s|\n', 'hi')    % hi        |
fprintf('%+.4e\n', 1000)     % +1.0000e+03
fprintf('%05d\n',    42)     % 00042
fprintf('% d\n',      5)     %  5
fprintf('%x\n',     255)     % ff
fprintf('%04X\n',   255)     % 00FF

Escape sequences

Multiple arguments and repeat behaviour

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

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

fprintf('x=%.1f  y=%.1f\n', 1, 2, 3, 4)
% x=1.0  y=2.0
% x=3.0  y=4.0

Formatted data table example

fprintf('%6s %12s %12s\n', 'time', 'position', 'velocity')
fprintf('%6s %12s %12s\n', '(s)', '(m)', '(m/s)')
fprintf('%s\n', repmat('-', 1, 32))

t = 0:0.5:2;
pos = 0.5 * 9.81 * t.^2;
vel = 9.81 * t;

for k = 1:length(t)
  fprintf('%6.1f %12.3f %12.3f\n', t(k), pos(k), vel(k))
end

Output:

  time     position     velocity
   (s)          (m)        (m/s)
--------------------------------
   0.0        0.000        0.000
   0.5        1.226        4.905
   1.0        4.905        9.810
   1.5       11.036       14.715
   2.0       19.620       19.620

See also

• format command — controls default display format for disp() and assignment output
• help io — concise in-REPL reference
• help script — full format specifier reference
• examples/formatted_output.calc — runnable example covering all specifiers

Configuration

ccalc stores persistent settings in a plain-text TOML file:

~/.config/ccalc/config.toml          # Linux / macOS
%APPDATA%\ccalc\config.toml          # Windows

The file is created automatically with defaults the first time you start the interactive REPL. You can edit it with any text editor.

Default config.toml

# ccalc configuration
# Edit this file and run 'config reload' in the REPL to apply changes.

[display]
# Default decimal precision (number of digits after the decimal point, 0–15).
precision = 10

# Default number base for output: "dec", "hex", "bin", "oct"
base = "dec"

[repl]
# Prompt templates — see the "Prompt customization" section below.
# prompt1 = "[ {ans} ]: "
# prompt2 = "  >> "

[highlight]
# Set to false to disable real-time syntax highlighting.
enabled = true
# Uncomment and set to override default colours.  Formats: named ("yellow"),
# 8-bit ("color256(220)"), truecolor ("#FFD700"), or "bold:<colour>".
# keywords = "yellow"
# numbers  = "cyan"
# strings  = "green"
# comments = "dark_gray"
# builtins = "bright_cyan"
# errors   = "red"

Settings

display.precision

Number of decimal places shown in the output. Range: 0–15. Default: 10.

Values above 15 are silently clamped to 15.

This is the same value controlled by p<N> during a session. Changes in config take effect on the next REPL start (or after config reload).

display.base

Default output base. Accepted values: "dec", "hex", "bin", "oct". Default: "dec".

Unknown values fall back to "dec" without error.

Prompt customization

The [repl] section lets you set custom prompt templates for prompt1 (the primary prompt, shown when ready for new input) and prompt2 (the secondary prompt, shown inside multi-line blocks such as if/for/while).

[repl]
prompt1 = "[ {ans} ]: "    # default
prompt2 = "  >> "           # default

Content placeholders

Color placeholders

Color codes are emitted only for the displayed prompt and do not affect cursor positioning. Any number of color/style placeholders can be combined.

Examples

[repl]
# Minimal: show counter and ans
prompt1 = "{line} [ {ans} ]: "

# Counter dimmed, ans in default colour
prompt1 = "{gray}({line}){reset} [ {ans} ]: "

# Shell-style: user@host:dir$
prompt1 = "{green}{user}@{host}{reset}:{cyan}{cwd_short}{reset}$ "

# Bold blue name, dimmed counter, ans
prompt1 = "{bold}{blue}ccalc{reset} {gray}[{line}]{reset} {ans} > "

# 24-bit orange accent colour
prompt1 = "{#FF8800}ccalc{reset} [{line}] {ans} > "

After editing config.toml, apply changes without restarting:

[ 0 ]: config reload
Config reloaded.

Syntax highlighting

The [highlight] section controls real-time input highlighting in the REPL.

[highlight]
enabled = true      # set to false to disable highlighting entirely

# Colour formats:
#   Named 4-bit  — black, red, green, yellow, blue, magenta, cyan, white
#                  bright_black (dark_gray), bright_red, bright_green,
#                  bright_yellow, bright_blue, bright_magenta,
#                  bright_cyan, bright_white
#   8-bit        — color256(N)  where N = 0..255
#   True color   — #RRGGBB     (hex, requires a true-color terminal)
#
# Prefix any value with "bold:" for bold text, e.g. "bold:yellow"

# keywords = "yellow"
# numbers  = "cyan"
# strings  = "green"
# comments = "dark_gray"
# builtins = "bright_cyan"
# errors   = "red"

Colour categories

User-defined variables and operators are shown in the terminal’s default colour.

Shadowing rules

If a name from a keyword or built-in list is assigned as a variable (e.g. end = 42), the highlighting uses default colour for that name — matching evaluation semantics.

Colour format reference

Unknown values are silently ignored and the built-in default is used instead.

REPL commands

Changes made with p<N>, hex, dec, bin, oct during a session are session-local and are not written back to config.toml.

Example

Set precision to 4 and default base to hex, then apply without restarting:

1. Edit config.toml:

   [display]
   precision = 4
   base = "hex"
   

2. In the REPL:

   [ 0 ]: config reload
   Config reloaded.
   precision:   4
   base:        hex
   [ 0x0 ]:
   

Config file location

The config command shows the full path of the file on the current system:

[ 0 ]: config
config file: /home/user/.config/ccalc/config.toml
precision:   10
base:        dec

Matrices

ccalc supports matrix literals using Octave/MATLAB bracket syntax.

Creating matrices

Separate elements with spaces or commas; separate rows with ; or a bare newline:

[1 2 3]          % row vector  (1×3)
[1; 2; 3]        % column vector  (3×1)
[1 2; 3 4]       % 2×2 matrix
[1, 2, 3]        % commas work too

A bare newline inside [...] is a row separator, identical to ;:

A = [1 2 3
     4 5 6]      % same as [1 2 3; 4 5 6]

v = [10
     20
     30]         % column vector (3×1)

Trailing % comments on a row are stripped before the newline is interpreted:

B = [100 200  % first row
     300 400] % second row

Line continuation (...) joins the next line into the same row — no row break occurs:

D = [1 2 ...
     3 4]         % same as [1 2 3 4]  (1×4 row vector)

Elements can be arbitrary expressions:

[sqrt(4), 2^3, mod(10,3)]     % [2, 8, 1]
[pi/2, pi; -pi, 0]

Assignment

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

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

Assignment does not update ans. The prompt shows the matrix size.

Arithmetic

Scalar operations

All four arithmetic operators apply element-wise between a scalar and a matrix:

2 * A             % multiply every element by 2
A / 10            % divide every element by 10
A + 1             % add 1 to every element
A ^ 2             % raise every element to the power 2

Matrix addition and subtraction

+ and - between two matrices of the same size are element-wise:

A + B
A - B

Size must match; otherwise you get an error:

[1 2] + [1 2 3]   % Error: Matrix size mismatch for '+'

Matrix multiplication

* between two matrices performs standard matrix multiplication (inner dimensions must agree):

A = [1 2; 3 4];
B = [1 0; 0 1];
A * B             % → same as A (multiply by identity)

v = [1; 2; 3];
v' * v            % dot product → 14 (1×3 times 3×1 = 1×1)
v * v'            % outer product → 3×3 matrix

Transpose

Postfix ' transposes a matrix. It binds tighter than any binary operator:

A'                % transpose of A
[1 2 3]'          % row vector → column vector (3×1)
R' * R            % for orthogonal R: gives identity

Element-wise operators

.*, ./, .^ apply the operation to each pair of corresponding elements (shapes must match):

A .* B            % element-wise product  (Hadamard product)
A ./ B            % element-wise division
A .^ 2            % square every element
v .^ 2            % same as v .* v

Note: * is matrix multiplication; .* is element-wise.

Range operator

Generate row vectors with the : operator. Range has lower precedence than arithmetic, so 1+1:5 evaluates as 2:5.

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]
5:1              % []   (empty — step in wrong direction)

Ranges work inside matrix literals — they are concatenated horizontally:

[1:4]            % [1 2 3 4]
[0, 1:3, 10]     % [0 1 2 3 10]
[1:2:7]          % [1 3 5 7]
[1:3; 4:6]       % 2×3 matrix: [1 2 3; 4 5 6]

linspace

linspace(a, b, n) generates n evenly spaced values from a to b (both endpoints included):

linspace(0, 1, 5)      % [0  0.25  0.5  0.75  1]
linspace(1, 5, 5)      % [1  2  3  4  5]
linspace(0, 1, 1)      % [1]   (single element returns b)
linspace(0, 1, 0)      % []   (empty)

Built-in functions

eye(3)            % 3×3 identity
det([1 2; 3 4])   % → -2
inv([1 2; 3 4])   % → 2×2 inverse matrix
size([1 2 3])     % → [1  3]
numel(zeros(3,4)) % → 12

Display

Matrices are displayed with right-aligned columns:

ans =
   1    2    3
   4    5    6
   7    8    9

The REPL prompt shows the size of the current ans when it is a matrix:

[ [3×3] ]: 

who and workspace

who shows matrix dimensions:

A = [2×2 double]
x = 3.14

ws (workspace save) saves only scalar variables. Matrices are not persisted.

Indexing

All indices are 1-based (Octave/MATLAB convention). If a name exists as a variable in the workspace, name(...) is always treated as indexing — variables shadow built-in function names.

Vector indexing

v = [10 20 30 40 50];

v(3)         % → 30          scalar element
v(2:4)       % → [20 30 40]  sub-vector via range
v(:)         % → [10;20;30;40;50]  all elements, column vector

Matrix indexing

A = [1 2 3; 4 5 6; 7 8 9];

A(2, 3)      % → 6           scalar at row 2, col 3
A(1, :)      % → [1 2 3]     entire row 1   (1×3)
A(:, 2)      % → [2;5;8]     entire column 2  (3×1)
A(1:2, 2:3)  % → [2 3; 5 6]  submatrix

Index expressions

Index arguments can be arbitrary expressions:

n = size(A, 2);   % number of columns
A(1, n)           % last element of row 1
A(1:2, 1+1)       % rows 1-2, column 2

end keyword

Inside any index expression, end resolves to the size of the dimension being indexed. Arithmetic on end is supported.

v = [10 20 30 40 50];
v(end)           % → 50          last element
v(end-1)         % → 40          second to last
v(end-2:end)     % → [30 40 50]  last three

A = [1 2 3; 4 5 6; 7 8 9];
A(end, :)        % → [7 8 9]     last row
A(:, end)        % → [3;6;9]     last column
A(1:end-1, 2:end) % → [2 3; 5 6] all but last row, columns 2 onward

Indexed Assignment

All index forms that work for reading also work for writing. The right-hand side can be a single scalar (broadcast to all selected positions) or a matrix/vector matching the selected size.

Scalar and slice assignment

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

2-D matrix assignment

A = zeros(4);
A(2, 3) = 7;               % single element
A(:, 1) = [1; 2; 3; 4];   % entire column
A(1, :) = [10, 20, 30, 40]; % entire row
A(2:3, 2:3) = eye(2);      % submatrix

Growing vectors

Assigning beyond the current length extends the vector and fills gaps with zeros. end+1 is the canonical Octave idiom for appending:

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

v = [1, 2, 3];
v(7) = 99;   % → [1 2 3 0 0 0 99]  (zeros fill the gap)

Assigning to a non-existent variable creates a new 1×N row vector:

fib(1) = 1;   % creates a 1×1 vector
fib(2) = 1;   % extends to 1×2
for k = 3:10
  fib(end+1) = fib(end) + fib(end-1);
end

Logical (boolean mask) indexing

A 0/1 vector whose length equals the dimension selects positions where the mask is 1. Masks can be produced by any comparison expression.

temps = [18, 22, 35, 12, 29, 41, 8, 33];

% Read: extract elements where mask is true
hot = temps(temps >= 30);   % → [35 41 33]

% Write: modify elements where mask is true
temps(temps >= 30) = 30;    % cap all hot days at 30

% Using a separate mask variable
mask = signal < 0;
signal(mask) = 0;           % half-wave rectifier

2-D matrices support logical masks as well — elements are selected in column-major order (same as Octave/MATLAB):

M = [1 2 3; 4 5 6; 7 8 9];
M(M > 5)        % → [7 8 6 9]   (column-major order)
M(M > 5) = 0;   % zero out those elements

Row separators inside matrix literals

Both ; and bare newlines act as row separators inside [...]; they are never statement separators there:

A = [1 2; 3 4];   % ; after ] suppresses output; ; inside is part of the matrix
B = [1 2
     3 4];        % newline inside [...] is a row separator; ; after ] suppresses output

Vector & Data Utilities

Special constants

nan and inf are built-in constants — they behave like numeric literals and cannot be overwritten.

nan + 5         % → NaN    (NaN propagates through all arithmetic)
nan == nan      % → 0      (IEEE 754: NaN is never equal to itself)
inf * 2         % → inf
-inf < inf      % → 1

NaN predicates (element-wise)

All three accept a scalar or a matrix and apply element-wise, returning a result of the same shape with each element replaced by 1.0 (true) or 0.0 (false). Use these instead of == nan or == inf, which do not work as expected: nan == nan always returns 0.

isnan(nan)       % → 1
isinf(inf)       % → 1
isfinite(42)     % → 1
isfinite(nan)    % → 0

v = [1 nan 3 inf];
isnan(v)         % → [0 1 0 0]
isfinite(v)      % → [1 0 1 0]

NaN matrix constructor

nan(n)        % n×n matrix of NaN
nan(m, n)     % m×n matrix of NaN

nan(n) is shorthand for nan(n, n). The result is a matrix where every element is NaN, useful for pre-allocating arrays that must be filled before use.

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.

Notes

min(v), max(v) — The 1-argument form finds the extreme element of a vector or matrix. The 2-argument forms min(a, b) and max(a, b) compare two scalars. Both forms are available; which is used depends on the number of arguments.

any(v), all(v) — Treat any non-zero value (including negative numbers) as true, and zero as false. NaN is non-zero, so any([nan]) → 1 and all([0 nan]) → 0.

norm(v, p) — Common values of p:

• p = 1 → L1 norm: sum of absolute values
• p = 2 (default) → L2 Euclidean norm
• p = inf → L∞ norm: maximum absolute value

For scalars, norm(x) returns abs(x).

v = [1 2 3 4 5];

sum(v)            % → 15
prod(v)           % → 120
mean(v)           % → 3
min(v)            % → 1
max(v)            % → 5
any(v > 4)        % → 1
all(v > 0)        % → 1
norm(v)           % → sqrt(1+4+9+16+25) ≈ 7.416
norm([3 4])       % → 5
norm([1 2 3], 1)  % → 6   (L1 = sum of absolute values)

Column-wise on a matrix:

M = [1 2 3; 4 5 6];
sum(M)    % → [5  7  9]    one sum per column
mean(M)   % → [2.5  3.5  4.5]
min(M)    % → [1  2  3]
max(M)    % → [4  5  6]

Cumulative operations

These return an array of the same shape as the input.

Both functions accept a scalar (returned unchanged) or a vector/matrix. For a matrix the operation runs along all elements in column-major order, returning a matrix of the same shape.

cumsum([1 2 3 4])    % → [1  3  6  10]
cumprod([1 2 3 4])   % → [1  2  6  24]

% Compound interest: balance after each year
rates = [1.05, 1.08, 1.03, 1.10];
cumprod(rates)       % → cumulative growth factors

Sorting and searching

Notes

sort(v) — Sorts in ascending order only. Accepts a scalar (returned unchanged) or a vector. Passing a 2D matrix (more than one row and more than one column) returns an error; use sort on individual rows or columns instead.

find(v) — Returns a row vector of 1-based indices of elements that are non-zero (including ±Inf and NaN). Indices follow column-major order (columns first), matching MATLAB/Octave convention. Returns an empty matrix [] when no elements match.

find(v, k) — Limits the result to the first k indices. k = 0 returns []. k must be a non-negative integer.

unique(v) — Returns a 1×N row vector of distinct values, sorted in ascending order. Accepts scalars, vectors, or matrices (elements are flattened in column-major order before deduplication).

v = [3 1 4 1 5 9 2 6];

sort(v)                    % → [1 1 2 3 4 5 6 9]
unique(v)                  % → [1 2 3 4 5 6 9]

find(v > 4)                % → [5  6  8]   indices where v > 4
find(v > 4, 2)             % → [5  6]      first 2 such indices

% Typical pattern: use find with a comparison mask
idx = find(v > 3);
v(idx)                     % → elements of v greater than 3

Reshape and flip

Notes

reshape(A, m, n) — Rearranges the elements of A into a matrix with m rows and n columns. The total number of elements must be preserved: m * n must equal numel(A), otherwise an error is raised. Elements are read and written in column-major order (column by column), matching MATLAB/Octave.

fliplr(A) — Reverses the order of columns. For a row vector this reverses all elements. A scalar is returned unchanged.

flipud(A) — Reverses the order of rows. For a column vector this reverses all elements. A scalar is returned unchanged.

reshape(1:6, 2, 3)    % fills column-by-column:
                      % [1 3 5]
                      % [2 4 6]

reshape(1:6, 3, 2)    % [1 4]
                      % [2 5]
                      % [3 6]

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

flipud([1 2; 3 4])    % → [3 4; 1 2]

Diagonal

Notes

diag(v) — When v is a row or column vector of length N, creates an N×N matrix with v on the main diagonal and zeros everywhere else. A scalar input returns a 1×1 matrix.

diag(A) — When A is a matrix, extracts its main diagonal as an N×1 column vector, where N = min(rows, cols). Works on both square and non-square matrices.

These two forms are inverses of each other: diag(diag(v)) reconstructs the diagonal matrix from its diagonal.

diag([1 2 3])       % row vector → 3×3 diagonal matrix:
                    % [1 0 0]
                    % [0 2 0]
                    % [0 0 3]

diag([4; 5; 6])     % column vector → same result

A = [1 2 3; 4 5 6; 7 8 9]
diag(A)             % → [1; 5; 9]  (main diagonal as column vector)

B = [1 2 3 4; 5 6 7 8]
diag(B)             % → [1; 6]  (min(2,4) = 2 elements)

diag(diag([1 2 3])) % → [1; 2; 3]  round-trip

Example file

examples/vector_utils.calc demonstrates all of these features:

ccalc examples/vector_utils.calc

Comparison & Logical Operators

Comparison operators

Comparison operators evaluate to 1 (true) or 0 (false). They work on scalars and element-wise on matrices.

3 > 2        % 1
3 == 4       % 0
5 ~= 3       % 1
4 <= 4       % 1

Comparison has lower precedence than arithmetic — operands are fully evaluated before the comparison:

1 + 1 == 2   % 1   (1+1 = 2, then 2 == 2)
2 * 3 > 5    % 1   (2*3 = 6, then 6 > 5)

Logical NOT — ~

~expr negates a truth value:

• 0 → 1
• any non-zero → 0

~0           % 1
~1           % 0
~(3 == 3)    % 0
~(3 ~= 3)    % 1

Short-circuit AND and OR — &&, ||

&& returns 1 when both operands are non-zero. || returns 1 when at least one operand is non-zero. && binds more tightly than ||. Both operators short-circuit and are intended for scalar conditions.

1 && 1       % 1
1 && 0       % 0
0 || 1       % 1
0 || 0       % 0

1 || 0 && 0  % 1    (1 || (0 && 0))

Combining conditions

x = 2.7;
x >= 0 && x <= 3.3    % 1  — in-range check
x < 0  || x > 3.3    % 0  — out-of-range flag

% Negate the condition:
~(x >= 0 && x <= 3.3) % 0  — fault flag (0 = OK)

Element-wise logical operators — &, |, xor, not

& and | are element-wise operators — they work on matrices, always evaluate both sides (no short-circuit), and return a 0/1 matrix:

a = [1 0 1 0];
b = [1 1 0 0];

a & b                  % [1 0 0 0]   element-wise AND
a | b                  % [1 1 1 0]   element-wise OR
xor(a, b)              % [0 1 1 0]   element-wise XOR

not(a)                 % [0 1 0 1]   element-wise NOT (alias for ~)

Use &/| for matrix logical masks; use &&/|| for scalar conditions in if.

Logical mask pattern

v = [3, -1, 8, 0, 5, -2, 7];

mask = v > 0 & v < 6   % [1 0 0 0 1 0 0]

Element-wise on matrices (comparison)

When one or both operands are matrices, all comparison operators apply element-wise and return a 0/1 matrix of the same size:

v = [1 2 3 4 5];

v > 3              % [0 0 0 1 1]
v <= 3             % [1 1 1 0 0]
v == 3             % [0 0 1 0 0]
~(v > 3)           % [1 1 1 0 0]

Scalar–matrix comparison broadcasts the scalar to every element:

3 < v              % [0 0 0 1 1]
v >= 3             % [0 0 1 1 1]

Soft masking

Because masks are 0/1 matrices, multiplying a matrix by its mask zeroes out the elements that failed the condition — a pattern often called soft masking or logical selection:

v = [1 2 3 4 5];

v .* (v > 3)             % [0 0 0 4 5]   keep elements > 3

% Keep elements in [2, 4]:
lo = v >= 2;
hi = v <= 4;
v .* (lo .* hi)          % [0 2 3 4 0]

lo .* hi works as element-wise AND because the values are already 0/1.

Precedence

From lowest to highest priority:

||          logical OR  (short-circuit)
&&          logical AND (short-circuit)
|           element-wise OR
&           element-wise AND
== ~= < > <= >=   comparison (non-associative)
:           range
+ -         additive
* / .* ./   multiplicative
^ .^ **     power (right-associative)
unary + - ~ negation / logical NOT
postfix ' .' transpose / plain transpose

REPL session

[ 0 ]: 3 > 2
[ 1 ]:
[ 0 ]: 5 ~= 5
[ 0 ]:
[ 0 ]: 2 > 1 && 10 > 5
[ 1 ]:
[ 0 ]: v = [10 20 30 40 50];
[ 0 ]: v > 25
ans =
   0   0   0   1   1
[ [1×5] ]: v .* (v > 25)
ans =
    0    0    0   40   50

See also

• help logic — REPL reference with examples
• ccalc examples/logic.calc — ADC validation and resistor tolerance demo
• Matrices — element-wise operators

Complex Numbers

ccalc supports complex numbers using the same syntax as Octave/MATLAB. No special mode is needed — i and j are always available as the imaginary unit.

Creating complex numbers

3 + 4i           % 3 + 4i   — Ni suffix (no space before i/j)
3 + 4*i          % same — explicit multiply also works
3 + 4*j          % j is also the imaginary unit
complex(3, 4)    % construct from real and imaginary parts
5i               % pure imaginary: 5i
2 - 3i           % 2 - 3i

Ni suffix syntax: any decimal number immediately followed by i or j (no space, no further alphanumeric characters) is treated as a complex literal. The tokenizer expands 4i to 4 * i — the imaginary unit i must be in scope (it is always pre-seeded at startup).

Arithmetic

All standard operators work on complex numbers:

z1 = 3 + 4*i
z2 = 1 - 2*i

z1 + z2          % 4 + 2i
z1 - z2          % 2 + 6i
z1 * z2          % 11 - 2i     (a+bi)(c+di) = (ac-bd) + (ad+bc)i
z1 / z2          % -1 + 2i

Mixing complex and real scalars works naturally:

z1 + 10          % 13 + 4i
2 * z1           % 6 + 8i
z1 ^ 2           % -7 + 24i

When the imaginary part of a result is exactly zero, the value is shown and stored as a real scalar:

(1+i) * (1-i)    % 2   (not 2 + 0i)

Powers

Integer powers use binary exponentiation for exact results:

i^2              % -1    (exact)
i^3              % -i    (exact)
i^4              %  1    (exact)
(1+i)^4          % -4
(1+i)^-1         % 0.5 - 0.5i

Non-integer powers use the polar form exp((c+di)·ln(a+bi)):

i^0.5            % 0.7071067812 + 0.7071067812i   (sqrt of i)
2^(1+i)          % 1.5384778027 + 1.2779225526i

Polar form

Every complex number z = re + im*i has a polar representation z = r * (cos θ + i * sin θ), where r = abs(z) and θ = angle(z):

z = 3 + 4*i
abs(z)           % 5          (modulus |z| = sqrt(3² + 4²))
angle(z)         % 0.9272...  (argument in radians)
angle(z) * 180/pi  % 53.13°  (in degrees)

Reconstruct from polar using exp:

r = abs(z);
t = angle(z);
r * exp(1i * t)               % 3 + 4i   (Euler's formula: e^(it) = cos t + i·sin t)
complex(r*cos(t), r*sin(t))   % 3 + 4i   (equivalent, without exp)

Euler’s identity:

exp(1i * pi) + 1              % ≈ 0   (≈ 0 + 1.22e-16i — floating-point rounding)

Built-in functions

z = 3 + 4*i
real(z)          % 3
imag(z)          % 4
conj(z)          % 3 - 4i
abs(z)           % 5
angle(z)         % 0.927...
isreal(z)        % 0
isreal(5)        % 1
imag(7)          % 0

Conjugate and plain transpose

The postfix ' operator returns the conjugate of a complex scalar (matching the matrix Hermitian-transpose convention):

z = 3 + 4i
z'               % 3 - 4i   conjugate — flips imaginary sign
conj(z)          % 3 - 4i   same result

The postfix .' operator returns the plain transpose — no conjugation:

z.'              % 3 + 4i   plain transpose — imaginary part unchanged

For real scalars and matrices ' and .' give identical results. The distinction only matters for complex values.

Comparison

== and ~= compare both real and imaginary parts:

(3 + 4*i) == (3 + 4*i)    % 1
(3 + 4*i) == (3 - 4*i)    % 0
(3 + 4*i) ~= (3 - 4*i)    % 1

Ordering operators (<, >, <=, >=) return an error for complex numbers — ordering is not defined for the complex plane.

Imaginary unit variables

i and j are pre-set to 0 + 1i at startup. You can reassign them (e.g. i = 5 for a loop counter), in which case the original value is no longer available until you restart ccalc.

Complex Matrices

Any matrix literal that contains at least one complex element becomes a ComplexMatrix. Real elements are promoted automatically.

A = [1+2i, 3-4i; 5, 6+1i]   % 2×2 complex matrix
v = [1+i, 2-i, 3]            % 1×3 complex row vector

isreal distinguishes the two kinds:

isreal([1 2; 3 4])   % 1   (real matrix — no imaginary parts)
isreal(A)            % 0   (complex matrix)

Display

Every cell always shows both parts:

A(1,1)   % 1 + 2i   (not just "1+2i")
A(2,1)   % 5 + 0i   (imaginary part printed even when zero)

Arithmetic

+, -, .*, ./, .^ work element-wise. * performs matrix multiplication. Scalar / complex scalar broadcast applies to both operands:

A + B         % element-wise addition
A .* B        % element-wise multiply
A * B         % matrix multiply
2 * A         % scalar broadcast
A + [10, 20; 30, 40]   % mixed real + complex matrix

Transpose

M = [1+2i, 3+4i; 5+6i, 7+8i]
M'            % conjugate transpose (Hermitian adjoint)
M.'           % plain transpose (no conjugation)

M * M' is Hermitian — its diagonal is always real.

Element-wise built-ins on matrices

All of the scalar complex built-ins work element-wise on ComplexMatrix:

Shape functions

size, numel, length, and norm (Frobenius) all work:

C = [1+1i, 2-1i, 3; 4, 5+2i, 6-3i]
size(C)           % [2  3]
numel(C)          % 6
norm(C)           % Frobenius norm

Indexing

1-based, column-major — the same conventions as real matrices:

w = [10+1i, 20+2i, 30+3i, 40+4i]
w(2)          % 20 + 2i
w(2:3)        % [20+2i, 30+3i]
G(1,:)        % first row
G(:,2)        % second column

Indexed assignment and auto-upcast

You can assign into an existing ComplexMatrix with any index expression:

A = [1+2i, 3-4i; 5, 6+1i]
A(1,1) = 0             % write a real scalar — stays ComplexMatrix
A(2,2) = 7 - 3i        % write a complex scalar
A(1,:) = [2+i, -1+0i]  % range assignment with a complex row vector

Assigning a complex value into a real matrix automatically promotes it to ComplexMatrix (MATLAB/Octave auto-upcast semantics). Existing real entries are preserved as x + 0i:

B = zeros(3, 3)          % real Matrix
B(2, 2) = 1 + 2i         % → B is now a ComplexMatrix; B(2,2) = 1 + 2i
B(1, :) = [3-1i, 0, 2i]  % range assignment; all other entries are x + 0i

Once a variable has been promoted to ComplexMatrix, assigning a real scalar back into an element leaves it as ComplexMatrix:

B(2, 2) = 9              % stays ComplexMatrix; B(2,2) = 9 + 0i

Reduction functions

trace, diag, sum, prod, and mean all work on ComplexMatrix, following the same conventions as for real matrices.

M = [1+2i, 3+4i; 5+6i, 7+8i]

trace(M)          % 8 + 10i  (sum of diagonal: (1+2i) + (7+8i))
diag(M)           % [1+2i; 7+8i]  — diagonal as a column vector
diag(diag(M))     % 2×2 diagonal ComplexMatrix

sum(M)            % [6+8i, 10+12i]  — column sums
prod(M)           % [(1+2i)*(5+6i), (3+4i)*(7+8i)]
mean(M)           % [3+4i, 5+6i]

sum([1+2i, 3+4i, 5+6i])   % 9 + 12i  — vector collapses to scalar

Block concatenation

ComplexMatrix blocks mix freely with real Matrix blocks in horizontal and vertical concatenation:

Z = [1+2i, 3-4i; 5, 6+1i]   % 2×2 ComplexMatrix
O = ones(2, 2)

[Z, O]    % 2×4 ComplexMatrix — horizontal
[Z; O]    % 4×2 ComplexMatrix — vertical
[Z, Z; O, O]  % 4×4 block matrix

FFT output

Since Phase 27, fft() returns a ComplexMatrix (1×N row vector) rather than a cell array. Access individual bins with X(k):

X = fft([1 2 3 4])
X(1)          % 10 + 0i  (DC component)
abs(X)        % real Matrix of bin magnitudes

Example

% Euler's identity: e^(i*pi) + 1 ≈ 0
e^(i * pi) + 1        % ≈ 0  (tiny floating-point residual from sin(π))

% Roots of x^2 + 1 = 0
x1 = i
x2 = -i

% AC impedance of a series RL circuit
R = 100; L = 0.05; f = 1000;
w = 2 * pi * f;
Z = complex(R, w * L)        % 100 + 314.159i
abs(Z)                        % impedance magnitude
angle(Z) * 180/pi             % phase angle in degrees

See examples/complex_numbers.calc for a complete annotated example.

Strings

ccalc supports two string types that match MATLAB/Octave:

Char arrays

A char array is a 1×N row of character codes. Single quotes delimit it. Inside a char array, '' (two consecutive single quotes) represents a literal single quote character.

[ 0 ]: s = 'Hello'
s = Hello
[ 'Hello' ]: length(s)
[ 5 ]: size(s)
ans =
   1   5

Arithmetic — characters as ASCII codes

Char arrays convert to their ASCII codes before any arithmetic operation. The result is a numeric scalar or row vector, not a string.

[ 0 ]: 'A' + 0        % ASCII code of 'A'
[ 65 ]:
[ 0 ]: 'a' + 1        % shift by one position
[ 98 ]:
[ 0 ]: 'abc' + 0      % codes for 'a', 'b', 'c'
ans =
   97   98   99
[ 0 ]: 'abc' + 1      % shift every character
ans =
   98   99   100

Element-wise comparison returns a 0/1 row vector:

[ 0 ]: 'abc' == 'aXc'
ans =
   1   0   1

Escaped single quote

Use '' inside a char array to include a literal ':

[ 0 ]: disp('it''s fine')
it's fine

Char-array concatenation with [...]

The bracket operator concatenates char arrays horizontally — the standard MATLAB/Octave idiom for building strings dynamically:

['hello' ' world']          % → 'hello world'
['a' 'b' 'c']               % → 'abc'
['prefix_' num2str(k)]      % → 'prefix_3'  (when k = 3)

String context (first element is a char array): numeric elements are treated as Unicode code points and become characters.

['A' 66 67]                 % → 'ABC'  (65='A', 66='B', 67='C')
['A' [66 67]]               % → 'ABC'  (matrix of codes)

Numeric context (first element is numeric): char-array elements contribute their code values.

[65 'B']                    % → [65 66]
[1 'AB']                    % → [1 65 66]

Note: each space before a ' signals the start of a new string literal, matching MATLAB whitespace-aware disambiguation. ['a' 'b'] with a space between the two char arrays correctly produces 'ab'.

String objects

A string object is a scalar container — one string, not a character-by-character array. Double quotes delimit it. "" inside a string object represents a literal ". Backslash escape sequences work: \n, \t, \\, \".

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

length and numel return 1 (it is a 1×1 scalar string):

[ 0 ]: length("hello")
[ 1 ]: numel("hello")
[ 1 ]: size("hello")
ans =
   1   1

Concatenation with +

[ 0 ]: "foo" + "bar"
[ '"foobar"' ]:
[ 0 ]: a = "left"; b = " right";
[ 0 ]: a + b
[ '"left right"' ]:

Comparison

== and ~= compare entire string objects:

[ 0 ]: "hello" == "hello"
[ 1 ]:
[ 0 ]: "hello" == "world"
[ 0 ]:
[ 0 ]: "abc" ~= "ABC"
[ 1 ]:

Type checks

[ 0 ]: ischar('hello')    % 1 — it's a char array
[ 1 ]:
[ 0 ]: isstring("hello")  % 1 — it's a string object
[ 1 ]:
[ 0 ]: ischar("hello")    % 0 — string object is NOT a char array
[ 0 ]:
[ 0 ]: ischar(42)         % 0
[ 0 ]:

String built-ins

Number conversions

[ 0 ]: num2str(42)
42
[ 0 ]: num2str(3.14159)
3.1416
[ 0 ]: num2str(3.14159, 2)    % 2 decimal digits
3.14
[ 0 ]: str2double('2.718')
[ 2.718 ]:
[ 0 ]: str2double('abc')      % NaN on failure
[ NaN ]:
[ 0 ]: str2num('100')
[ 100 ]:

Concatenation

strcat works on both char arrays and string objects:

[ 0 ]: strcat('foo', 'bar')
foobar
[ 0 ]: strcat("unit: ", num2str(42), " Hz")
unit: 42 Hz

Comparison functions

[ 0 ]: strcmp('abc', 'abc')     % 1 — case-sensitive equal
[ 1 ]:
[ 0 ]: strcmp('abc', 'ABC')     % 0
[ 0 ]:
[ 0 ]: strcmpi('abc', 'ABC')    % 1 — case-insensitive
[ 1 ]:

Case and whitespace

[ 0 ]: upper('hello')
HELLO
[ 0 ]: lower('WORLD')
world
[ 0 ]: strtrim('  spaces  ')
spaces

Search and replace

[ 0 ]: strrep('the cat sat', 'cat', 'dog')
the dog sat
[ 0 ]: strrep("Hello World", "World", "ccalc")
Hello ccalc

Predicates — containment, prefix, suffix

[ 0 ]: contains('hello world', 'world')
[ 1 ]:
[ 0 ]: contains('hello', 'xyz')
[ 0 ]:
[ 0 ]: contains('Hello', 'hello', 'IgnoreCase', true)
[ 1 ]:
[ 0 ]: startsWith('hello', 'he')
[ 1 ]:
[ 0 ]: endsWith('hello', 'lo')
[ 1 ]:

Splitting and joining strings

strsplit splits a string on a delimiter and returns a cell array of char arrays:

[ 0 ]: parts = strsplit('alpha,beta,gamma', ',')
[ 0 ]: numel(parts)
[ 3 ]:
[ 0 ]: parts{1}
alpha
[ 0 ]: parts{2}
beta

Without a delimiter, strsplit splits on whitespace:

[ 0 ]: words = strsplit('hello world')
[ 0 ]: words{1}
hello

strjoin is the inverse — it joins a cell array of strings into one string:

[ 0 ]: strjoin({'a', 'b', 'c'}, ',')
a,b,c
[ 0 ]: strjoin({'x', 'y'})
x y

Integer and matrix string conversion

[ 0 ]: int2str(3.2)          % round to nearest integer, return string
3
[ 0 ]: int2str(3.7)
4
[ 0 ]: int2str(-1.5)
-2

[ 0 ]: mat2str([1 2; 3 4])   % matrix → MATLAB literal syntax
[1 2;3 4]
[ 0 ]: mat2str([10 20 30])
[10 20 30]

sprintf

Single-argument form: returns a char array with escape sequences processed.

[ 0 ]: disp(sprintf('line 1\nline 2\n'))
line 1
line 2

[ 0 ]: disp(sprintf('A\tB\tC'))
A	B	C

Regular expressions

Regular expression support is available when ccalc is built with --features regex. Without the feature, calling these functions returns an informative error message. Both names are always available for tab completion.

% Find start index of first match (1-based); [] if no match:
regexp('abc 123 def', '\d+')          % → 5

% Extract all matched substrings as a cell array:
regexp('abc 123 def 456', '\d+', 'match')   % → {'123', '456'}

% Case-insensitive search:
regexpi('Hello World', 'hello')       % → 1

% Replace all matches (replacement is always a literal string):
regexprep('foo  bar', '\s+', '_')     % → 'foo_bar'
regexprep('2024-01-15', '-', '/')     % → '2024/01/15'
regexprep('a', 'a', '$1')            % → '$1'  (not expanded)

Build with regex support:

cargo build --features regex

Displaying strings

String values display as plain text — no surrounding quotes in the output:

[ 0 ]: 'hello'
hello
[ 0 ]: "world"
world
[ 0 ]: x = strcat('value: ', num2str(42))
x = value: 42

The REPL prompt shows the string content (truncated at 15 characters) when ans is a string.

who annotates string types:

[ 0 ]: s = 'abc'; t = "hello";
[ 0 ]: who
Variables visible from the current scope:

ans = 0
s [1×3 char]
t [string]

Workspace

ws and wl do not persist string variables — the same policy as matrices and complex numbers. Only scalars are saved.

Practical example — labelled output

R = 4700;
C = 2.2e-9;
f0 = 1 / (2 * pi * R * C);

fprintf('RC filter\n')
fprintf('  R  = ')
disp(strcat(num2str(R), ' Ohm'))
fprintf('  C  = ')
disp(strcat(num2str(C * 1e9, 3), ' nF'))
fprintf('  f0 = ')
disp(strcat(num2str(f0, 5), ' Hz'))

Output:

RC filter
  R  = 4700 Ohm
  C  = 2.2 nF
  f0 = 15392 Hz

See examples/strings.calc for the full demo: ccalc examples/strings.calc

File I/O

ccalc supports file I/O using MATLAB/Octave-compatible functions. You can read and write files using low-level file handles, load and save delimiter-separated data, query the filesystem, and persist workspace variables to named files.

File handles

Open a file with fopen, write or read, then close with fclose:

fd = fopen('log.txt', 'w');
fprintf(fd, 'result: %.4f\n', 3.14159);
fclose(fd);

Supported modes:

fopen returns a file descriptor (integer ≥ 3) on success, or -1 on failure.

File descriptor 1 is stdout and 2 is stderr — they can be used with fprintf directly.

Reading lines

fd = fopen('data.txt', 'r');
line1 = fgetl(fd);    % strip trailing newline; returns -1 at EOF
line2 = fgetl(fd);
raw   = fgets(fd);    % keep trailing newline
fclose(fd);

Closing all handles

fclose('all');    % close every open file handle

Delimiter-separated data

Write and read numeric matrices as CSV or TSV files:

data = [0, 3.30, 0.012; 0.5, 3.28, 0.015; 1.0, 3.25, 0.018];

dlmwrite('measurements.csv', data);          % comma-separated (default)
dlmwrite('measurements.tsv', data, '\t');    % tab-separated

loaded = dlmread('measurements.csv');        % auto-detect delimiter
loaded = dlmread('measurements.tsv', '\t'); % explicit delimiter

dlmread returns a Matrix. All values in the file must be numeric; non-numeric data returns an error with the offending line number.

Auto-detection order: try , first, then \t, then whitespace.

Filesystem queries

Check whether a file or directory exists before opening it:

if isfile('data.csv')
    data = dlmread('data.csv');
end

isfolder('output/')    % 1 if directory exists, 0 otherwise

cwd = pwd()            % current working directory as a char array

exist checks variables or files:

exist('x', 'var')      % 1 if variable x is in the workspace, 0 otherwise
exist('log.txt', 'file')  % 2 if file found, 0 otherwise
exist('x')             % checks workspace first, then filesystem

The numeric codes for exist match MATLAB: 1 = variable, 2 = file.

Directory listing

dir returns a struct array where every element describes one filesystem entry.

entries = dir('.')              % list current directory
entries = dir('/path/to/dir')   % list a specific directory
entries = dir('*.csv')          % glob pattern — current directory
entries = dir('data/*.toml')    % glob with parent path
entries = dir()                 % same as dir('.')

Each element has four fields:

MATLAB compatibility: dir(path) always prepends . and .. as the first two entries (both with isdir = 1). Glob patterns do not include . or ...

A non-existent path returns an empty struct array — no error is raised.

% Print all files in examples/
entries = dir('examples');
for k = 1:numel(entries)
    e = entries(k);
    if ~e.isdir
        fprintf('%s  (%d bytes)\n', e.name, e.bytes);
    end
end

% Count .csv files in the current directory
csvs = dir('*.csv');
fprintf('%d CSV file(s) found\n', numel(csvs));

% Non-existent path → 0 entries, no error
missing = dir('/no/such/path');
fprintf('entries: %d\n', numel(missing));   % → 0

The folder field is always an absolute path using OS-native separators.

Path generation

genpath(dir) recursively walks a directory tree and returns a path string containing the root directory and all of its subdirectories (depth-first, sorted alphabetically). On Unix the entries are joined with :; on Windows with ;. Non-existent paths return an empty string.

% Get a path string covering crates/ and all of its subdirectories
p = genpath('crates');
fprintf('%s\n', p)

% Typical use: add all subdirectories of a library to the search path
addpath(genpath('libs'))

Workspace with explicit path

Save and load workspace variables to a named file instead of the default path:

R = 4700;
C = 220e-9;
label = 'RC filter';

save('session.mat');                    % save all to named file
save('session.mat', 'R', 'C');         % save specific variables only

clear R
clear C

load('session.mat');                    % load back

fprintf('R = %g\n', R)

The path argument can be a variable holding the path string:

path = 'session.mat';
save(path);
load(path);

save and load without arguments use the default workspace path ~/.config/ccalc/workspace.toml — the same as ws and wl.

What gets saved

Example

The examples/file_io.calc file demonstrates all File I/O features end-to-end:

ccalc examples/file_io.calc

It covers: filesystem queries, writing to files with fprintf, line-by-line reading with fgetl/fgets, CSV/TSV with dlmread/dlmwrite, append mode, save/load with explicit paths and variable selection, and fopen error handling.

Control Flow

ccalc supports multi-line control flow blocks in both the interactive REPL and in script/pipe mode. All block constructs use end as the closing keyword.

REPL multi-line input

The REPL detects unclosed blocks and buffers incoming lines, displaying a continuation prompt >> until the block is complete. 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 >= 80
  grade = 'B';
elseif score >= 70
  grade = 'C';
elseif score >= 60
  grade = 'D';
else
  grade = 'F';
end
fprintf('score %d -> grade %s\n', score, grade)

A condition is truthy when:

for

for var = range_expr
  % body
end

The range expression is evaluated once. Iteration is column-by-column:

• Row vector → each element as a scalar
• M×N matrix → each column as an M×1 column vector

% Simple range
for k = 1:5
  fprintf('%d\n', k)
end

% Step range
for k = 10:-2:0
  fprintf('%d ', k)   % 10 8 6 4 2 0
end

while

while cond
  % body
end

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

break exits the innermost loop immediately. continue skips to the next iteration.

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

Compound assignment operators

All forms desugar at parse time to a plain Stmt::Assign — no new AST nodes. The RHS is a full expression: x *= 2 + 3 desugars to x = x * (2 + 3).

Limitation: ++/-- are statement-level only. Using them inside a larger expression (b = a - b--) is not supported.

switch / case / otherwise

switch expr
  case val1
    % ...
  case val2
    % ...
  otherwise     % optional
    % ...
end

No fall-through — only the first matching case executes. Works with scalars (exact ==) and strings (Str/StringObj interchangeable). break/continue propagate to the nearest enclosing loop.

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

do…until

Octave post-test loop — body always runs at least once:

do
  body
until (cond)

Parentheses around cond are optional. Closed by until, not end. break and continue work as in while.

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

run() / source()

Execute a script file in the current workspace. Variables defined in the script persist in the caller’s scope (MATLAB run semantics — not a function call):

a = 252; b = 105;
run('euclid_helper')        % looks for euclid_helper.calc, then .m
fprintf('gcd = %d\n', g)    % g was set by the helper

source('euclid_helper')     % Octave alias — identical behaviour

Extension resolution for bare names: .calc is tried first (native ccalc format), then .m (Octave/MATLAB compatibility).

Examples

See the example scripts for self-contained demos:

ccalc examples/control_flow.calc           # if/for/while/break/continue
ccalc examples/extended_control_flow.calc  # switch/do-until/run/source

User-defined Functions

ccalc supports user-defined named functions, multiple return values, and anonymous functions (lambdas) using Octave/MATLAB syntax.

Named functions

function result = name(p1, p2)
  ...
  result = expr;
end

Define a function at the top level in the REPL or in a .calc / .m script file. The function is stored in the workspace and can be called like any built-in. In script files, functions may appear anywhere — before or after the code that calls them (see Function hoisting in scripts).

Single return value

function y = square(x)
  y = x ^ 2;
end

square(5)     % 25

Multiple return values

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

[lo, hi, mu] = stats([4 7 2 9 1 5 8 3 6]);
% lo = 1   hi = 9   mu = 5

Discarding outputs

Use ~ in the assignment target to ignore individual outputs:

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

nargin — optional parameters

nargin holds the number of arguments actually passed:

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

power_fn(5)     % 25   (exp = 2 by default)
power_fn(2, 8)  % 256

return — early exit

function result = factorial_r(n)
  if n <= 1
    result = 1;
    return      % exit immediately — no further code runs
  end
  result = n * factorial_r(n - 1);
end

factorial_r(7)   % 5040

Scope

Each call gets its own isolated scope:

• The caller’s data variables are not visible inside the function.
• Parameters are bound locally.
• Other functions and lambdas from the caller’s workspace are forwarded, enabling self-recursion and mutual recursion.

function g = gcd_fn(a, b)
  while b ~= 0
    r = mod(a, b);
    a = b;
    b = r;
  end
  g = a;
end

gcd_fn(252, 105)   % 21

Anonymous functions

@(params) expr creates an anonymous function (lambda):

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

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

Lexical capture

A lambda captures the value of free variables at definition time:

rate = 0.05;
interest = @(p, n) p * (1 + rate) ^ n;

interest(1000, 10)   % 1628.89  (uses captured rate = 0.05)

rate = 0.99;         % does not affect the already-created lambda
interest(1000, 10)   % still 1628.89

Passing functions as arguments

Use @name to pass an existing function, or @(x) expr inline:

function s = midpoint(f, a, b, n)
  h = (b - a) / n;
  s = 0;
  for k = 1:n
    s += f(a + (k - 0.5) * h);
  end
  s *= h;
end

midpoint(@(x) x^2,    0, 1, 1000)    % ≈ 0.333333  (∫₀¹ x² dx)
midpoint(@(x) sin(x), 0, pi, 1000)   % ≈ 2.000001  (∫₀ᵖⁱ sin x dx)

Functions returning functions

function f = make_adder(c)
  f = @(x) x + c;
end

add5  = make_adder(5);
add10 = make_adder(10);

add5(3)         % 8
add10(7)        % 17
add5(add10(1))  % 16

Documentation comments

Place %-prefixed lines immediately after the function header to document a function (MATLAB H1-line convention). The REPL command help <name> displays them:

function t = tri(n)
% Return the nth triangular number T(n) = n*(n+1)/2.
% Usage: t = tri(n)
%
% Example:
%   tri(4)  →  10
  t = n * (n + 1) / 2;
end

>> help tri
Return the nth triangular number T(n) = n*(n+1)/2.
Usage: t = tri(n)

Example:
  tri(4)  →  10

• Any number of consecutive % lines form the doc block.
• A blank line between the function header and the first % breaks the association — only lines that immediately follow the header are collected.
• One leading space after % is stripped; remaining indentation is preserved, so % example displays as example.
• #-style comments work the same way.
• help <name> works for autoloaded functions on the path before the first call — ccalc loads the file on demand to extract the doc.

Function hoisting in scripts

In a script file (one that does not begin with a function definition), helper functions may be placed anywhere in the file — including after the code that calls them. ccalc pre-registers all top-level function definitions before executing the script body, matching MATLAB/Octave script semantics:

% main code at the top — calls a helper defined further down
result = double_it(7);
fprintf("double_it(7) = %d\n", result);   % prints: double_it(7) = 14

% helper function at the bottom
function y = double_it(x)
  y = x * 2;
end

This is the standard layout for MATLAB/Octave scripts: keep the main logic at the top and put helper functions at the bottom, where they are out of the way.

REPL difference: In the interactive REPL, functions take effect immediately when entered — a function must be defined before its first call.

Function files and autoload

A .calc (or .m) file that begins with a function definition is a function file. ccalc handles it differently from a script:

• Only the primary function (the first one) is exposed to the caller’s workspace.
• Any additional functions in the file are local helpers — invisible outside the file, but available to the primary function (MATLAB-style scoping).
• When a function name is called that is not in the workspace, ccalc automatically searches for <name>.calc / <name>.m on the current directory and the session path, loads it, and calls it — no explicit source() required.

% bisect.calc — primary function + private helper
function [c, k] = bisect(fun, a, b, tol)
% help text goes here, right after the function line
  steps = ceil(log2((b - a) / tol));
  [c, k] = bisect_r(fun, a, b, 0, steps);   % calls local helper
end

function [c, k] = bisect_r(fun, a, b, k, maxSteps)
  % bisect_r is local — not visible outside bisect.calc
  ...
end

If bisect.calc is on the path, calling bisect(...) without any source() works automatically:

[c, k] = bisect(@(x) x^2 - 2, 1, 2, 1e-8)   % bisect.calc auto-loaded

source('bisect.calc') still works for explicit loading.

Testing with assert

assert checks a condition and throws an error if it is false. Use it in scripts and function files to catch programming mistakes early.

% assert(cond) — error if cond is 0, NaN, or empty
assert(1 == 1)            % passes — silently returns
assert(2 > 3)             % fails: "assert: condition is false"

% assert(expected, actual) — error if values differ (element-wise)
assert(sqrt(4), 2)        % passes
assert([1 2], [1 3])      % fails: "assert: values differ"

% assert(expected, actual, tol) — error if |expected - actual| > tol
assert(pi, 3.14159, 1e-4) % passes — within tolerance
assert(pi, 3.14, 1e-4)    % fails — difference 0.00159 > 1e-4

assert works on scalars, vectors, and matrices. For numeric comparisons the element-wise absolute difference is checked; for matrices the check applies to every element.

Full example

ccalc examples/user_functions.calc

See also: help userfuncs for the in-REPL reference, and Control Flow for if, for, while, break, and return.

Cell Arrays

A cell array is a heterogeneous 1-D container: each element can hold any value — scalar, matrix, string, complex number, function handle, or even another cell array.

Creating cell arrays

c = {1, 'hello', [1 2 3]};    % cell literal — comma-separated expressions
d = cell(5);                   % 1×5 cell pre-filled with zeros
e = cell(2, 4);                % 1×8 cell pre-filled with zeros (1-D, m*n slots)

Brace indexing — reading elements

Use c{i} (curly braces, 1-based) to retrieve the content of element i:

c = {42, 'hello', [1 2 3]};

c{1}    % → 42       (scalar)
c{2}    % → hello    (char array)
c{3}    % → [1 2 3]  (matrix)

Note: c(i) with round parentheses returns an error — brace indexing c{i} is required to get the element’s value.

Assigning to elements

c{2} = 'world';      % replace existing element
c{5} = pi;           % auto-grows: elements 4–5 are zero-filled
numel(c)             % 5

Predicates and size

varargin — variadic input

Declare the last parameter as varargin to collect all extra call arguments into a cell array:

function s = sum_all(varargin)
  s = 0;
  for k = 1:numel(varargin)
    s += varargin{k};
  end
end

sum_all(1, 2, 3)        % 6
sum_all(10, 20)         % 30
sum_all()               % 0  (empty varargin cell)

Fixed and variadic parameters can be mixed:

function show(label, varargin)
  fprintf('[%s]', label)
  for k = 1:numel(varargin)
    fprintf(' %g', varargin{k})
  end
  fprintf('\n')
end

show('A', 1, 2, 3)    % [A] 1 2 3
show('B', 100)         % [B] 100

varargout — variadic output

Declare the sole output variable as varargout (a cell array) and the caller receives one output value per cell element:

function varargout = first_n(v, n)
  for k = 1:n
    varargout{k} = v(k);
  end
end

[a, b, c] = first_n([10 20 30 40], 3)   % a=10  b=20  c=30

case {v1, v2} — multi-value switch cases

Inside a switch block, a cell array case matches if the switch expression equals any element of the cell:

switch x
  case {1, 2, 3}
    disp('small')
  case {4, 5, 6}
    disp('medium')
  otherwise
    disp('large')
end

cellfun — apply a function to a cell

cellfun(f, c) applies f to each element of cell c. Returns a Matrix when all results are scalar; otherwise returns a Cell.

c = {1, 4, 9, 16, 25};
cellfun(@sqrt, c)             % [1  2  3  4  5]
cellfun(@(x) x * 2, c)       % [2  8  18  32  50]

arrayfun — apply a function to a numeric vector

arrayfun(f, v) applies f to each element of matrix v. Returns a same-shape matrix (function must return a scalar per element).

arrayfun(@(x) x^2, [1 2 3 4])        % [1  4  9  16]
arrayfun(@(x) x > 2, [1 2 3 4])      % [0  0  1   1]

@funcname — function handles

@funcname creates a callable that forwards its arguments to funcname. Works with any built-in or user-defined function:

f = @sqrt;
g = @abs;

f(16)     % 4
g(-7.5)   % 7.5

cellfun(@sqrt, {1, 4, 9})   % [1  2  3]
arrayfun(@abs, [-1 -2 3])   % [1  2  3]

Compose handles via a capturing lambda:

compose = @(f, g) @(x) f(g(x));
sqrt_abs = compose(@sqrt, @abs);
sqrt_abs(-9)    % 3   ( sqrt(abs(-9)) )

Function pipelines

Store a sequence of function handles in a cell array and apply them in order:

function y = apply_pipeline(x, pipeline)
  y = x;
  for k = 1:numel(pipeline)
    f = pipeline{k};
    y = f(y);
  end
end

pipeline = {@(x) x + 1, @(x) x * 2, @sqrt};
apply_pipeline(5, pipeline)   % sqrt((5+1)*2) = sqrt(12) ≈ 3.4641

Workspace

Cell arrays are not saved by ws/save — same policy as matrices and complex values. who shows them as:

c = {1×4 cell}

See also

• help cells — in-REPL reference
• help userfuncs — varargin/varargout in the context of user functions
• ccalc examples/cell_arrays.calc — annotated 9-section example

containers.Map

containers.Map is a string-keyed associative array — a lookup table that maps string keys to values of any type. It is the ccalc equivalent of Python’s dict or JavaScript’s Map.

Creating a map

% Empty map
m = containers.Map();

% From two cell arrays — keys cell + values cell (must be equal length)
prices = containers.Map({'apple', 'banana', 'cherry'}, {1.5, 0.75, 2.0});

All keys must be strings (char arrays or string objects).
Values can be any type: scalar, matrix, string, cell, struct, etc.

Reading values

Use parenthesis indexing with a string key:

prices('apple')     % → 1.5
prices('banana')    % → 0.75

Accessing an absent key is an error:

prices('mango')     % error: Map key 'mango' not found

Writing values

prices('date') = 3.5;      % insert new key
prices('banana') = 0.99;   % update existing key

Count property

prices.Count    % → number of entries (read-only)

Built-in functions

m = containers.Map({'c', 'a', 'b'}, {3, 1, 2});

isKey(m, 'a')   % → 1
isKey(m, 'z')   % → 0

k = keys(m)     % → {'a', 'b', 'c'}   (sorted)
v = values(m)   % → {1, 2, 3}         (matching key order)

remove(m, 'b');
m.Count         % → 2

Iterating over a map

m = containers.Map({'x', 'y', 'z'}, {10, 20, 30});
k = keys(m);
for i = 1:m.Count
  fprintf('%s = %g\n', k{i}, m(k{i}));
end

Display

m =

  Map with 3 entries:

    'apple'  → 1.5
    'banana' → 0.75
    'cherry' → 2

Notes

• String keys only. Numeric-key maps are not supported.
• Value semantics. Assigning m2 = m creates a copy (unlike MATLAB handle semantics). Mutations to m2 do not affect m.
• Maps are not persisted by ws/save — same policy as matrices and cells.
• remove(m, k) mutates m in-place without an assignment statement, matching MATLAB handle-class behaviour as closely as possible under value semantics.

See also

Cell Arrays · Structs

Structs and Struct Arrays

A scalar struct groups named fields into a single value. Each field can hold any type — scalar, matrix, string, complex, cell array, or another struct. Fields are stored in insertion order (MATLAB-compatible behaviour using an ordered map).

Creating structs

Field assignment

Assign to name.field to create the struct and set the field in one step:

pt.x = 3;
pt.y = 4;
pt.z = 0;

If the variable does not yet exist it is created as an empty struct and then the field is added. Assigning to a non-existent nested path creates all intermediate levels automatically:

car.engine.hp = 190;       % car and car.engine are both created here
car.dims.length_m = 4.76;

struct() constructor

Build a struct from key–value pairs:

s = struct('x', 1, 'y', 2)     % two fields
p = struct('name', 'Alice', 'score', 98.5)
e = struct()                    % empty struct (zero fields)

Arguments must come in pairs (name, value). The name must be a string ('single-quoted' or "double-quoted").

Reading fields

Use the same . notation:

pt.x          % 3
pt.y          % 4

car.engine.hp          % 190
car.dims.length_m      % 4.76

Chaining works to any depth. Accessing a field that does not exist is an error.

Dynamic field access

Use s.(expr) to read or write a field whose name is computed at runtime. The expression inside .(...) must evaluate to a string:

fname = 'x';
s.x = 10;
s.(fname)           % 10 — equivalent to s.x

s.(fname) = 99;     % write: equivalent to s.x = 99
s.x                 % 99

This is especially useful when iterating over a list of field names:

stats.min  = -3.14;
stats.max  =  9.81;
stats.mean =  2.71;

fields = {'min', 'max', 'mean'};
for k = 1:numel(fields)
  fprintf('  %s = %g\n', fields{k}, stats.(fields{k}))
end

Or when building a struct from parallel name/value arrays:

keys   = {'x', 'y', 'z'};
values = {10,  20,  30};
pt = struct();
for k = 1:numel(keys)
  pt.(keys{k}) = values{k};
end
pt.y    % 20

An inline string literal also works: s.('fieldname').

The field expression must evaluate to a string; passing a number produces an error: "Dynamic field name must be a string".

Built-in utilities

s.a = 1;  s.b = 2;  s.c = 3;

fn = fieldnames(s)       % {'a'; 'b'; 'c'}
fn{1}                    % a
numel(fn)                % 3

isfield(s, 'b')          % 1
isfield(s, 'z')          % 0

s2 = rmfield(s, 'b');
fieldnames(s2)           % {'a'; 'c'}

isstruct(s)              % 1
isstruct(42)             % 0

Display

s =

  scalar structure containing the fields:

    x: 3
    y: 4
    engine: [1×1 struct]
    data: [1×100 double]

Nested structs and non-scalar values are shown inline as [1×1 struct], [M×N double], or {1×N cell}. Access the field directly to see its full contents.

Structs in functions

Pass and return structs like any other value:

function d = distance(pt)
  d = sqrt(pt.x^2 + pt.y^2 + pt.z^2);
end

p = struct('x', 1, 'y', 2, 'z', 2);
distance(p)    % 3

Build structs inside functions the same way:

function v = make_vec3(x, y, z)
  v.x = x;  v.y = y;  v.z = z;
end

u = make_vec3(1, 0, 0);
u.x    % 1

Nested structs

config.server.host = 'localhost';
config.server.port = 8080;
config.db.name     = 'prod';
config.db.timeout  = 30;

config.server.host    % localhost
config.db.timeout     % 30

fieldnames returns only the top-level fields:

fieldnames(config)    % {'server'; 'db'}

Workspace

Structs are not saved by ws / save — the same policy as matrices, complex values, and cell arrays.

who displays structs as:

s = [1×1 struct]

Struct arrays

A struct array is a 1-D array of structs that all share the same field schema. Use indexed assignment to create and grow the array:

pts(1).x = 1;  pts(1).y = 0;
pts(2).x = 3;  pts(2).y = 4;
pts(3).x = 0;  pts(3).y = 5;

numel(pts)     % 3
isstruct(pts)  % 1
pts(2).x       % 3

Access an element by index — it returns a scalar struct:

p = pts(1);
p.x      % 1
p.y      % 0

pts(3).y   % 5  (chained access also works)

Field collection

Applying .field to the array (without an index) collects that field across all elements:

xs = pts.x;   % [1 3 0]   — 1×3 row vector (all scalars)
ys = pts.y;   % [0 4 5]

dists = (xs .^ 2 + ys .^ 2) .^ 0.5;   % [1 5 5]

If the field holds non-scalar values, the result is a cell array instead of a matrix.

Building in a loop

Struct arrays grow automatically:

for k = 1:5
  data(k).value = k * k;
  data(k).label = num2str(k);
end

vals = data.value;   % [1 4 9 16 25]
sum(vals)            % 55

String fields → cell array

When a collected field holds strings, the result is a cell array:

roster(1).name = 'Alice';  roster(1).score = 92;
roster(2).name = 'Bob';    roster(2).score = 78;

names  = roster.name;    % {'Alice', 'Bob'}  — cell array
scores = roster.score;   % [92 78]           — matrix

names{1}      % Alice
mean(scores)  % 85

Built-in utilities on struct arrays

fieldnames, isfield, rmfield, numel, size, length, and isstruct all work on struct arrays the same way they do on scalar structs.

fn = fieldnames(pts);
fn{1}               % x
numel(fn)           % 2
isfield(pts, 'x')   % 1
isfield(pts, 'z')   % 0

Display

pts =

  1×3 struct array with fields:
    x
    y

A single-element struct array ([1×1 struct]) displays its full field values like a scalar struct.

See also

• help structs — in-REPL reference
• help cells — cell arrays, varargin/varargout
• ccalc examples/structs.calc — annotated scalar struct example
• ccalc examples/struct_arrays.calc — annotated struct array example
• ccalc examples/dyn_field_demo.m — dynamic field access examples

Error Handling

ccalc provides MATLAB-compatible error handling so scripts can recover from runtime errors without crashing the session.

Raising errors

error('message')                   % plain message
error('expected %d, got %d', 2, n) % formatted (same as fprintf)
warning('result may be inaccurate') % prints to stderr, continues

try / catch / end

try
  result = risky_computation(x)
catch e
  fprintf('failed: %s\n', e.message)
  result = default_value
end

• If the try body succeeds, catch is skipped.
• catch e binds a struct with field message to the catch variable.
• Anonymous catch (no variable) silently handles the error.
• try with no catch silently swallows errors.

Inline fallback: try(expr, default)

n = try(str2num(s), 0)      % 0 if s is not a valid number
x = try(inv(A), eye(n))     % identity matrix if A is singular

The default is only evaluated if expr raises an error.

Protected call: pcall

[ok, val] = pcall(@func, arg1, arg2)
if ok
  % use val
else
  fprintf('error: %s\n', val)
end

Returns [1, result] on success and [0, message] on failure.

Last error message

lasterr()      % message from most recent error
lasterr('')    % clear

“Did you mean?” hints

When a name is not found, ccalc compares it against all known variable names and built-in function names using edit distance. If a close match exists (at most 2 edits away), it is shown as a suggestion:

>> sqrtt(4)
Error: Unknown function 'sqrtt'; did you mean 'sqrt'?

>> my_valu + 1
Error: Undefined variable 'my_valu'; did you mean 'my_value'?

No suggestion is shown when no close match exists.

Source location in error messages

Errors inside block statements, function bodies, and scripts executed via run()/source() include a near line N suffix pointing to the failing line:

Error: Undefined variable: 'v' near line 3

The line number is 1-based and relative to the immediately enclosing block or function body, matching Octave’s convention.

When an error propagates through nested blocks the innermost location is kept — outer wrappers do not overwrite it. Inside a catch block, e.message contains the original message without the near line suffix.

See help errors for the full reference.

Variable Scoping

ccalc provides four mechanisms to control visibility and lifetime of variables across function calls and files.

global — shared workspace storage

Declare the same name in every function that needs to share it. Changes in one function are immediately visible in all others and in the base workspace.

function reset_counter()
  global g_count
  g_count = 0;
end

function increment(step)
  global g_count
  g_count = g_count + step;
end

function n = read_counter()
  global g_count
  n = g_count;
end

reset_counter()
increment(1)
increment(1)
increment(1)
read_counter()   % 3

Typical use cases: configuration objects, counters, accumulators shared by multiple functions without threading the value through every argument list.

persistent — per-function long-lived storage

A persistent variable keeps its value between calls to the same function. On the very first call the variable is []; use isempty() to initialise it.

function n = how_many_calls()
  persistent call_count
  if isempty(call_count)
    call_count = 0;
  end
  call_count += 1;
  n = call_count;
end

how_many_calls()   % 1
how_many_calls()   % 2
how_many_calls()   % 3

Memoization

Persistent variables are ideal for caching computed results. The write-through semantics ensure that recursive calls see each other’s cache updates immediately:

function f = fib_memo(n)
  persistent cache
  if isempty(cache)
    cache = zeros(1, 100);
    cache(1) = 1;  cache(2) = 1;
  end
  if cache(n) ~= 0
    f = cache(n);
    return
  end
  cache(n) = fib_memo(n-1) + fib_memo(n-2);
  f = cache(n);
end

fib_memo(30)   % 832040  (computed in O(n) time, not O(2^n))

Contrast with global: a persistent variable is private to its function — no other function can read or write it. A global variable is shared by any function that declares it.

private/ — directory-scoped helpers

Functions placed in a private/ sub-directory are visible only to scripts and functions in the parent directory. Any other caller receives an “Unknown function” error.

mylib/
  normalize.calc     ← can call clamp() and lerp()
  private/
    clamp.calc       ← invisible outside mylib/
    lerp.calc        ← invisible outside mylib/

% normalize.calc — parent can call private helpers directly
function y = normalize(data, lo, hi)
  span = hi - lo;
  for k = 1:numel(data)
    y(k) = lerp(0, 1, (clamp(data(k), lo, hi) - lo) / span);
  end
end

private/ directories are not added to the session search path even when a parent directory is included in config.toml or via addpath. The privacy boundary is enforced by the file-system layout, not by any configuration.

Packages (+pkg/) — named namespaces

A directory whose name starts with + is a package. Functions inside are invisible at the top level and must be called with the package prefix:

pkg.function(args)

Layout

+utils/
  clamp.calc          % utils.clamp(x, lo, hi)
  lerp.calc           % utils.lerp(a, b, t)
+geom/
  circle_area.calc    % geom.circle_area(r)
  rect_area.calc      % geom.rect_area(w, h)

Usage

utils.clamp(-3, 0, 10)       % 0
utils.clamp( 5, 0, 10)       % 5
utils.lerp(0, 100, 0.25)     % 25

geom.circle_area(1)          % 3.14159...
geom.rect_area(4, 5)         % 20

% Packages compose naturally with each other and with regular expressions
x = utils.clamp(utils.lerp(-10, 20, 0.5), 0, 10);   % 5

Nested packages

Sub-directories inside a package directory that also start with + form nested packages:

+geom/
  +solid/
    sphere_vol.calc   % geom.solid.sphere_vol(r)

geom.solid.sphere_vol(3)   % 4/3 * pi * 27

Autoload

Package functions are loaded on the first call. The search follows the standard path order: calling script’s directory → CWD → session path. No source() call is needed.

Summary

Full example

ccalc examples/scoping/scoping.calc

See also: help scoping for the in-REPL reference, and User-defined Functions.

Statistics & Random Numbers

Random number generation

Use rng(seed) at the start of any script that needs reproducible output.

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.

v = [2 4 4 4 5 5 7 9];
mean(v)      % 5.0
std(v)       % sample std ≈ 2.138
std(v, 1)    % population std = 2.0
median(v)    % 4.5
mode(v)      % 4

Shape statistics

These functions measure the shape of a distribution (symmetry and peakedness). Both use the population (biased) central-moment formula.

Returns 0 for a scalar or constant vector; kurtosis returns NaN for constant data. Column-wise on M×N matrices, same as std / var.

v = [2 4 4 4 5 5 7 9];
skewness(v)    % 0.656  (slight right skew)
kurtosis(v)    % 2.781  (slightly platykurtic)

% Symmetric data → skewness exactly 0:
skewness(1:10)   % 0
kurtosis(1:10)   % 1.776

Percentiles and spread

v = [1 2 3 4 5 6 7 8];
prctile(v, 50)          % 4.5  (median)
prctile(v, [25 75])     % [2.75  6.25]  (quartiles)
iqr(v)                  % 3.5

z = zscore([2 4 6]);    % z = [-1  0  1]

Outlier detection (1.5 × IQR rule)

q1 = prctile(data, 25);
q3 = prctile(data, 75);
fence_lo = q1 - 1.5 * iqr(data);
fence_hi = q3 + 1.5 * iqr(data);
outliers = data(data < fence_lo | data > fence_hi);

Histogram

hist prints an ASCII bar chart to stdout and returns Void. histc returns a count vector for user-supplied bin edges.

hist(data)           % 10 bins (default)
hist(data, 20)       % 20 bins

edges = [0 10 20 30 40 50];
counts = histc(data, edges)

histc bin semantics: bin i counts elements where edges(i) <= x < edges(i+1); the last bin counts x == edges(end) exactly.

Normal distribution

All six functions work element-wise on scalars and matrices.

normcdf(0)                        % 0.5
normcdf(1) - normcdf(-1)          % 0.6827  (68% rule)
normcdf(2) - normcdf(-2)          % 0.9545  (95% rule)
normcdf(3) - normcdf(-3)          % 0.9973  (99.7% rule)

% Probability that X ~ N(50, 10) falls between 40 and 60:
normcdf(60, 50, 10) - normcdf(40, 50, 10)   % ≈ 0.6827

The relationship between normcdf and erf:

normcdf(x) = 0.5 * (1 + erf(x / sqrt(2)))

Full example

% Generate 200 samples from N(50, 10) and analyse them.
rng(7)
n    = 200;
data = 50 + 10 * randn(1, n);

fprintf('mean     = %.4f\n', mean(data))
fprintf('std      = %.4f\n', std(data))
fprintf('median   = %.4f\n', median(data))
fprintf('IQR      = %.4f\n', iqr(data))
fprintf('skewness = %.4f\n', skewness(data))
fprintf('kurtosis = %.4f\n', kurtosis(data))

% Percentile table
pct = prctile(data, [5 25 50 75 95]);
fprintf('P5/P25/P50/P75/P95 = %.1f  %.1f  %.1f  %.1f  %.1f\n', ...
  pct(1), pct(2), pct(3), pct(4), pct(5))

% ASCII histogram
hist(data, 12)

See the full demo at examples/statistics.calc.

Linear Algebra

ccalc supports a comprehensive set of matrix decompositions and properties. By default all operations are implemented in pure Rust (no external dependencies). An optional BLAS build links against the system OpenBLAS for faster matrix multiply and solve on larger matrices — see Performance / BLAS below.

All decompositions use [a, b] = f(x) multi-output assignment syntax. Single-output forms are also available for convenience.

QR decomposition

qr(A) factors a matrix as A = Q * R, where Q is orthogonal and R is upper triangular.

[Q, R] = qr(A)    % Q: m×m orthogonal, R: m×n upper triangular
R = qr(A)         % single-output: R only

The full Q returned by ccalc is always m×m. For least-squares problems with an overdetermined system, extract the “thin” (economy) factors:

A = [1 2; 3 4; 5 6];            % 3×2 overdetermined
[Q, R] = qr(A);
Q1 = Q(:, 1:2);                  % first n columns
R1 = R(1:2, :);                  % first n rows (2×2 square)

b = [1; 2; 3];
c = R1 \ (Q1' * b);              % least-squares solution

Verification:

norm(Q' * Q - eye(3), 'fro')     % ≈ 0  (Q orthogonal)
norm(Q * R - A, 'fro')           % ≈ 0  (exact factorisation)

LU decomposition

lu(A) factors a square matrix with partial pivoting: PA = LU, where P is a permutation matrix, L is unit lower triangular, and U is upper triangular.

[L, U, P] = lu(A)   % PA = LU
U = lu(A)           % single-output: U only

B = [2, 1, -1; -3, -1, 2; -2, 1, 2];
[L, U, P] = lu(B);
norm(P * B - L * U, 'fro')       % ≈ 0

x = B \ [8; -11; -3];            % backslash uses LU internally

Cholesky decomposition

chol(A) returns the upper triangular Cholesky factor R such that A = R’ * R. The input must be symmetric positive definite (SPD). An error is returned otherwise.

A = [4 2 2; 2 5 3; 2 3 6];
R = chol(A);
norm(R' * R - A, 'fro')          % ≈ 0

Cholesky is about twice as fast as LU for SPD systems and also serves as a positive-definiteness test.

Singular value decomposition (SVD)

svd(A) computes the decomposition A = U * S * V’.

s = svd(A)                       % singular values as a column vector (descending)
[U, S, V] = svd(A)               % full: U (m×m), S (m×n diagonal), V (n×n)
[U, S, V] = svd(A, 'econ')       % economy: U (m×k), S (k×k), V (n×k)

C = [1 2 3; 4 5 6; 7 8 9];       % rank-2 matrix
s = svd(C);
fprintf('rank = %d\n', rank(C))   % 2

[U, S, V] = svd(C);
norm(U * S * V' - C, 'fro')      % ≈ 0
norm(U' * U - eye(3), 'fro')     % ≈ 0  (U orthogonal)

% Rank-1 approximation (best in Frobenius sense)
C1 = S(1,1) * (U(:,1) * V(:,1)');

Eigendecomposition

eig(A) returns eigenvalues and eigenvectors.

d = eig(A)           % eigenvalues as a column vector
[V, D] = eig(A)      % V: eigenvectors (columns), D: diagonal eigenvalue matrix

The decomposition satisfies A * V = V * D, i.e. A * V(:,k) = D(k,k) * V(:,k) for each eigenpair k.

S = [4 1 0; 1 3 1; 0 1 2];      % symmetric
[V, D] = eig(S);

% Check residual for each eigenpair
for k = 1:3
  r = norm(S * V(:,k) - D(k,k) * V(:,k));
  fprintf('residual %d: %.2e\n', k, r)
end

Complex eigenvalues

Non-symmetric real matrices can have complex conjugate eigenvalue pairs. eig(A) detects these automatically and returns a ComplexMatrix N×1 column vector. Use real() and imag() to inspect the parts, and all(real(d) < 0) for continuous-time stability checks.

% Rotation matrix — eigenvalues are exactly ±i
Rot = [0, -1; 1, 0];
d = eig(Rot)             % ComplexMatrix [0+1i; 0-1i]

% Damped oscillator (omega=2, zeta=0.3) — stable complex pair
A = [0, 1; -4, -1.2];
d = eig(A)
fprintf('stable: %d\n', all(real(d) < 0))   % 1

% Unstable system (trace > 0 → at least one Re(λ) > 0)
U = [0.5, 1; -1, 0.3];
d = eig(U)
fprintf('stable: %d\n', all(real(d) < 0))   % 0

When all eigenvalues are real (e.g. for symmetric matrices), eig returns a plain real Matrix column vector as before. The [V, D] = eig(A) two-output form is available for real eigenvalues only; it returns an error when complex pairs are detected.

% Polynomial roots via companion matrix
% p(x) = x^4 + 2x^3 + 4x^2 + 3x + 1  →  coefficients [c0,c1,c2,c3] = [1,3,4,2]
c = [1, 3, 4, 2];
n = length(c);
C = zeros(n, n);
for k = 1:n-1
    C(k+1, k) = 1;
end
C(:, n) = -c';
roots_p = eig(C)    % ComplexMatrix — roots of the polynomial

Matrix properties

Numerical rank

rank(A) counts the singular values above the threshold ε × σ_max × max(m, n) (where ε = 2.2×10⁻¹⁶, the double precision machine epsilon).

rank([1 2 3; 4 5 6; 7 8 9])     % → 2  (third row is sum of first two)
rank(eye(4))                      % → 4

Null space

null(A) returns an orthonormal basis for the null space of A — the set of vectors x such that A*x = 0.

N = null([1 2 3; 4 5 6; 7 8 9]);
norm(([1 2 3; 4 5 6; 7 8 9]) * N)   % ≈ 0

Column-space basis

orth(A) returns an orthonormal basis for the column space of A (the range or image of A).

Q = orth([1 2 3; 4 5 6; 7 8 9]);   % 3×2 (rank 2 matrix → 2 basis vectors)
norm(Q' * Q - eye(2), 'fro')        % ≈ 0  (Q has orthonormal columns)

Condition number

cond(A) returns the 2-norm condition number σ_max / σ_min. A large condition number means the matrix is nearly singular and linear systems involving it may be sensitive to small perturbations.

cond(eye(3))                        % → 1.0  (perfectly conditioned)
cond([1 1; 1 1.0001])               % → ~40000  (nearly singular)

Pseudoinverse

pinv(A) computes the Moore-Penrose pseudoinverse via SVD. For full-rank square matrices it coincides with inv(A). For rank-deficient or non-square matrices it gives the minimum-norm least-squares solution.

A = [1 2 3; 4 5 6; 7 8 9];         % rank 2
Ap = pinv(A);
norm(A * Ap * A - A, 'fro')         % ≈ 0  (fundamental property)
rank(Ap)                             % → 2  (same as rank(A))

Matrix norms

M = [1 2; 3 4; 5 6];
norm(M)           % 9.5255  (largest singular value)
norm(M, 'fro')    % 9.5394  (sqrt(1+4+9+16+25+36))
norm(M, 1)        % 12.0    (max column sum: max(1+3+5, 2+4+6))
norm(M, inf)      % 11.0    (max row sum: max(1+2, 3+4, 5+6))

Tip: negative elements in matrix literals

A space before a minus sign inside [...] can be parsed as subtraction rather than a negative element. Use commas to be unambiguous:

A = [2, 1, -1; -3, -1, 2]   % safe: comma disambiguates
A = [2 1 -1; ...]            % risky: '1 -1' parses as 1 - 1 = 0

Performance / BLAS

By default ccalc uses pure-Rust matrix arithmetic. This is fast enough for matrices up to a few hundred rows, but for larger work (500×500 and above) linking against the system BLAS gives a significant speedup.

Building with BLAS

Requires OpenBLAS installed on the system:

# Linux (Debian/Ubuntu)
sudo apt install libopenblas-dev

# macOS (Homebrew)
brew install openblas

# Windows — install via vcpkg or use blas-static (see below)

Then build ccalc with the feature enabled:

cargo build --release --features blas

For a fully static binary with no OpenBLAS runtime dependency:

cargo build --release --features blas-static

All functions work identically in both builds — --features blas only changes the underlying kernel for *, inv, \, and the decompositions; the API is unchanged.

Example

ccalc examples/linear_algebra.calc

The example script covers all functions above with numerical verification of each decomposition and matrix property.

JSON

ccalc can encode and decode JSON data using two built-in functions. These functions are available when ccalc is built with the json feature flag.

Requires the json feature:

cargo build --release --features json

Without this flag, calling jsondecode or jsonencode returns an error message explaining how to enable the feature.

Decoding JSON

jsondecode(str) parses a JSON string and returns a ccalc value.

s = jsondecode('{"x": 1, "y": [1, 2, 3]}')
% s is a struct with fields x and y
s.x      % → 1
s.y      % → [1 2 3]  (1×3 matrix row vector)

Type mapping

Arrays containing only numbers (and null values, which become NaN) decode to a Matrix row vector. Arrays with mixed types (numbers, strings, nested objects, etc.) decode to a Cell.

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

Nested data

Nested JSON objects become nested structs:

data = jsondecode('{"person": {"name": "Alice", "age": 30}}');
data.person.name   % → 'Alice'
data.person.age    % → 30

Reading from a file

Combine with fileread to decode a JSON file:

raw = fileread('data.json');
data = jsondecode(raw);

Encoding JSON

jsonencode(val) encodes a ccalc value to a compact JSON string.

s.x = 1;
s.y = [1 2 3];
jsonencode(s)   % → '{"x":1.0,"y":[1.0,2.0,3.0]}'

Type mapping

Scalar(Inf) and Scalar(-Inf) cannot be represented in JSON and produce an error. Complex, Lambda, and Function values also produce an error.

jsonencode(42)            % → '42.0'
jsonencode('hello')       % → '"hello"'
jsonencode([1 2 3])       % → '[1.0,2.0,3.0]'
jsonencode({1, 'a'})      % → '[1.0,"a"]'

Writing to a file

s.result = 3.14;
fid = fopen('output.json', 'w');
fprintf(fid, '%s\n', jsonencode(s));
fclose(fid);

Roundtrip example

original = '{"name":"Bob","scores":[88,92,75]}';
data = jsondecode(original);
data.name       % → 'Bob'
data.scores     % → [88 92 75]

% Re-encode (field order preserved via IndexMap):
jsonencode(data)
% → '{"name":"Bob","scores":[88.0,92.0,75.0]}'

CSV — Tables and Matrices

ccalc provides three built-in functions for reading and writing delimiter-separated files. They extend the lower-level dlmread/dlmwrite primitives with automatic header handling, mixed-type columns, and RFC 4180 quoting.

readmatrix

readmatrix(path) reads a numeric CSV file and returns a Matrix.

A = readmatrix('data.csv')

Behaviour:

• Auto-detects the delimiter: comma → tab → whitespace.
• If the first row contains any non-numeric text it is skipped as a header. A purely numeric first row is treated as data.
• Empty cells become NaN (unlike dlmread, which uses 0.0).

% data.csv:  x,y,z\n1,2,3\n4,5,6
A = readmatrix('data.csv')
% → [1 2 3; 4 5 6]  (header row skipped)

Explicit delimiter:

A = readmatrix('data.tsv', 'Delimiter', '\t')

readtable

readtable(path) reads a CSV file where the first row is always the header and returns a Struct of columns.

T = readtable('people.csv')
T.name    % Cell of Str — one element per row
T.age     % Matrix (N×1) — numeric column

Column type rules:

Quoted fields (RFC 4180):

Fields may be enclosed in double-quotes. A comma inside a quoted field is part of the value, not a delimiter. Two consecutive "" inside a quoted field encode a literal ".

% people.csv:
%   name,city
%   "Smith, John","New York"
T = readtable('people.csv')
T.name{1}   % → 'Smith, John'
T.city{1}   % → 'New York'

Explicit delimiter:

T = readtable('data.tsv', 'Delimiter', '\t')

writetable

writetable(T, path) writes a struct table to a CSV file with a header row.

T.name  = {'Alice'; 'Bob'};
T.score = [95; 87];
writetable(T, 'output.csv')

Output:

name,score
Alice,95
Bob,87

Accepted column types:

Quoting: any cell value that contains the delimiter, a ", or a newline is automatically wrapped in double-quotes (RFC 4180). Embedded " are doubled.

T.desc = {'hello, world'; 'plain'};
T.n    = [1; 2];
writetable(T, 'out.csv')
% out.csv:
%   desc,n
%   "hello, world",1
%   plain,2

Explicit delimiter:

writetable(T, 'out.tsv', 'Delimiter', '\t')

Roundtrip example

% Write
T.city  = {'Paris'; 'Berlin'; 'Tokyo'};
T.pop   = [2161000; 3645000; 13960000];
writetable(T, 'cities.csv')

% Read back
T2 = readtable('cities.csv')
T2.city{2}   % → 'Berlin'
T2.pop(3)    % → 13960000

Differences from dlmread / dlmwrite

MAT Files

ccalc can read MATLAB Level 5/7 .mat files using load. This lets you exchange data with MATLAB, Octave, SciPy, and any other tool that writes the standard MAT format.

Requires the mat feature:

cargo build --release --features mat

Without this flag, calling load('*.mat') returns an error message explaining how to enable the feature.

Loading a MAT file

Assignment form

data = load('file.mat') reads all variables from the file and returns a Struct whose fields are the variable names.

data = load('results.mat');

data.score        % scalar variable from the file
data.readings     % matrix variable from the file
data.label        % char-array variable from the file
data.sensor.id    % struct field — nested access works directly

Access the shape of a loaded matrix:

fprintf('%dx%d\n', size(data.A, 1), size(data.A, 2))

Bare form

load('file.mat') (without an assignment) injects all variables directly into the current workspace:

load('results.mat')

% All variables are now in scope:
score
readings
sensor.gain

This is equivalent to the assignment form followed by assigning each field to a workspace variable.

Type mapping

Complex and sparse matrices are not yet supported.

Working with loaded data

Scalar

data = load('results.mat');
s = data.score;
fprintf('score = %g,  score^2 = %g\n', s, s^2)

Matrix

A = data.A;
fprintf('A is %dx%d\n', size(A, 1), size(A, 2))
fprintf('trace(A''*A) = %.1f\n', trace(A'*A))

Char array

lbl = data.label;
fprintf('label = %s\n', upper(lbl))

Struct fields

sen = data.sensor;
scaled = data.readings * sen.gain;
fprintf('scaled mean = %.2f\n', mean(scaled))

Saving MAT files

Writing .mat files is not yet supported. save('out.mat', ...) returns an informative error. Use save without a .mat extension (or ws) to persist workspace variables in ccalc’s native TOML format.

Example

The examples/mat/mat.calc file demonstrates all MAT-file features:

cargo run --release --features mat -- examples/mat/mat.calc

It covers: assignment form, scalar arithmetic, row-vector statistics, matrix algebra, char-array built-ins, struct field access, bare workspace merge, and a simple signal-analysis routine.

Generating the fixture

The example uses examples/mat/fixtures/sample.mat, which can be regenerated with:

cargo test --features mat create_example_fixture -- --ignored

Datetime & Duration

ccalc supports UTC datetime values and durations as first-class types. All timestamps are stored internally 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)                 % year, month, day
datetime(2024, 6, 1, 9, 30, 0)      % year, month, day, hour, min, sec
datetime(ts, 'ConvertFrom', 'posixtime')  % from Unix timestamp scalar

NaT is the Not-a-Time constant, analogous to NaN for scalars.

Duration constructors

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

Arithmetic

t = datetime(2024, 1, 1);
d = hours(1);
t2 = t + d;           % 2024-01-01 01:00:00
elapsed = t2 - t;     % Duration: 01:00:00

Component extractors

year(dt)     month(dt)    day(dt)
hour(dt)     minute(dt)   second(dt)

All extractors also work on DateTimeArray, returning a column vector.

Duration extractors

hours(d)          % Duration → hours as scalar
minutes(d)        % Duration → minutes as scalar
seconds(d)        % Duration → seconds as scalar
days(d)           % Duration → days as scalar
milliseconds(d)   % Duration → milliseconds as scalar

Predicates

isdatetime(x)    % 1 if x is DateTime or DateTimeArray
isduration(x)    % 1 if x is Duration or DurationArray
isnat(x)         % 1 if x is NaT (DateTime(NaN))

Formatting and conversion

datestr(dt)                    % "15-Jan-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
datenum(y, m, d)               % MATLAB serial date from components
posixtime(dt)                  % Unix timestamp as scalar

datestr pattern tokens

Array operations

Matrix literals build DateTimeArray or DurationArray when all elements are the same type:

t = [datetime(2024,1,1); datetime(2024,1,2); datetime(2024,1,3)];   % DateTimeArray
d = [hours(1); hours(2); hours(3)];                                  % DurationArray

diff(arr) computes successive differences:

• DateTimeArray → DurationArray
• DurationArray → DurationArray

t = [datetime(2024,1,1); datetime(2024,1,2); datetime(2024,1,3)];
d = diff(t);    % DurationArray of two 1-day durations

fprintf and sprintf

DateTime and Duration values format as strings with %s:

dt  = datetime(2024, 6, 1);
dur = hours(2);
fprintf('%s\n', dt)    % 2024-06-01 00:00:00
fprintf('%s\n', dur)   % 02:00:00
s = sprintf('elapsed: %s', dur);

Matrix Utilities & Set Operations

Phase 23 adds triangular-matrix extraction, tiling, Kronecker products, vector products, set-theoretic operations on vectors, and index-conversion utilities.

Triangular extraction

A = [1 2 3; 4 5 6; 7 8 9];

triu(A)        % [1 2 3; 0 5 6; 0 0 9]   upper triangular
triu(A, 1)     % [0 2 3; 0 0 6; 0 0 0]   above main diagonal
tril(A)        % [1 0 0; 4 5 0; 7 8 9]   lower triangular
tril(A, -1)    % [0 0 0; 4 0 0; 7 8 0]   below main diagonal

The optional offset k:

Tiling and Kronecker product

repmat([1 2; 3 4], 2, 3)            % 4×6 block matrix
kron([1 0; 0 1], [1 2; 3 4])        % 4×4 block-diagonal (identity scaling)

repmat(A, m, n) tiles matrix A in an m × n grid of blocks.

kron(A, B) replaces each scalar element a[i,j] of A with the block a[i,j] * B, producing a (rows_A × rows_B) by (cols_A × cols_B) result.

Vector products

cross([1 0 0], [0 1 0])   % [0 0 1]
cross([1 2 3], [4 5 6])   % [-3 6 -3]

dot([1 2 3], [4 5 6])     % 32

cross(a, b) requires both vectors to have exactly 3 elements. The result orientation (row or column) matches argument a.

dot(a, b) computes the inner product sum(a .* b) and returns a scalar.

Set operations

All set functions return sorted, unique results. NaN is never considered a member (IEEE semantics: NaN ≠ NaN).

intersect([1 3 5 7], [3 5 9])    % [3 5]
union([1 3 5], [3 5 7])          % [1 3 5 7]
setdiff([1 2 3 4 5], [2 4])      % [1 3 5]

ismember(3, [1 2 3 4])           % 1
ismember([1 6 3], [1 2 3 4])     % [1 0 1]  (element-wise)
ismember(nan, [nan])             % 0  (NaN is never a member)

Index conversion

sub2ind and ind2sub convert between row/column subscripts and 1-based column-major linear indices (MATLAB convention).

sub2ind([3 4], 2, 3)            % 8    (scalar)
sub2ind([3 4], [1 2], [1 3])    % [1 8]  (vectorised)

[r, c] = ind2sub([3 4], 8)      % r=2, c=3
[r, c] = ind2sub([3 4], [1 7])  % r=[1 1], c=[1 3]

Element repetition

repelem([1 2 3], 3)          % [1 1 1 2 2 2 3 3 3]
repelem([1 2 3], [2 1 3])    % [1 1 2 3 3 3]  (per-element counts)
repelem([1 2; 3 4], 2, 3)    % 4×6  (each element repeated 2 rows × 3 cols)

repelem(v, n) — repeat each element n times (scalar n).
repelem(v, nv) — repeat v(i) by nv(i) times (vector nv).
repelem(A, m, n) — 2-D form: repeat each element m rows and n columns.

See also

• help matrices — matrix literals and arithmetic
• help vectors — sort, find, unique, reshape
• help linalg — QR, LU, SVD, eigenvectors

Polynomial Operations & Interpolation

Polynomials are represented as row vectors of coefficients in descending degree order.

p(x) = x² − 3x + 2  →  [1, -3, 2]
p(x) = x³ − 6x² + 11x − 6  →  [1, -6, 11, -6]

Evaluation — polyval

polyval(p, x) evaluates polynomial p at scalar or vector x using Horner’s method (numerically stable, O(n) multiplications).

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

Fitting — polyfit

polyfit(x, y, n) returns the degree-n polynomial (n+1 coefficients) that best fits the data points (x, y) in the least-squares sense.

The fit is computed via a Vandermonde matrix and QR decomposition.

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

% Evaluate the fit at finer points:
xi = linspace(0, 4, 100);
yi = polyval(p, xi);

Roots — roots

roots(p) finds all roots of polynomial p using the Durand–Kerner (Weierstrass) iteration in complex arithmetic.

• All roots real → returns a real column vector (Matrix).
• Any root complex → returns a Cell of Scalar/Complex values.

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

Monic polynomial — poly

poly(r) expands the product (x − r₁)(x − r₂)… into a coefficient vector.

poly(A) computes the characteristic polynomial of square matrix A via the Faddeev–LeVerrier algorithm.

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

Convolution — conv

conv(a, b) computes the discrete linear convolution of vectors a and b. For polynomials this is equivalent to polynomial multiplication.

Result length = length(a) + length(b) − 1.

conv([1 2 3], [1 1])   % → [1 3 5 3]

Deconvolution — deconv

[q, r] = deconv(c, b) performs polynomial long division c / b.

Returns quotient q and remainder r (same length as c) satisfying:

conv(b, q) + r == c

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

Interpolation — interp1

interp1(x, y, xi) interpolates the data (x, y) at query points xi.

x must be strictly monotonically increasing. Queries outside [x(1), x(end)] return NaN (no extrapolation).

x = [0 1 2 3];
y = [0 1 4 9];

interp1(x, y, 1.5)                  % → 2.5   (linear)
interp1(x, y, [0.5 1.5 2.5])       % → [0.5 2.5 6.5]
interp1(x, y, 1.5, 'nearest')       % → 1     (closest knot)
interp1(x, y, 1.5, 'previous')      % → 1     (left step)
interp1(x, y, 1.5, 'next')          % → 4     (right step)
interp1(x, y, 99)                   % → NaN   (out of range)

FFT & Signal Processing

ccalc provides FFT-based frequency analysis through five built-in functions.

fft and ifft require the fft feature flag:

Requires the fft feature:

cargo build --release --features fft

Without this flag, calling fft or ifft returns an error message explaining how to enable the feature. fftshift, ifftshift, and fftfreq are always available.

Forward FFT — fft

fft(x) computes the Discrete Fourier Transform (DFT) of real vector x. Returns a ComplexMatrix (1×N row vector) where each element is a complex number re+im·i. Access individual bins with X(k).

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

Zero-padded FFT

fft(x, n) pads x with zeros to length n before the transform (or truncates if n < length(x)). Use to control the frequency resolution:

X = fft([1 2 3 4], 8)   % 8-point FFT of a 4-sample signal

Inverse FFT — ifft

ifft(X) computes the inverse DFT, normalised by 1/N. Accepts a ComplexMatrix (as returned by fft). When all imaginary parts are negligibly small (< 1e-12), returns a real matrix:

x = [1 2 3 4];
X = fft(x);
y = ifft(X)   % → [1 2 3 4]  (real matrix; imaginary parts dropped)

Shift DC to centre — fftshift / ifftshift

fftshift(x) performs a circular shift by floor(N/2) so that the DC component (index 1) moves to the centre of the array. Used to produce a zero-centred spectrum plot.

ifftshift(x) undoes the shift (ceil(N/2)).

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

fftshift([1 2 3 4 5])        % → [4 5 1 2 3]   (odd length)
ifftshift(fftshift([1 2 3 4 5]))  % → [1 2 3 4 5]

For 2-D matrices both dimensions are shifted simultaneously.

Frequency axis — fftfreq

fftfreq(n, d) returns a 1×n row vector of DFT sample frequencies for n points with sample spacing d seconds. The result is in cycles per unit of d.

n  = 8;
fs = 1000;              % sampling rate in Hz
d  = 1/fs;             % sample spacing in seconds
f  = fftfreq(n, d)
% → [0 125 250 375 -500 -375 -250 -125]  Hz

The formula matches NumPy/MATLAB:

f = [0, 1, ..., floor((n-1)/2), -floor(n/2), ..., -1] / (n·d)

Worked example — power spectrum

Two-tone signal: 10 Hz (amplitude 1.0) and 25 Hz (amplitude 0.5), sampled at 100 Hz for 100 points (1 second). Both tones land exactly on FFT bins (frequency resolution = 1 Hz), so there is no spectral leakage.

For a real sine of amplitude A, the one-sided magnitude is A × n/2.

fft returns a ComplexMatrix, so abs(S) gives a real matrix of element-wise magnitudes directly — no loop needed:

n  = 100;
fs = 100;
t  = (0:n-1) / fs;                        % 0, 0.01, …, 0.99 s
s  = sin(2*pi*10*t) + 0.5*sin(2*pi*25*t);
S  = fft(s);
f  = fftfreq(n, 1/fs);

% abs() on a ComplexMatrix returns a real Matrix of element-wise magnitudes.
mag = abs(S);

% Bins: 10 Hz → bin 11, 25 Hz → bin 26  (1-based; resolution = 1 Hz)
fprintf('Bin 11 @ 10 Hz :  |S| = %.2f   (expected %.2f)\n', mag(11), 1.0 * n/2)
fprintf('Bin 26 @ 25 Hz :  |S| = %.2f   (expected %.2f)\n', mag(26), 0.5 * n/2)
% Bin 11 @ 10 Hz :  |S| = 50.00   (expected 50.00)
% Bin 26 @ 25 Hz :  |S| = 25.00   (expected 25.00)

% Centred spectrum view using fftshift
f_centred   = fftshift(f);
mag_centred = fftshift(mag);

Summary

Dynamic Evaluation & Timing

eval — string execution

eval(str) executes a string as ccalc code in the current workspace. Variables defined inside the string persist in the caller’s scope, matching MATLAB/Octave semantics.

eval('x = sqrt(2)')    % x is now defined in the workspace
x                      % → 1.4142…

eval('disp(pi)')       % prints 3.14159…

Dynamic variable naming

A common idiom is building variable names at runtime with sprintf:

for k = 1:3
  eval(sprintf('v%d = k*k', k))
end
v1    % → 1
v2    % → 4
v3    % → 9

Two-argument form — catching errors

eval(try_str, catch_str) executes catch_str if try_str raises an error. The original error message is available via lasterr() inside the catch string.

eval('error(''oops'')', 'fprintf(''caught: %s\n'', lasterr())')

eval in expression context

When eval is used on the right-hand side of an assignment, it returns ans from the inner execution. Variable mutations inside do not propagate back to the caller’s workspace.

y = eval('2 + 2')    % y = 4

Nesting

eval calls can be nested. The depth limit is 64 (shared with run/source).

tic / toc — elapsed time

tic starts (or restarts) a timer. toc reads the elapsed time in seconds since the last tic.

tic
A = rand(500) * rand(500);
t = toc                           % → e.g. 0.0042  (seconds)

tic
for k = 1:1000
  x = k^2;
end
fprintf('loop: %.4f s\n', toc)

Both tic and toc can be written with or without parentheses:

tic
t = toc
% same as
tic()
t = toc()

Multiple toc calls after a single tic are valid — the timer is not reset by toc. Calling toc before any tic is an error.

See also

• help eval — reference page
• help control — control flow
• help errors — error handling

Plugins

ccalc’s built-in list is extended via a lightweight plugin system. A plugin is a separate Rust crate that implements the Plugin trait and registers itself at startup. The engine checks the plugin registry before its own built-in table, so plugins can shadow existing built-ins when needed.

Writing a plugin

Add ccalc-engine as a dependency and implement the Plugin trait:

# my-plugin/Cargo.toml
[dependencies]
ccalc-engine = { path = "../ccalc-engine" }

#![allow(unused)]
fn main() {
use ccalc_engine::env::{Env, Value};
use ccalc_engine::plugin::Plugin;

pub struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &str { "myfunc" }

    fn call(&self, _name: &str, args: &[Value], _env: &Env) -> Result<Value, String> {
        if args.is_empty() {
            return Err("myfunc: at least one argument required".into());
        }
        Ok(args[0].clone())
    }
}
}

Exporting multiple names

A single plugin registration can expose several function names. Override exported_names with a const-backed slice:

#![allow(unused)]
fn main() {
const NAMES: &[&str] = &["myfunc", "myother", "mythird"];

impl Plugin for MyPlugin {
    fn name(&self) -> &str { "myfunc" }

    fn exported_names(&self) -> &[&str] { NAMES }

    fn call(&self, name: &str, args: &[Value], _env: &Env) -> Result<Value, String> {
        // dispatch internally based on which name was called
        match name {
            "myfunc"  => Ok(Value::Void),
            "myother" => Ok(Value::Void),
            _         => Err(format!("{name}: not implemented")),
        }
    }
}
}

All exported names appear in tab completion automatically.

Registering a plugin

In your fork of crates/ccalc/src/main.rs, call register_plugin after exec::init():

#![allow(unused)]
fn main() {
fn run() {
    ccalc_engine::exec::init();
    ccalc_engine::plugin::register_plugin(Box::new(MyPlugin));
    // …
}
}

Add your crate to the workspace and as a dependency of ccalc:

# Cargo.toml (workspace root)
[workspace]
members = ["crates/ccalc", "crates/ccalc-engine", "crates/my-plugin"]

# crates/ccalc/Cargo.toml
[dependencies]
my-plugin = { path = "../my-plugin" }

Built-in plugins

ccalc-plot is the reference plugin shipped with ccalc. It registers the plot, scatter, bar, stem, xlabel, ylabel, and title names. See Phase 29 — Plot engine for rendering details.

Plot Functions

ccalc supports terminal and file-based plotting via the ccalc-plot plugin crate. Two rendering tiers are available:

Build with the desired tier:

cargo build --release --features plot          # ASCII only
cargo build --release --features plot-svg      # file export only
cargo build --release --features plot-all      # both

Without a feature flag, calling a render function returns a helpful error suggesting the rebuild command. Annotation functions (title, xlabel, ylabel, xlim, ylim, legend, grid) always succeed in every build configuration.

Chart types

All chart functions accept an optional trailing file path. When the last string argument ends in .svg or .png the chart is saved to that file (requires plot-svg). Without a file path the chart is rendered to the terminal (requires plot).

plot(y) / plot(x, y) / plot(x, M)

Connected line chart.

• y — row or column vector; x inferred as 1:numel(y) when omitted.
• M — M×N matrix: each row is drawn as a separate series. In SVG/PNG mode each series gets a distinct colour from the 7-colour Octave palette; legend labels the series.

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

% multi-series
M = [sin(x); cos(x); 0.5*sin(2*x)];
legend('sin', 'cos', '0.5 sin(2x)')
plot(x, M)

scatter(y) / scatter(x, y)

Individual point cloud — use when connecting data points would imply false continuity.

t = linspace(-2, 2, 50);
scatter(t, t.^2 + 0.3*randn(size(t)))

bar(y) / bar(x, y)

Vertical bar chart. Bars extend from y = 0; negative values drop below the baseline. Bar width is 40 % of the minimum x-spacing.

months = 1:12;
rain   = [42 38 55 61 72 80 95 90 73 58 44 40];
xlabel('month')
ylabel('mm')
bar(months, rain)

stem(y) / stem(x, y)

Discrete-sequence plot: a vertical line from y = 0 to each tip, plus a circle marker. Typical use: impulse/frequency responses and sampled signals.

n = 0:15;
stem(n, 0.8 .^ n)

stairs(y) / stairs(x, y)

Piecewise-constant (step-function) chart — each value is held until the next sample. Useful for zero-order-hold signals, quantised waveforms, and control outputs.

t = 0:0.5:4.5;
v = [0 0 1 1 2 2 1 1 0 0];
stairs(t, v)

hist(v) / hist(v, n) / hist(v, edges)

Histogram. ASCII output (character bars) requires no feature flag; SVG/PNG requires plot-svg.

data = randn(1, 200);
hist(data)          % auto bins
hist(data, 20)      % 20 uniform bins
hist(data, -3:0.5:3)   % explicit edges

loglog(x, y) / semilogx(x, y) / semilogy(x, y)

Log-scale plots. Data is transformed with log₁₀ before rendering; non-positive values are silently excluded. Axis labels are annotated with [log₁₀].

f = 10 .^ linspace(1, 5, 80);   % 10 Hz – 100 kHz
G = 1e6 * f .^ (-2);
loglog(f, G)

3D plots

plot3(x, y, z) / scatter3(x, y, z)

Three-dimensional line and point cloud plots. All three vectors must have the same length.

ASCII tier (--features plot): projects (x, y, z) onto a 2D plane using an orthographic projection with MATLAB-compatible default view angles (azimuth = −37.5°, elevation = 30°). The projected points are rendered with textplots. xlabel / ylabel / zlabel appear as labeled footer lines below the chart.

File tier (--features plot-svg): uses the plotters 3D Cartesian chart engine (build_cartesian_3d). plot3 draws a connected LineSeries; scatter3 draws filled circles at each point.

% 3D helix — ASCII
t  = linspace(0, 4*pi, 120);
title('3D helix')
xlabel('x = cos(t)')
ylabel('y = sin(t)')
zlabel('z = t/(4π)')
plot3(cos(t), sin(t), t/(4*pi))

% Lissajous 3D — save to SVG
t2 = linspace(0, 2*pi, 200);
title('Lissajous 3D')
plot3(sin(3*t2), sin(2*t2), cos(t2), 'lissajous.svg')

% 3D scatter
scatter3(randn(1,80), randn(1,80), randn(1,80), 'cloud.svg')

3D surface plots

meshgrid(x) / meshgrid(x, y)

Generates coordinate matrices for evaluating functions on a 2D grid — the standard prerequisite for surf and mesh.

[X, Y] = meshgrid(-2:0.1:2, -2:0.1:2);
Z = exp(-(X.^2 + Y.^2));   % Gaussian bell

surf(X, Y, Z) / surf(X, Y, Z, 'file.svg')

Colored 3D surface plot. X, Y, Z must all have the same dimensions (M×N from meshgrid).

ASCII tier (--features plot): projects each column’s maximum Z as a vertical bar — an elevation silhouette. Prints title, xlabel, ylabel, zlabel as header/footer. colormap is ignored.

File tier (--features plot-svg): renders the surface as a colored grid of row and column LineSeries, each segment colored by local Z value through the active colormap. Chart axes: X horizontal, Z (our height) vertical, Y depth.

[X, Y] = meshgrid(-3:0.2:3, -3:0.2:3);
Z = sin(sqrt(X.^2 + Y.^2));

title('Sine wave surface')
colormap('viridis')
surf(X, Y, Z)                          % ASCII preview

surf(X, Y, Z, 'surface.svg')          % SVG file

mesh(X, Y, Z) / mesh(X, Y, Z, 'file.png')

Wireframe 3D surface. Same API as surf; in ASCII mode the output is identical. In file mode only row lines are drawn (no column fill lines), giving a sparser wireframe appearance.

[X, Y] = meshgrid(-2:0.2:2, -2:0.2:2);
Z = X.^2 - Y.^2;            % saddle surface

colormap('jet')
mesh(X, Y, Z, 'saddle.svg')

Both functions accept the same annotations as other plot functions (title, xlabel, ylabel, zlabel, xlim, ylim, zlim, colormap).

Contour plots

Render 2D isolines (contour lines) or filled contour regions for a scalar field defined on a meshgrid.

contour(X, Y, Z) / contour(X, Y, Z, n) / contour(X, Y, Z, n, 'file')

Draws n evenly-spaced contour isolines.

• X, Y — coordinate matrices from meshgrid.
• Z — scalar-field matrix, same size as X and Y.
• n — number of contour levels (default 10). Levels are placed evenly inside the Z range (never at the exact min/max).
• Without a path: ASCII tier prints a character-art density map (dimensions from $COLUMNS × $LINES, default 80 × 24) where each character encodes the Z band of the corresponding sample point (palette: " .:-=+*#").
• With a .svg or .png path: file tier draws each isoline as a colored LineSeries, with colors cycling through the active colormap.

contourf(X, Y, Z) / contourf(X, Y, Z, n) / contourf(X, Y, Z, n, 'file')

Filled contour chart. Same API as contour.

• ASCII tier: identical to contour (character-art density map).
• File tier: colors each grid cell by its Z band using the active colormap, then draws the contour isolines on top.

Algorithm: marching squares (classic isoline extraction per 2×2 cell). The saddle-point ambiguity is resolved with the simple split convention.

[X, Y] = meshgrid(-2:0.05:2, -2:0.05:2);
Z = exp(-X .^ 2 - Y .^ 2);

% ASCII density map (10 levels)
contour(X, Y, Z)

% SVG with 8 levels
title('Gaussian bell')
xlabel('x')
ylabel('y')
contour(X, Y, Z, 8, 'gauss.svg')

% PNG filled contour
colormap('viridis')
contourf(X, Y, Z, 8, 'gauss_filled.png')

% Saddle function — shows both positive and negative regions
Z2 = X .* exp(-X .^ 2 - Y .^ 2);
colormap('hot')
contour(X, Y, Z2, 12, 'saddle.svg')

Both functions accept title, xlabel, ylabel, xlim, ylim, and colormap annotations, which are consumed by the render call.

clabel()

Enables contour level labels for the next contour or contourf call. The flag is consumed (cleared) by the render, matching the single-shot semantics of grid, colorbar, and similar state annotations.

ASCII tier: prints a Levels: … footer line after the chart listing all level values formatted to 2 decimal places.

File tier: places a text label at the midpoint of the longest marching-squares segment for each level. Label color matches the isoline color; font size scales with fontsize(n) (default 10 pt, proportional to the axis-label size).

[X, Y] = meshgrid(-2:0.05:2, -2:0.05:2);
Z = exp(-X .^ 2 - Y .^ 2);

% ASCII with level footer
clabel()
contour(X, Y, Z, 6)

% SVG with inline labels
title('Gaussian bell — labeled contours')
xlabel('x')
ylabel('y')
clabel()
contour(X, Y, Z, 8, 'gauss_labeled.svg')

% contourf also respects clabel()
colormap('viridis')
clabel()
contourf(X, Y, Z, 8, 'gauss_filled_labeled.svg')

Multi-panel layout

subplot, hold, and savefig work together to compose figures with multiple panels or overlaid series.

subplot(rows, cols, index)

Activates panel index (1-based, row-major) in a rows × cols grid. Once called, ccalc enters accumulating mode: all subsequent plot calls (plot, scatter, bar, stem, stairs, hist, fill, area, quiver) are buffered instead of rendered immediately. Annotations (title, xlabel, ylabel, xlim, ylim, legend, grid, text) set after the render call are collected for the current panel and consumed at commit time.

Calling subplot a second time commits the current panel and starts the next one. savefig commits the last panel and writes the composed figure.

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

subplot(2, 2, 1);
title('sin(x)');
plot(x, sin(x));

subplot(2, 2, 2);
title('cos(x)');
plot(x, cos(x));

subplot(2, 2, 3);
bar([3 1 4 1 5 9 2 6]);

subplot(2, 2, 4);
hist(randn(1, 200), 20);

savefig('out.svg');

hold('on') / hold('off')

Overlay multiple series in a single chart panel.

• hold('on') — enables accumulating mode; subsequent plot calls push series into the current panel without rendering.
• hold('off') — disables accumulating mode and, if no subplot is active, immediately renders the accumulated series to the terminal (ASCII tier). For file output, call savefig before hold('off').

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

% ASCII overlay: both series rendered at hold('off')
hold('on');
plot(x, sin(x));
plot(x, cos(x));
hold('off');

% File overlay via subplot + savefig
subplot(1, 1, 1);
title('sin and cos overlay');
hold('on');
plot(x, sin(x));
plot(x, cos(x));
hold('off');
savefig('overlay.svg');

savefig('path')

Commits the last pending panel and renders all accumulated panels to a single SVG or PNG file (requires --features plot-svg). The grid layout is determined by the rows × cols dimensions passed to the subplot calls.

When used without subplot (only with hold), the single panel fills the entire canvas.

False-colour images (imagesc)

Render a matrix as a heat-map — each cell is coloured according to its value.

imagesc(Z) / imagesc(Z, path)

• Z — any numeric matrix.
• Without a path: ASCII tier prints a character-art grid using 10 density characters (" .:-=+*#@█") mapped from Z_min to Z_max. Grid dimensions adapt to terminal width ($COLUMNS, default 80).
• With a .svg or .png path: file tier draws one filled Rectangle per cell, scaled to the canvas. Canvas size comes from figure(w, h) (default 800 × 600 px). Requires --features plot-svg.

colormap('name') / colormap(M)

Set the active colormap for the next imagesc call (consumed and cleared together with other FigureState annotations). Case-insensitive.

Named colormaps:

Custom colormap from matrix:

Pass an N×3 matrix where each row is an RGB control point with values in [0, 1]. The colormap is linearly interpolated between control points.

% Two-stop blue → red
colormap([0 0 1; 1 0 0])
imagesc(Z, 'heat.svg')

% Three-stop blue → yellow → red
colormap([0 0 1; 1 1 0; 1 0 0])
imagesc(Z, 'custom.svg')

colorbar()

Appends a colour-scale legend strip to the right side of the exported image (80 px wide, with 5 tick labels at 0 %, 25 %, 50 %, 75 %, 100 % of the data range). Silently ignored in ASCII mode.

% ASCII heat-map
Z = reshape(1:100, 10, 10);
imagesc(Z)

% SVG with viridis colormap and colorbar
colormap('viridis')
colorbar()
title('Signal strength')
imagesc(Z, 'heat.svg')

% Mandelbrot set — colormap changes false-colour appearance
N = 200; max_iter = 60;
x = linspace(-2.5, 1.0, N);
y = linspace(-1.2, 1.2, N);
Z = zeros(N, N);
for row = 1:N
  for col = 1:N
    c = x(col) + y(row)*1i;
    z = 0;
    for k = 1:max_iter
      if abs(z) > 2, break; end
      z = z^2 + c;
    end
    Z(row, col) = k;
  end
end
colormap('inferno')
colorbar()
title('Mandelbrot set')
imagesc(Z, 'mandelbrot.svg')

image(Z) / image(Z, path)

MATLAB alias for imagesc — identical behaviour in every way. Use image when compatibility with MATLAB scripts is preferred.

colormap('hot')
image(Z, 'heat.svg')    % same as imagesc(Z, 'heat.svg') with hot colormap

imshow(Z) / imshow(Z, path)

Displays Z as a grayscale image using clamp-to-[0,1] normalisation. Unlike imagesc, the data is not min/max scaled: values above 1.0 map to white and values below 0.0 map to black. Values in [0, 1] map directly to gray intensity.

• Typical use: images already normalised to a [0, 1] intensity range.
• ASCII tier: 10-level density palette " .:-=+*#@█".
• File tier: one gray Rectangle per cell; gray = clamp(v, 0, 1) × 255.

% Load / generate a normalised grayscale image
n = 64;
Z = rand(n, n);           % random noise in [0,1]
imshow(Z, 'noise.png')    % displayed as-is — no scaling applied

% Values outside [0,1] are clamped, not scaled
Z2 = 2 * rand(n, n);      % values in [0,2] — upper half maps to white
imshow(Z2, 'bright.png')

imshow(R, G, B) / imshow(R, G, B, path)

Displays a colour image from three separate channel matrices. R, G, and B must all have the same dimensions; each component is clamped to [0, 1].

• ASCII tier: computes luminance L = 0.299·R + 0.587·G + 0.114·B per pixel and renders the equivalent grayscale with the density palette. This produces the same output as imshow(L).
• File tier: one filled Rectangle per pixel, RGB colour from the three channel values. For a 128×128 image this produces 16 384 rectangles — use PNG output to keep file size reasonable.

n = 128;
[X, Y] = meshgrid(linspace(0, 4*pi, n), linspace(0, 4*pi, n));
C = sqrt((X - 2*pi).^2 + (Y - 2*pi).^2);  % radial ripple component

R = 0.5 + 0.5 * sin(X + C);
G = 0.5 + 0.5 * sin(Y + C / 2);
B = 0.5 + 0.5 * sin(X/2 + Y/2 + C);

title('Plasma interference (128×128)')
imshow(R, G, B, 'plasma.png')

Comparison — imagesc vs imshow:

Style strings and colors

Color specification forms

Five ways to specify a color, accepted by all plot functions that support styling:

Single-letter codes:

Additional named colors (full names only, not single-letter): orange, purple, gray / grey

Style strings for plot, scatter, fill, area

These functions accept an optional MATLAB-compatible style string before the file path. The string combines a color code, a marker code, and/or a line-style code in any order.

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

% Single-letter code: red dashed line
plot(x, sin(x), 'r--')

% Full color name
plot(x, sin(x), 'orange')

% Hex color
plot(x, cos(x), '#1A6ECC')

% 1×3 RGB matrix (values in [0, 1])
plot(x, sin(x), [0.8 0.2 0.1])

% Blue scatter with dot markers
scatter(x, cos(x), 'b.')

% Green solid line to SVG
plot(x, sin(x), 'g-', 'wave.svg')

% Red fill
fill([0, 1, 0.5], [0, 0, 1], 'r', 'tri.svg')

Color for bar, stem, hist, quiver

These functions do not use a trailing style string (to avoid ambiguity with data arguments). Use the 'color' named argument instead:

% Color name
bar([1 3 2 5 4], 'color', 'red')

% Hex color
stem(x, sin(x), 'color', '#FF8800')

% Full name in hist
hist(randn(1, 500), 20, 'color', 'purple')

% Quiver with named color
[X, Y] = meshgrid(-2:2, -2:2);
quiver(X, Y, -Y, X, 'color', 'blue')

% RGB matrix form also works
bar([1 3 2 5 4], 'color', [0.2 0.6 1.0])

Note: In ASCII (textplots) mode, color and line-style are ignored because the backend is monochrome Braille. Style specifications still parse without error.

Filled polygons and areas

fill(x, y) / fill(x, y, style) / fill(x, y, style, 'file')

Filled polygon. x and y are coordinate vectors of the polygon vertices; the shape is automatically closed (last vertex connects back to the first).

ASCII tier: prints a bounding-box density block with a ░ fill character plus an outline using textplots.

File tier: draws a plotters Polygon element filled at 40 % opacity, with the full-opacity outline drawn as a LineSeries on top.

% Filled triangle
fill([0, 1, 0.5], [0, 0, 1])

% Red-filled triangle → SVG
fill([0, 1, 0.5], [0, 0, 1], 'r', 'triangle.svg')

area(y) / area(x, y) / area(x, y, style) / area(x, y, style, 'file')

Filled area under a curve. The curve is closed along y = 0 to form a polygon (equivalent to fill with an added baseline segment).

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

% ASCII area preview
area(x, sin(x) + 1)

% Blue area under sine wave → SVG
area(x, sin(x) + 1, 'b', 'area_sine.svg')

Drawing primitives

Phase 32a adds three low-level drawing functions that complement fill and area. All three participate in hold/subplot accumulation and savefig exactly like the other chart functions.

line(x, y) / line(x, y, style) / line(x, y, style, 'file')

MATLAB-compatible alias for plot. Accepts the same arguments, style strings, and file-export path.

x = linspace(0, 2*pi, 64);
line(x, sin(x), 'b-', 'sine.svg')

patch(x, y) / patch(x, y, color) / patch(x, y, color, 'file')

MATLAB-compatible alias for fill. Draws a filled polygon from vertex vectors x and y.

% Cyan-filled triangle → SVG
patch([0, 1, 0.5], [0, 0, 1], 'c', 'triangle.svg')

rectangle(x, y, w, h) / rectangle([x y w h]) / rectangle(..., color) / rectangle(..., color, 'file')

Draws an axis-aligned filled rectangle defined by its origin (x, y), width, and height. The bounding box is converted to a 4-vertex polygon [x, x+w, x+w, x] × [y, y, y+h, y+h] and rendered via render_fill_xy.

Two input forms:

% Green rectangle (4-scalar form) → SVG
rectangle(0.1, 0.2, 0.6, 0.4, 'g', 'rect.svg')

% Magenta rectangle (vector form) → SVG
rectangle([0.1, 0.2, 0.6, 0.4], 'm', 'rect_vec.svg')

% Combined: sine curve inside a bounding box
hold('on')
line(x, sin(x), 'b-')
rectangle(0, -1, 2*pi, 2, 'k--')
title('sine + bounding box')
savefig('sine_box.svg')

See also: examples/primitives_demo/primitives_demo.calc

Statistical extensions

Phase 32b adds two statistical chart functions.

errorbar(x, y, e) / errorbar(x, y, e, style) / errorbar(x, y, e, style, 'file')

Draws a line plot with symmetric error bars: each point (x[i], y[i]) gets a vertical cap spanning [y[i] - e[i], y[i] + e[i]].

errorbar(x, y, e_low, e_high) / errorbar(x, y, e_low, e_high, style) / errorbar(x, y, e_low, e_high, style, 'file')

Asymmetric form: the lower extent is y[i] - e_low[i] and the upper extent is y[i] + e_high[i], allowing different uncertainties in each direction.

All arrays must have the same length. The optional style argument accepts the same color/line-style strings as plot. Without a file path the result is printed as a compact ASCII table with ± notation.

ASCII tier: compact table x | y ± e (or x | y + e_high - e_low).

File tier: three PathElement segments per point (vertical shaft, lower cap, upper cap) plus a Circle centre dot. Cap width = 3 % of the x-axis range.

x = 1:5;
y = [2.1, 3.4, 2.8, 4.2, 3.7];

% Symmetric — same error on each side
e = [0.3, 0.2, 0.4, 0.25, 0.35];
xlabel('Sample')
ylabel('Value')
title('Symmetric error bars')
errorbar(x, y, e, 'b', 'errorbar_sym.svg')

% Asymmetric
e_low  = [0.1, 0.3, 0.2, 0.15, 0.4];
e_high = [0.4, 0.1, 0.5, 0.3,  0.2];
errorbar(x, y, e_low, e_high, 'r', 'errorbar_asym.svg')

% Overlay errorbar on a line plot (hold mode)
hold('on')
plot(1:5, 0.8*(1:5) + 0.5, 'k--')
errorbar(x, y, e, 'b')
title('Line + error bars')
savefig('errorbar_with_line.svg')

scatter(x, y, sz, c) — per-point color form

When scatter receives four numeric arguments (x, y, sz, c), each point is colored individually by mapping the scalar c[i] through the active colormap (default: viridis).

• sz — marker radius in pixels. Either a scalar (broadcast to all points) or a vector of the same length as x.
• c — scalar color values; automatically normalized to [min(c), max(c)] before the colormap lookup.
• Change the colormap with colormap(name) before the scatter call.

ASCII tier: degrades gracefully to a monochrome textplots scatter chart.

File tier: each point is a Circle element whose fill color comes from apply_colormap_spec(c_normalized).

n  = 20;
x  = linspace(0, 2*pi, n);
y  = sin(x);
c  = cos(x);          % values drive the colormap

% Uniform size, viridis (default)
scatter(x, y, 6, c, 'scatter_viridis.svg')

% Per-point size, jet colormap
colormap('jet')
sz = 3 + 7 * (c - min(c)) / (max(c) - min(c));
scatter(x, y, sz, c, 'scatter_jet.svg')

% Two ColorScatter series in hold mode
x2 = linspace(0, 2*pi, n);
y2 = cos(x2);
hold('on')
scatter(x,  y,  5, c)
scatter(x2, y2, 5, sin(x2))
title('Two ColorScatter series')
savefig('scatter_hold.svg')

See also: examples/errorbar_demo/errorbar_demo.calc, examples/scatter_color_demo/scatter_color_demo.calc

Pie charts

Phase 32c adds pie chart support through the pie function.

pie(v) / pie(v, labels) / pie(v, explode) / pie(v, explode, labels) / pie(v, ..., 'file')

Renders a proportional pie chart from the numeric vector v. Each slice covers an angular fraction equal to v[i] / sum(v). Values must be non-negative and their sum must be positive.

Argument type detection (flexible ordering):

• Cell array of strings → slice labels.
• Numeric vector (same length as v) → per-slice explode offsets (see below).
• String ending in .svg/.png → output file path (requires plot-svg).

Explode: when explode[i] > 0, slice i is shifted radially outward by explode[i] × 0.08 × r from the chart center.

ASCII tier: horizontal bar-art table with a 20-character bar per slice. Four rotating fill characters (█ ▓ ▒ ░) visually distinguish slices; empty bar space is filled with ·; a : marker appears at the midpoint (position 10) of every bar for scale reference; exploded slices get a ◄ suffix after the label.

pie chart:
  Work      ████████··········:··········  30.0% ◄
  Sleep     █████·············:··········  20.0%
  Exercise  ████··············:··········  15.0%
  Leisure   ██████████········:··········  25.0%
  Eating    ██················:··········  10.0%

File tier: one Polygon wedge per slice built from 64 arc points plus the center point (65 vertices total). The chart is drawn in a (-1..1) × (-1..1) Cartesian space with axes and mesh hidden. Labels are placed at radius r × 1.18 using Text elements. Slices cycle through the 7-color Octave palette; set colormap('name') before calling pie to use a different palette.

v = [30, 20, 15, 25, 10];
labels = {'Work', 'Sleep', 'Exercise', 'Leisure', 'Eating'};

% ASCII output
pie(v)
pie(v, labels)

% Explode first slice outward
explode = [0.1, 0, 0, 0, 0];
pie(v, explode, labels)

% File export
pie(v, 'pie_basic.svg')
pie(v, labels, 'pie_labels.svg')
pie(v, explode, labels, 'pie_explode.svg')

See also: examples/pie_demo/pie_demo.calc

Dual Y axis

Phase 32d adds dual Y-axis support through yyaxis.

yyaxis('left') / yyaxis('right')

Switches the active Y axis. All subsequent plot, scatter, ylabel, and ylim calls are routed to that axis until the axis is switched again.

Both calls implicitly enable hold mode so that series from both sides accumulate before rendering. The chart is flushed automatically when:

• yyaxis('left') is called again while right-axis series are pending (i.e. at the start of the next dual-axis block), or
• savefig('path.svg') commits all pending panels to a file.

Call hold('off') to render the chart to the terminal immediately without starting a new block.

ASCII rendering draws both curves on a single character grid; left-axis series use . and right-axis series use *. The footer lines show the actual Y range for each axis:

Temperature and Humidity
+------------------------------------------------------------------------+
|                                          *****                         |
|                                      .***     ********                 |
|                                  ..***                *****            |
|                              ...***                        ***         |
+------------------------------------------------------------------------+
x: Time (h)
y (left)  . : Temperature (C)  [18 .. 23]
y (right) * : Humidity (%)     [60 .. 70]

SVG / PNG rendering uses the plotters DualCoordChartContext so the left and right Y axes each carry independent tick labels and optional grid lines.

t       = [0, 1, 2, 3, 4, 5];
temp_C  = [18, 19, 21, 23, 22, 20];
humid_p = [60, 62, 65, 70, 68, 64];

% ASCII output — renders automatically when the next yyaxis block begins
yyaxis('left');
ylabel('Temperature (C)');
plot(t, temp_C, 'b-');

yyaxis('right');
ylabel('Humidity (%)');
plot(t, humid_p, 'r--');

xlabel('Time (h)');
title('Temperature and Humidity');

% SVG output
yyaxis('left');           % <-- also flushes the ASCII chart above
ylabel('Temperature (C)');
plot(t, temp_C, 'b-');

yyaxis('right');
ylabel('Humidity (%)');
plot(t, humid_p, 'r--');

xlabel('Time (h)');
title('Temperature and Humidity');
savefig('examples/yyaxis_demo/output/yyaxis_basic.svg');

See also: examples/yyaxis_demo/yyaxis_demo.calc

Polar plots

polar(theta, r) / polar(theta, r, style) / polar(theta, r, 'file')

Converts polar coordinates (r, theta) to Cartesian (x, y) using x = r·cos(θ), y = r·sin(θ) and renders a connected line plot.

theta is in radians.

theta = linspace(0, 2*pi, 200);

% Unit circle
polar(theta, ones(size(theta)))

% Rose curve: r = |cos(2θ)|
polar(theta, abs(cos(2*theta)), 'rose.svg')

% Archimedean spiral: r = θ/(2π)
polar(theta, theta / (2*pi), 'spiral.svg')

Vector field plots

quiver(x, y, u, v) / quiver(x, y, u, v, 'file')

Draws a vector field: at each point (x[i], y[i]) an arrow is drawn in the direction (u[i], v[i]).

• All four arrays must have the same length (or the same total element count when meshgrid matrices are passed — they are flattened in row-major order).
• Arrow scale: the longest arrow is normalised to 80 % of the minimum grid spacing, so arrows never overlap adjacent grid cells.

ASCII tier: places a Unicode directional arrow character (→ ↗ ↑ ↖ ← ↙ ↓ ↘) at the grid position of each origin point.

File tier: each arrow is drawn as a shaft (PathElement) plus a filled triangular arrowhead at the tip.

% Simple rotational flow: u = -y, v = x
[X, Y] = meshgrid(-2:1:2, -2:1:2);
U = -Y;
V = X;

% ASCII render
title('Rotational flow')
quiver(X, Y, U, V)

% SVG export
quiver(X, Y, U, V, 'flow.svg')

Text annotations

text(x, y, 'str') / text(x, y, 'str', 'file')

Places a text label at the data coordinates (x, y).

Text annotations are stored in FigureState.annotations and are flushed alongside plot data at the next render call or at savefig / hold('off'). They do not trigger an immediate render on their own.

ASCII tier: annotations are printed below the chart as (x, y): label lines.

File tier: annotations are drawn as Text elements at their data coordinates using a 12-pt sans-serif font.

% Annotate a quiver plot
text(0.0, 0.0, 'origin')
text(2.0, 2.0, 'tip region')
quiver(x, y, u, v, 'annotated.svg')

% Annotate any plot
x = linspace(0, 2*pi, 80);
text(pi/2, 1.0, 'peak')
text(3*pi/2, -1.0, 'trough')
plot(x, sin(x), 'sine.svg')

Canvas size

File export: figure(width, height)

Sets the output canvas size in pixels for the next SVG or PNG export. Applies to all file-export functions: plot, scatter, bar, hist, fill, area, polar, quiver, surf, mesh, contour, contourf, and savefig.

• Width and height must be integers in the range 1–16384.
• The size persists across panels (like colormap) and is cleared when the figure state resets after a render.
• Has no effect in ASCII (terminal) mode — ASCII chart dimensions follow the terminal size instead (see below).

% Wide landscape chart
figure(1200, 400)
plot(x, sin(x), 'wide.svg')

% Square heatmap
figure(600, 600)
colormap('viridis')
imagesc(Z, 'square.svg')

% Multi-panel at HD resolution
figure(1920, 1080)
subplot(2, 2, 1); plot(x, sin(x)); title('sin')
subplot(2, 2, 2); plot(x, cos(x)); title('cos')
subplot(2, 2, 3); bar([1 2 3 4]);
subplot(2, 2, 4); hist(randn(1, 200), 20);
savefig('hd_grid.png')

ASCII output: terminal auto-detection

ASCII charts automatically adapt to the terminal size by reading the standard environment variables $COLUMNS (width, default 80) and $LINES (height, default 24) at render time.

Set these variables in your shell before running ccalc to get larger charts:

export COLUMNS=120
export LINES=40
ccalc

Or inline for a single script:

COLUMNS=120 LINES=40 ccalc -q myscript.calc

Figure appearance

The following functions adjust the visual appearance of the next rendered figure. Like other annotations, they are stored in FigureState and consumed by the next render call. These settings apply to SVG/PNG file output only; ASCII charts are monochrome and their geometry is fixed by the terminal size.

Theme and background color

bgcolor accepts any color specification: a color name string, a hex code '#RRGGBB', or a 1×3 RGB matrix with values in [0, 1].

theme('dark')
plot(x, sin(x), 'sin_dark.svg')

bgcolor('#F5F5F5')     % light grey background, keeps other defaults
plot(x, cos(x), 'cos_grey.svg')

Font and stroke sizes

Per-series overrides are applied via named arguments appended to a single plot call:

plot(x, y, 'r--', 'linewidth', 2)         % thick red dashed line
scatter(x, y, 'markersize', 5)             % larger dot markers
plot(x, y, 'linewidth', 1.5, 'markersize', 4)

Figure-level overrides apply to all series unless a per-series value is present:

fontsize(14)
linewidth(2)
title('Thick lines')
plot(x, sin(x), 'sin_thick.svg')

Grid color and width

Requires grid('on') to have any visible effect.

grid('on')
gridcolor('#4080FF')
gridwidth(0.5)
plot(x, sin(x), 'blue_grid.svg')

Axis mode

t = linspace(0, 2*pi, 120);
axis('equal')
plot(cos(t), sin(t), 'circle.svg')    % unit circle appears as a circle

axis('tight')
bar([3 1 4 1 5], 'tight_bar.svg')    % bars fill the chart with no margin

axis('off')
imagesc(Z, 'clean.svg')              % image only, no axis decorations

axis('equal') expands the tighter axis so data-units-per-pixel are equal on both axes. axis('tight') removes the default 5 % margin around the data range. Both apply to SVG/PNG output; ASCII charts are unaffected.

File export

Append a file path as the last string argument (after the optional style string):

imagesc always writes to a file (never prints a file path to the terminal). The colormap and colorbar annotations apply only to imagesc.

x = linspace(0, 2*pi, 200);
title('sin(x)')
xlabel('x (radians)')
ylabel('amplitude')
plot(x, sin(x), 'wave.svg')

hist(randn(1, 500), 'dist.png')

Annotation functions

Set annotations before the render call. All annotations are stored in a thread-local FigureState and consumed (cleared) by the next render call.

title('My Chart')
xlabel('time (s)')
ylabel('amplitude')
xlim([0, 10])
ylim([-1.2, 1.2])
grid('on')
plot(t, y)       % all annotations applied here, then cleared

Grid defaults to off. The grid is visible in SVG/PNG output only; ASCII charts ignore it.

Annotations not consumed before a second render call are not carried over:

title('First plot')
plot(x, y1, 'a.svg')    % title applied
plot(x, y2, 'b.svg')    % no title — state was cleared by first render

SVG/PNG chart properties

• Size (file export): 800 × 600 px by default; override with figure(width, height) (1–16384 px).
• Size (ASCII): adapts to terminal $COLUMNS × $LINES (defaults 80 × 24).
• Colours (multi-series): 7-colour Octave palette — blue, orange, yellow, purple, green, cyan, dark red — cycling as needed.
• Line plots: LineSeries (1 px, series colour).
• Scatter plots: filled circles, 3 px radius.
• Per-point color scatter (scatter(x,y,sz,c)): Circle elements; each fill color mapped through the active colormap; radius from sz (scalar or per-point vector).
• Contour labels (clabel() before contour/contourf): one Text element per level, placed at the midpoint of the longest segment; color matches the isoline; font size scales with fontsize(n).
• Error bars (errorbar): three PathElement segments (shaft + two caps) plus a Circle centre dot per data point; cap width = 3 % of x-range.
• Pie charts (pie): one Polygon wedge per slice (64 arc points + center); axes and mesh disabled; labels via Text at radius × 1.18; explode offsets along slice bisector.
• Bar charts: edge-to-edge Rectangle series; negative bars extend below baseline.
• Stem plots: PathElement vertical lines + Circle tip markers (4 px).
• Histograms: edge-to-edge Rectangle bins (blue fill).
• 3D line plots (plot3): LineSeries over (f64, f64, f64) tuples via plotters 3D Cartesian chart (build_cartesian_3d).
• 3D scatter plots (scatter3): Circle elements at each 3D coordinate.
• 3D surface plots (surf): colored row + column LineSeries grid on a 3D Cartesian chart; each line colored by local Z mean through the active colormap.
• 3D wireframe plots (mesh): row-only LineSeries grid (sparser than surf).
• False-colour images (imagesc / image): one Rectangle per matrix cell, RGB colour from the active colormap LUT; optional 80 px colorbar strip on the right.
• Grayscale images (imshow(Z)): one gray Rectangle per cell; intensity = clamp(v, 0, 1) × 255 — no min/max scaling.
• RGB images (imshow(R, G, B)): one Rectangle per pixel; colour from the three channel values clamped to [0, 1]. PNG output recommended for large images.
• Axis range: auto-computed from data with 5 % margin by default. axis('tight') removes the margin; axis('equal') enforces equal data-units/pixel; axis('off') hides all axis decorations. Single-point data uses ± 1.
• Legend: shown when legend(...) is set; drawn in the upper-right corner with a black border.

Examples

• examples/plot_file/plot_demo.calc — ASCII plot/scatter, annotations
• examples/plot_file/plot_file.calc — plot/scatter to SVG/PNG
• examples/plot_extended_file/plot_extended.calc — bar, stem, stairs, hist, loglog/semilogx/semilogy, multi-series, xlim/ylim/grid (ASCII)
• examples/plot_extended_file/plot_extended_file.calc — same chart types exported to SVG/PNG, multi-series with legend+grid, histogram variants
• examples/plot3_file/plot3_demo.calc — plot3/scatter3 ASCII 3D plots
• examples/plot3_file/plot3_file.calc — plot3/scatter3 exported to SVG/PNG
• examples/colormap/imagesc_demo.calc — imagesc with all 8 colormaps + colorbar
• examples/colormap/mandelbrot.calc — Mandelbrot set rendered with colormap('inferno')
• examples/colormap/julia.calc — Julia set rendered with colormap('magma')
• examples/surf_demo/surf_demo.calc — sine wave surface + Gaussian bell (surf)
• examples/surf_demo/mesh_demo.calc — sine wave wireframe + saddle surface (mesh)
• examples/contour_demo/contour_demo.calc — contour, contourf, and clabel() level labels on Gaussian bell + saddle
• examples/subplot_demo/subplot_demo.calc — 2×2 grid: sin, cos, bar, hist (SVG export)
• examples/hold_demo/hold_demo.calc — overlaid sin and cos series using hold on/off
• examples/fill_area_polar_demo/fill_area_polar_demo.calc — fill, area, polar, style strings
• examples/quiver_demo/quiver_demo.calc — vector field with Unicode arrow grid
• examples/color_system_demo/color_system_demo.calc — Phase 30.5 unified color system: custom colormaps, full names, hex, RGB matrix, 'color' named arg for bar/stem/hist/quiver
• examples/figure_appearance_demo/figure_appearance_demo.calc — Phase 30.6 figure appearance: theme, bgcolor, fontsize, linewidth, markersize, gridcolor, gridwidth, axis
• examples/primitives_demo/primitives_demo.calc — Phase 32a: line, patch, rectangle in hold mode and standalone
• examples/errorbar_demo/errorbar_demo.calc — Phase 32b: symmetric and asymmetric errorbar, hold-mode overlay with plot
• examples/scatter_color_demo/scatter_color_demo.calc — Phase 32b: per-point color scatter(x,y,sz,c) with viridis/jet colormaps and hold mode
• examples/pie_demo/pie_demo.calc — Phase 32c: pie chart with labels, explode, and file export
• examples/yyaxis_demo/yyaxis_demo.calc — Phase 32d: dual Y-axis — temperature vs humidity (ASCII + SVG), population vs growth rate (SVG)
• examples/contour_demo/contour_demo.calc already covers Phase 32e (clabel() calls included)
• examples/imshow_demo/imshow_demo.calc — Phase 32f: image/imshow grayscale and RGB; includes a 128×128 plasma interference pattern saved as PNG

See also

• Plugins — how the ccalc-plot plugin is registered
• Run help plot in the REPL for a compact quick reference

Architecture

Internal design of ccalc: workspace layout, data flow, module responsibilities, and design principles that guide every implementation decision.

Contents

Architecture Overview

Workspace layout

ccalc/
├── Cargo.toml                  ← [workspace] — single version source
├── crates/
│   ├── ccalc/                  ← binary crate (CLI)
│   │   └── src/
│   │       ├── main.rs         ← entry point, mode detection
│   │       ├── repl.rs         ← REPL loop, pipe mode, evaluate()
│   │       └── help.rs         ← help text
│   └── ccalc-engine/           ← library crate (computation)
│       ├── src/
│       │   ├── lib.rs          ← public API
│       │   ├── env.rs          ← Env/Value types, workspace save/load
│       │   ├── eval.rs         ← AST + evaluator + formatters + Base enum
│       │   ├── parser.rs       ← tokenizer + recursive-descent parser, Stmt enum
│       │   ├── exec.rs         ← block executor, exec_stmts(), BODY_CHUNK_CACHE
│       │   ├── io.rs           ← IoContext — file descriptor table for fopen/fgetl/etc.
│       │   └── vm/             ← bytecode compiler + stack VM (Phase 34b)
│       │       ├── mod.rs      ← Opcode, Instr (8 B), Chunk, IterState, CompileError
│       │       ├── compile.rs  ← compile(&[StmtEntry]) → Chunk; is_compilable()
│       │       └── exec.rs     ← vm_exec(chunk, env, …)
│       └── benches/
│           └── engine.rs       ← Criterion benchmark suite
└── docs/                       ← this mdBook

Data flow

User input (String)
    │
    ▼
parser::parse_stmts(input) → Vec<StmtEntry>   (AST — unchanged)
    │
    ▼
vm::compile::compile(&stmts)
    │  Ok(Chunk) ──────────────────────────────┐
    │  Err(Unsupported)                         │
    ▼                                           ▼
exec::exec_stmts (tree-walker)           vm::exec::vm_exec(chunk, env, …)
    │                                           │
    └─────────────────────┬─────────────────────┘
                          ▼
                    Value → format → stdout

exec_stmts attempts to compile the statement block on every call. If compilation succeeds the VM executes it without per-statement recursion; otherwise the tree-walker runs unchanged. The public API is unaffected.

Module responsibilities

Dependency graph

ccalc (binary)
  ├── ccalc-engine (local)
  │     ├── dirs
  │     ├── ndarray
  │     └── indexmap
  ├── rustyline
  ├── toml
  └── serde

ccalc-engine (dev / benches only)
  └── criterion

Design principles

• One binary, no runtime. The release binary is self-contained. Every new dependency requires explicit justification.
• The library is pure. ccalc-engine has no I/O, no terminal codes, no rustyline. The binary owns all user-facing interaction.
• Modern MATLAB standard (R2016b+). Where MATLAB and Octave differ, ccalc follows modern MATLAB. Example: 'text' is a char array (numeric), "text" is a string object.
• Version is defined once in [workspace.package]; both crates inherit it.
• No runtime allocations on the hot path beyond the input string itself.