Skip to main content

Null & Initialization

null means "nothing here". Stof has no separate "undefined": a field set to null and a field that doesn't exist both read as null.

Missing Is Null​

Reading a field that doesn't exist, even deep in a path, gives null instead of an error:

missing.stofPlayground ↗
config: { name: 'api' }

#[main]
fn main() {
  pln(self.config.timeout);              // null
  pln(self.config.retry.max_attempts);   // null: retry doesn't exist either
}
Output

Defaults with ??​

a ?? b gives a, unless a is null, then b. It's the usual way to give a default:

defaults.stofPlayground ↗
config: { name: 'api' }

#[main]
fn main() {
  const timeout = self.config.timeout ?? 30s;
  pln(timeout);

  const retries = self.config.retry.max ?? self.defaults.retries ?? 3;
  pln(retries);

  pln(false ?? 'only null is replaced');
}
Output

Math with Null Is an Error​

Adding, multiplying, or doing any other math with null throws an error, instead of quietly giving a wrong number. Usually it means a field is missing or misspelled:

null-math.stofPlayground ↗
rate: 2

#[main]
fn main() {
  try {
      pln(self.rat * 3);     // a typo: self.rat is null
  } catch {
      pln('error: cannot multiply null');
  }

  pln((self.discount ?? 0) * 3);    // a default makes it safe
}
Output

The same goes for running totals: start them at a value (let total = 0;), not empty. Comparisons are the exception: they don't throw, and null < 10 is true, so check for null first when it matters.

Null-Safe Calls​

Calling a function that doesn't exist throws, unlike reading a missing field. Add ? before the . to get null instead. It works anywhere in a path:

null-safe.stofPlayground ↗
plugins: {
  audit: {}
}

#[main]
fn main() {
  pln(self.plugins.audit?.on_save());                // audit has no on_save
  pln(self.plugins.billing?.on_save() ?? 'skipped');  // billing doesn't exist
}
Output

A ? in front of a whole expression makes every call in it null-safe at once: ?self.load().parse().validate() gives null if any of those functions is missing. For library functions, Lib?::func() does the same: see Libraries.

Not Null​

Add ! to a type to reject null. It works on fields, variables, parameters, and return types:

not-null.stofPlayground ↗
fn send(to: str!) -> str {
  `sending to ${to}`
}

#[main]
fn main() {
  pln(self.send('ada@example.com'));
  try {
      self.send(null);
  } catch {
      pln('a null address is rejected');
  }
}
Output

! goes anywhere a type does: inside a tuple ((int!, str), where only the int can't be null), on a union's members (int! | str! is never null), on a whole union ((int | str)!), and in a function signature (fn(str!) -> str). A function whose parameter is str! only fits a signature that promises a str!, since a plain str could be null.

Choosing a Value​

The ternary operator picks one of two values:

ternary.stofPlayground ↗
usage: 120
limit: 100

#[main]
fn main() {
  const status = self.usage > self.limit ? 'over' : 'ok';
  pln(status);
}
Output

For more than two branches, a block can be an expression too: its last line without a ; is its value. That turns a multi-step calculation into a single assignment:

block-expression.stofPlayground ↗
usage: 120
limit: 100

#[main]
fn main() {
  const status = {
      const ratio = (self.usage as float) / self.limit;
      if (ratio > 1) 'over'
      else if (ratio > 0.8) 'close'
      else 'ok'
  };
  pln(status);
}
Output

Next, Error Handling.