Structs¶
Structs are named product types — a fixed set of named fields.
Declaration¶
Comments are allowed inside the body:
type Rect = struct {
// top-left corner
x: int64
y: int64
// dimensions
width: int64
height: int64
}
A field's type can name the struct itself:
Construction¶
Pass fields by name using labeled arguments, in any order:
The values are computed in the order they're written. Every value needs
its label, so Point(10, 20) is an error at each value:
let p: Point = Point(10, 20)
// error: argument 1 of `Point` needs a field label (`x:`)
// error: argument 2 of `Point` needs a field label (`y:`)
Each unlabelled value is offered the next field, in declaration order, that no label names.
Every field must be supplied unless it has a default. Omitting a field with no default is a compile error — there's no implicit zero/null value:
Each field value must have the field's type, with the same implicit
conversions as a function argument:
Point(x: "a", y: 1) is an error (expected `int64`, got `str`), while
3 is fine for an int64? field and a struct for an interface field. A
field can be given only once: Point(x: 1, x: 2, y: 3) is an error
(field `x` is given twice).
Field defaults¶
A field may declare a default with = expr. When a construction omits
that field, the default expression is evaluated and stored:
type Counter = struct {
label: str
count: int64 = 0
history: [int64] = []
}
let c: Counter = Counter(label: "hits") // count = 0, history = []
let d: Counter = Counter(label: "x", count: 5)
The default is evaluated fresh at each construction (so a [] default
yields a new empty array per instance, not a shared one). Defaults are
ordinary expressions evaluated in the struct's defining module, and they
can't see the local variables of the function doing the construction. A
default must have its field's type, which is checked where it is declared,
so count: int64 = "x" is an error even if no construction omits count.
Anything else wrong in it, such as an unknown name or variant, is reported
where a construction omits the field, and a generic struct's default is
checked only at each construction that omits it.
This is what lets the built-in Map[K, V] be created with no arguments —
all three of its fields default to []:
Custom constructors¶
A struct may declare its own constructor, a function named init inside the
body with no self:
type Port = struct {
number: int64
func init(number: int64) -> Port or Error {
if number < 1 or number > 65535 {
throw BadPort(number: number)
}
return Port(number: number)
}
}
let p = try Port(number: 8080) // calls init
From then on Port(...) anywhere outside the struct's own functions calls
init, with the usual rules for a function call: labels, defaults and
skipped labels. The field constructor is not available there,
so a label init doesn't declare is an error. init is the only way to make a
Port, and whatever it checks holds for every Port at the moment it is made.
Inside the struct's own functions, init and the other methods, Port(...)
is the field constructor as before. That is how init builds the value, and
how methods such as op_add make a new one without going through the checks
again. A method can't call init itself.
init must return the struct (-> Port) or a result of it (-> Port or Error),
which makes try Port(...) and must Port(...) work as for any fallible
call. It may not be a generic struct's: init on a Box[T] is an error for
now. A struct without init is built from its fields as described above.
Public fields stay assignable, so p.number = 0 is still possible after a
checked construction. To keep what init checks true for the value's whole
life, make the field private.
Private fields¶
A field whose name starts with _ is private: only the struct's own
functions (init, its methods and its operator methods) can read or assign
it, or name it in the field constructor.
type Duration = struct {
_ns: int64
func init(seconds: int64 = 0, ms: int64 = 0) -> Duration {
return Duration(_ns: seconds * 1 000 000 000 + ms * 1 000 000)
}
func as_ms(self) -> int64 {
return self._ns / 1 000 000
}
}
let d = Duration(seconds: 5)
print_int(d.as_ms()) // 5000
d._ns // error: field `_ns` is private to `Duration`
d._ns = 0 // error: field `_ns` is private to `Duration`
Only Duration's own functions can set _ns, so whatever init checks
about it holds for as long as the value lives.
Callers depend only on the methods, so the representation can change
without breaking them: Duration could store microseconds instead and no
caller would notice.
Outside the struct, a private field can't be named in the field constructor
either. A private field with a default is filled in from
it; a private field without one means the struct can only be built through
init or its own functions. Public and private fields mix freely.
Privacy covers the field, not what it points to. A method that returns a private array returns the array itself, which the caller can then change by indexing it; return a copy when that matters.
Private methods¶
A method whose name starts with _ is private in the same way: only the
struct's own functions can call it, as self._name(...) or on another value
of the struct.
type Duration = struct {
_ns: int64
func _whole(self, unit: int64) -> int64 {
return self._ns / unit
}
func as_ms(self) -> int64 {
return self._whole(unit: 1 000 000)
}
}
d.as_ms() // fine
d._whole(unit: 1) // error: method `_whole` is private to `Duration`
That keeps helpers that assume the struct's invariants, or that would break
them, out of the struct's interface. A method of a primitive type such as
str or int64 is private to the module that declares it.
An interface can't declare a private method: calling it through the interface would reach the struct's method from outside.
Field access¶
Field mutation¶
Reading or assigning a field the struct doesn't declare is an error, with
a did-you-mean hint when the name is close to a real field. So is .field
on a value that isn't a struct, such as an interface or an optional; for a
T?, use p?.x.
Methods¶
Define methods inside the struct body. The first parameter must be self:
type Point = struct {
x: int64
y: int64
func distance_sq(self) -> int64 {
return self.x * self.x + self.y * self.y
}
func translate(self, dx: int64, dy: int64) -> none {
self.x = self.x + dx
self.y = self.y + dy
}
}
Call methods with dot notation:
let p: Point = Point(x: 3, y: 4)
print_int(p.distance_sq()) // 25
p.translate(dx: 1, dy: 0)
print_int(p.x) // 4
Methods can also be invoked on non-Ident receivers — 0.to_str(),
p.field.method(), f().bar(), etc.
A method's parameter and return types can name the struct itself or a type
declared later in the module, so func scaled(self, by: int64) -> Point
inside Point chains as p.scaled(by: 2).distance_sq().
Generic structs¶
Type parameters in square brackets after the name; each unique instantiation is monomorphised:
type Pair[A, B] = struct {
first: A
second: B
func swap(self) -> Pair[B, A] {
return Pair[B, A](first: self.second, second: self.first)
}
}
let p: Pair[str, int64] = Pair[str, int64](first: "hello", second: 42)
let q = p.swap() // Pair[int64, str]
Construction always spells the type arguments; a bare Pair(...) is an
error.
A method of an instance is compiled for its type arguments when something
uses it: a call, an operator or other syntax that calls it, or the instance
becoming a value of an interface, which uses all of that interface's methods.
So a Box[T] whose contains uses == can hold a struct that has no ==, as
long as nothing calls contains on that Box. Only a method's signature is
checked otherwise, so a mistake in the body of a method nothing uses isn't
reported, as with a generic function nothing calls. An error in a body names the
instance, as in
`<` doesn't take `Color` operands; declare `op_lt` on `Color` to use it (in `Box[Color]`), and a line of
the template is reported for one instance only.
A generic struct or enum may name itself, with any type arguments, in its
fields, payloads and method signatures, as in kids: [Tree[T]] or the
Pair[B, A] above. The instances have to end, though: one that keeps naming a
bigger type, like next: W[[T]]? in W[T] or a called method of W[T] that
makes a W[[T]], is an error once it is 64 instances deep
(generic type `W` is 64 instances deep; each one names another with a new type).
Methods that branch into new types are stopped earlier, when a module passes 4096
instances.
The built-in Map[K, V] is the canonical example.
Operators¶
A struct gives the arithmetic and comparison operators a meaning by declaring methods with reserved names. The operator on the left operand's struct calls the method with the right operand as its one argument:
| Operator | Method | Returns |
|---|---|---|
a + b |
op_add(self, other) |
any type |
a - b |
op_sub(self, other) |
any type |
a * b |
op_mul(self, other) |
any type |
a / b |
op_div(self, other) |
any type |
a % b |
op_mod(self, other) |
any type |
a == b, a != b |
op_eq(self, other) |
bool |
a < b, a > b, a <= b, a >= b |
op_lt(self, other) |
bool |
type Money = struct {
cents: int64
func op_add(self, other: Money) -> Money {
return Money(cents: self.cents + other.cents)
}
func op_mul(self, times: int64) -> Money {
return Money(cents: self.cents * times)
}
func op_eq(self, other: Money) -> bool {
return self.cents == other.cents
}
func op_lt(self, other: Money) -> bool {
return self.cents < other.cents
}
}
let total = Money(cents: 250) + Money(cents: 100) * 3 // 550
if total > Money(cents: 500) { ... }
!= is not op_eq. The four orderings come from op_lt alone: a > b is
b < a, a <= b is not (b < a) and a >= b is not (a < b). a += b and
a -= b are a = a + b and a = a - b, and a < b < c chains as it does for
numbers. The operators keep their usual precedence, and the operands are
evaluated left to right whichever one the method belongs to.
A struct is the right operand when the left is an int64: 3 * price calls
op_rmul on price with 3 as its argument. The reflected methods are
op_radd, op_rsub, op_rmul, op_rdiv and op_rmod; each is tried only
when the left operand isn't a struct, and there is no reflected comparison.
A method that implements an operator takes self and one more parameter, and
the comparison methods return bool; otherwise it is an error where the
operator is used. A struct that doesn't declare the method still can't use the
operator, so a + b on a plain struct is the same error as before, and
a == b still tells you to compare the fields. A prefix minus is 0 - x,
so -price calls op_rsub with 0. not, and, or and is are never
overloaded.
Memory layout (compiler)¶
Struct fields are laid out sequentially, each taking 8 bytes, allocated on the heap:
Struct variables hold a pointer to the allocation.