Skip to main content

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​

basics.stofPlayground ↗
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());
}
Output

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:

numbers.stofPlayground ↗
#[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
}
Output

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:

strings.stofPlayground ↗
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"#);
}
Output

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:

casting.stofPlayground ↗
#[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
}
Output

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:

typeof.stofPlayground ↗
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
}
Output

Collections​

Lists, maps, sets, and tuples hold other values:

collections.stofPlayground ↗
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]);
}
Output

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:

length.stofPlayground ↗
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);
}
Output

The same works for time, data sizes, mass, temperature, and angles:

units.stofPlayground ↗
#[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);
}
Output

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:

versions.stofPlayground ↗
ver release: 1.2.3-beta

#[main]
fn main() {
  pln(self.release > 1.0.0);
  pln(self.release.minor());
}
Output

Unions and unknown​

A union type accepts any of its types. unknown accepts anything, and leaves checking it up to you:

union.stofPlayground ↗
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]));
}
Output

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:

data.stofPlayground ↗
greeting: 'hello'
other: {}

#[main]
fn main() {
  const handle: data = Data::field('self.greeting');
  handle.attach(self.other);
  pln(self.other.greeting);
}
Output

See the Data Library for more. Next, Functions.