null and errors
SG has no value that every type can hold by accident. An int is always a number and a string is always a
text. A value that may be missing says so in its type, T?, and an operation that may fail says so in its
return type, Result<T, E>. The compiler then makes the program deal with the missing value and the error
before it goes on. Only a fault that depends on the data and could not be seen when the program was compiled
stops it, with a panic.
T? and null
struct User {
string name
string? nickname
}
void main() {
int? age = null
print(age is null)
age = 36
if age is not null {
print(age + 1)
}
var ada = User { name = "Ada", nickname = null }
var grace = User { name = "Grace", nickname = "Amazing Grace" }
print(ada.nickname ?? ada.name)
print(grace.nickname ?? grace.name)
}
It prints:
true
37
Ada
Amazing Grace
T? is a T or null, and null is written only where a T? goes. x is null and x is not null test it.
a ?? b gives a when it holds a value and b when it is null. A Node*? takes no more room than a
pointer; an int? is the number and a flag beside it.
A T? cannot be used as a T before it has been tested:
void main() {
string? name = "Ada"
print(name.length())
}
error: this is `string?` and may be `null`; `.length()` needs a value
--> example.sg:3:11
3 | print(name.length())
| ^^^^
hint: test it first: `if name is not null { ... }`
Narrowing
After a test, the compiler knows which case the program is in, and the same name has the narrower type: inside
if age is not null, age is an int. This follows the conditions along && and ||, and past a return:
void greet(read string? name) {
if name is null || name.length() == 0 {
print("hello, stranger")
return
}
print($"hello, {name}")
}
void main() {
string? nobody = null
string? empty = ""
string? ada = "Ada"
greet(read nobody)
greet(read empty)
greet(read ada)
if ada is not null && ada.length() > 2 {
print("a long enough name")
}
}
It prints:
hello, stranger
hello, stranger
hello, Ada
a long enough name
On the right of ||, name is no longer null, or the left side would have been true. After the if, which
returns, it is not null either. Narrowing also works under ! and after while x is null { ... }.
Only local variables and parameters are narrowed. A field could be changed between the test and the use (by a method called in between, for one), so the compiler does not trust a test of it; you borrow the field into a local and test that:
struct Address {
string city
}
struct Person {
string name
Address? address
}
void show(read Person person) {
var address = read person.address
if address is not null {
print(address.city)
}
}
void main() {
var ada = Person { name = "Ada", address = Address { city = "London" } }
show(read ada)
}
It prints:
London
?.
a?.b is null when a is, and a.b otherwise; the rest of a chain does not run once a part is null. It
works for fields and for methods (a?.m()), and is often followed by ??:
struct Address : Formattable {
string city
}
struct Person {
string name
Address? address
}
void main() {
var people = List<Person> {
Person { name = "Ada", address = Address { city = "London" } },
Person { name = "Pasha", address = null }
}
for person in read people {
var city = person.address?.city ?? "unknown"
print($"{person.name}: {city}")
}
}
It prints:
Ada: London
Pasha: unknown
Result<T, E>
A function that can fail returns a Result<T, E>: either Ok(value) or Error(cause). The caller sees both
in the type and cannot take the value without deciding what happens to the error:
Result<int, string> half(int n) {
if n % 2 != 0 {
return Error($"{n} is odd".toString())
}
return Ok(n / 2)
}
void main() {
match half(10) {
Ok(value) => print(value)
Error(why) => print(why)
}
match half(7) {
Ok(value) => print(value)
Error(why) => print(why)
}
print(half(7) ?? 0)
if half(8) is Ok(value) && value > 3 {
print($"big half: {value}")
}
}
It prints:
5
7 is odd
0
big half: 4
match and is see the two variants, Ok and Error, and ?? gives a fallback in place of the error. A
Result can never be dropped without a word, since the error would be lost:
Result<void, string> save() {
return Ok()
}
void main() {
save()
}
error: this `Result` is not used, so an error would be lost silently
--> example.sg:6:5
6 | save()
| ^^^^^^
hint: pass the error on with `try save()`, or drop it on purpose with `_ = save()`
Result<void, E> is a function that gives nothing when it works; it ends with return Ok().
Errors of your own, try and ?? return
The error type is usually an enum of your own, with a variant for each way to fail and the values that say
more about it. try x gives the value of x, or returns its error from the function at once. When the
error is of another type, try puts it in the variant whose only value is of that type:
enum ConfigError : Formattable {
Missing(string key)
BadNumber(NumberError cause)
OutOfRange(int value)
}
Result<int, ConfigError> parsePort(read string text) {
var port = try int.parse(text)
if port < 1 || port > 65535 {
return Error(ConfigError.OutOfRange(port))
}
return Ok(port)
}
Result<int, ConfigError> portOf(read HashMap<string, string> settings) {
var text = settings.get("port") ?? return Error(ConfigError.Missing("port"))
return Ok(try parsePort(text))
}
void main() {
var all = List<HashMap<string, string>> {
HashMap<string, string> { {"port", "8080"} },
HashMap<string, string> { {"port", "80x"} },
HashMap<string, string> { {"port", "99999"} },
HashMap<string, string>()
}
for settings in read all {
match portOf(read settings) {
Ok(port) => print($"port {port}")
Error(error) => print($"error: {error}")
}
}
}
It prints:
port 8080
error: BadNumber(Invalid(2))
error: OutOfRange(99999)
error: Missing("port")
int.parse gives a Result<int, NumberError>, and try turns its error into ConfigError.BadNumber, the one
variant that carries a NumberError. There is no conversion to write by hand; if no variant carries the type,
or two do, the compiler says so. Invalid(2) says where the text stopped being a number.
settings.get("port") gives a read string?, null for a missing key, and ?? return ... leaves the function
in that case; after it, text is a read string. The right side of ?? can be a value, a return or a
panic(...). try works on a T? too, in a function that returns a T?: it returns null when the value is
null.
try is only written in a function that can pass the error on:
Result<int, string> parse() {
return Ok(1)
}
int twice() {
return 2 * try parse()
}
void main() {
print(twice())
}
error: `try` returns the error to the caller, but `twice` returns `int`
--> example.sg:6:16
6 | return 2 * try parse()
| ^^^^^^^^^^^
hint: make `twice` return a `Result<..., string>`, or handle the error here with `match` or `??`
Result<void, E> main()
main can return a Result too, so a program can use try from the top. If it ends with an error, the error is
printed after error: and the program exits with code 1; the error type must be Formattable, and here it
writes its own text. The second check fails:
enum CopyError : Formattable {
TooLarge(long size, long limit)
Empty
void format(read this, ref Formatter f) {
match this {
TooLarge(size, limit) => f.write($"{size} bytes is more than the limit of {limit}")
Empty => f.write("there is nothing to copy")
}
}
}
Result<void, CopyError> check(long size) {
if size == 0 {
return Error(CopyError.Empty)
}
if size > 1000 {
return Error(CopyError.TooLarge(size, 1000))
}
return Ok()
}
Result<void, CopyError> main() {
try check(10)
print("10 bytes: fine")
try check(5000)
print("never printed")
return Ok()
}
10 bytes: fine
error: 5000 bytes is more than the limit of 1000
Panics
Some faults cannot be known when the program is compiled, because they depend on the data: an index that came
from the input, a divisor that is 0. SG checks for them as the program runs, and when one happens it stops the
program with a panic: a message that says what went wrong and where, and the exit code 1. There is no
unwinding and no catching. A panic means the program has a bug, not that the world was unkind; what the world
can do to a program (a missing file, a bad number in the input) comes back as a Result.
What can be found before the program runs is a compile error instead, never a panic: an array index known to be
too large, a missing match arm, a null not tested for. This program compiles, and stops when it runs:
void main() {
var scores = List<int> { 90, 75, 60 }
var at = 3
print(scores[at])
}
panic: index 3 is out of range: the length is 3
--> example.sg:4:11
4 | print(scores[at])
| ^^^^^^^^^^
hint: `.get(i)` reads with `null` instead; before a write, compare the index with `.length()`
These panic:
- an index outside a list, an array, a slice or a text (
scores.get(at)givesnullinstead); - integer overflow, in the interpreter, in tests and in a debug build (
tryAddgivesnull,wrappingAddwraps; a release build wraps); - a division by zero, and a cast whose value does not fit (
(int)big;big.tryToInt()givesnull); map[key]for a key that is not in theHashMap, andmap.addfor one that is;panic("..."), written by you, and anassertthat fails.
The checks stay on in a release build, which cannot turn them off. Only integer overflow (and a shift by more bits than the type has) wraps there instead, as in Rust.
panic and assert
panic(message) stops the program on purpose, for a case your code says cannot happen. assert(condition)
panics when the condition is false, and shows both sides of a comparison:
int percent(int part, int whole) {
assert(whole > 0)
return part * 100 / whole
}
void main() {
print(percent(1, 4))
print(percent(1, 0))
}
25
panic: assert failed: whole > 0
left: 0
right: 0
--> example.sg:2:5
2 | assert(whole > 0)
| ^^^^^^^^^^^^^^^^^
x ?? panic("...") is the way to say that a missing value is a bug: var port = int.parse(text) ?? panic("the port was checked above"). Use it where you know more than the compiler does; where the data can really be
wrong, give the caller a Result.