Types & Units
Every value in Stof has a type. You don't have to write types down, since a value's type comes from the value itself, but you can, on fields, variables, and function parameters. A declared type casts what's assigned to it.
The Basics
bool active: true
int count: 1_000 // 64-bit integer; underscores for readability
float ratio: 0.75 // 64-bit floating point
str label: 'v1' // text
ver release: 1.2.3 // a semantic version
blob raw: |104, 105| // bytes
#[main]
fn main() {
pln(typeof self.count);
pln(self.release > 1.0.0);
pln(self.raw.utf8());
}null is a value and a type of its own, for "nothing here". Null & Initialization covers it.
Numbers
int and float work together the way you'd expect, with two things to know:
#[main]
fn main() {
pln(7 / 2); // 3: int divided by int is an int
pln(7 / 2.0); // 3.5: use a float to get a fraction
pln(85.0 == 85); // true: int and float compare by value
pln(0xFF + 0b11); // hex and binary literals
pln(1 / 0); // infinity, instead of an error
}Number methods like round return a new number and leave the original alone, so write x = x.round(2) to change x. The Number Library has them all.
Strings
Single and double quotes are the same. Backticks make a template string, and ${...} puts a value inside it:
name: 'Ada'
visits: 3
#[main]
fn main() {
pln(`${self.name} has visited ${self.visits} times`);
pln(`${self.visits}${self.visits}`); // always text: '33', not 6
pln(r#"raw: "quotes" and \n stay as written"#);
}A template string is always a string, even when every part is a number. A null inside one prints as null. \$ writes a literal dollar sign.
Casting with as
as converts a value to another type. It works between numbers, strings, booleans, and units:
#[main]
fn main() {
pln('3.5' as float);
pln(42 as str);
pln((7 as float) / 2); // inside a larger expression, wrap the cast in parentheses
}A cast that can't work throws an error, which you can catch.
Checking Types
typeof gives a value's basic type. typename gives the most specific name it has: the unit, or the type of an object:
distance: 5km
#[main]
fn main() {
pln(typeof self.distance); // float
pln(typename self.distance); // km
pln(typeof self); // obj
pln(typeof self.main); // fn
pln(typeof 3 == 'int'); // true: typeof applies to the value right after it
}Collections
Lists, maps, sets, and tuples hold other values:
list scores: [90, 85, 100]
map ages: map(('Ada', 36), ('Grace', 45))
set tags: set('core', 'stof', 'core')
(str, int) pair: ('alpha', 1)
#[main]
fn main() {
pln(self.scores.len());
pln(self.ages.get('Ada'));
pln(self.tags.len()); // 2: a set keeps one of each value
pln(self.pair[0]);
}Collections covers working with them.
Objects and Functions Are Values
An object is a value of type obj, and a function is a value of type fn. Both can be stored in variables and fields, passed to functions, and returned from them. A function type can also name a signature, like fn(str) -> str, to take only the functions that fit it (Function Signatures). Objects can also have types of your own, like User or Invoice, which Prototypes & Schemas covers.
Units
Numbers can carry units, and Stof converts between them for you:
m height: 135cm + 5ft + 123in
#[main]
fn main() {
pln(self.height.round(4)); // in meters, the field's type
pln((self.height as ft).round(2));
pln(1km + 500m == 1.5km);
}The same works for time, data sizes, mass, temperature, and angles:
#[main]
fn main() {
pln(5min + 30s == 330s);
pln(1day as hr);
pln(512MiB as MB); // binary and decimal sizes are different units
pln(2GB as MB);
}A unit type like m or ms is a kind of float. A field typed ms stores milliseconds however you assign it, so ms timeout: 2min holds 120000. Units that measure different things don't mix: adding 12km + 34s drops the units and gives a plain number. The Units Reference lists every unit.
A plain number has no units, so comparing it with a unit value compares the bare numbers. That matters most for times: Time::now() + 1hr is in hours (math gives the larger unit), while a time read from JSON is a plain number of milliseconds, so record.expires < Time::now() + 1hr compares the wrong numbers. Give the number its units first, and the comparison converts:
const expires: ms = record.expires; // a plain number from JSON, now in milliseconds
if (expires < Time::now() + 1hr) pln('expires within the hour');
Versions
ver holds a semantic version, and versions compare the way they should:
ver release: 1.2.3-beta
#[main]
fn main() {
pln(self.release > 1.0.0);
pln(self.release.minor());
}Unions and unknown
A union type accepts any of its types. unknown accepts anything, and leaves checking it up to you:
fn describe(v: int | str) -> str {
typeof v == 'int' ? 'a number' : 'some text'
}
fn kind(v: unknown) -> str {
typeof v
}
#[main]
fn main() {
pln(self.describe(5));
pln(self.describe('five'));
pln(self.kind([1, 2]));
}The data Type
Underneath, every field and function is a piece of data attached to an object, and a data value is a handle to one. You won't need it often. It's what richer values like a loaded image or PDF are (Data<Image>, Data<Pdf>), and it lets you do things like attach the same field to more than one object:
greeting: 'hello'
other: {}
#[main]
fn main() {
const handle: data = Data::field('self.greeting');
handle.attach(self.other);
pln(self.other.greeting);
}See the Data Library for more. Next, Functions.