Structs
Declare a struct #
A struct is a record with named, typed fields. Declare it at the top of the file.
struct User
name: String
age: Int
end
def main() -> Void
user = User(name: "Ana", age: 25)
puts(user.name)
puts(user)
endAna
User(name: "Ana", age: 25)Build a struct with every field, each by name, in any order. A missing field is an error:
struct Point
x: Int
y: Int
end
def main() -> Void
p = Point(x: 1)
enderror[CHECK-MISSING-FIELD]Default values #
A field written name: Type = value has a default, and a constructor may leave it out. A field without a default must still be given.
struct Options
name: String
retries: Int = 3
tags: List[String] = []
end
def main() -> Void
puts(Options(name: "a"))
puts(Options(name: "b", retries: 1))
endOptions(name: "a", retries: 3, tags: [])
Options(name: "b", retries: 1, tags: [])A default follows the rules of a parameter default: a literal, true, false, nil, none, [], {}, an enum variant without a payload or the name of a constant with such a value (retries: Int = RETRIES), but not a struct built with no arguments, which only a parameter takes. Anything else is CHECK-DEFAULT-VALUE, and a value of the wrong type is CHECK-TYPE-MISMATCH.
struct Options
retries: Int = 1 + 2
end
def main() -> Void
puts(Options())
enderror[CHECK-DEFAULT-VALUE]with and JSON.decode do not use defaults: with copies a value, and a decode still needs every key.
Change a field #
Fields cannot be assigned. value.with(...) copies the struct with the named fields changed. The original stays as it was.
struct Account
owner: String
balance: Int
end
def deposit(account: Account, amount: Int) -> Account = account.with(balance: account.balance + amount)
def main() -> Void
account = Account(owner: "Bob", balance: 10)
richer = deposit(account, 5)
puts(richer)
puts(account)
endAccount(owner: "Bob", balance: 15)
Account(owner: "Bob", balance: 10)Every value is computed from the struct before the update, so fields can swap:
struct Pair
left: Int
right: Int
label: String
end
def main() -> Void
pair = Pair(left: 1, right: 2, label: "p")
swapped = pair.with(left: pair.right, right: pair.left)
puts(swapped)
puts(pair.with(label: "q", left: 0))
endPair(left: 2, right: 1, label: "p")
Pair(left: 0, right: 2, label: "q")For a field inside a struct, update both levels. Updates chain:
struct Address
city: String
zip: Int
end
struct User
name: String
address: Address
end
def main() -> Void
ana = User(name: "Ana", address: Address(city: "Cusco", zip: 8))
moved = ana.with(address: ana.address.with(city: "Lima"))
puts(moved)
puts(moved.with(name: "Bea").with(address: Address(city: "Quito", zip: 1)))
endUser(name: "Ana", address: Address(city: "Lima", zip: 8))
User(name: "Bea", address: Address(city: "Quito", zip: 1))with needs at least one field. Each must be named (PARSE-UNEXPECTED-TOKEN otherwise), appear once, exist in the struct and have the right type (CHECK-TYPE-MISMATCH):
struct Point
x: Int
y: Int
end
def main() -> Void
p = Point(x: 1, y: 2)
q = p.with(z: 5)
enderror[CHECK-UNKNOWN-FIELD]A bare p.with(x: 2) changes nothing, so it is CHECK-UNUSED-VALUE. Assign the result: p = p.with(x: 2).
struct Point
x: Int
y: Int
end
def main() -> Void
p = Point(x: 1, y: 2)
p.with(x: 2)
enderror[CHECK-UNUSED-VALUE]with is not reserved: a struct can have a field named with, unless that field is a function (CHECK-REDEFINED-NAME).
Structs in structs and lists #
Fields can be lists, maps, other structs and enums.
struct Item
name: String
price: Int
end
struct Order
id: Int
items: List[Item]
end
def main() -> Void
order = Order(id: 7, items: [Item(name: "tea", price: 3), Item(name: "cake", price: 5)])
total = order.items.reduce(0) do |sum, item| sum + item.price end
puts("order #{order.id}: #{total}")
endorder 7: 8List the fields #
Type.members is a List[StructMember] with one entry per field of a struct type, in declaration order. A StructMember has two String fields: name and type, the field type written as source. A tool such as a table mapper can build SQL from a struct with it.
type Id = Int
struct Address
city: String
end
struct User
id: Id
name: String
tags: List[String]
home: Address
end
def main() -> Void
User.members.each do |m| puts("#{m.name}: #{m.type}") end
endid: Int
name: String
tags: List[String]
home: AddressThe type is the one the checker prints, so an alias is expanded (Id gives Int). members is on the type and not on a value: user.members reads a field of that name, and a struct may have one. An enum, a resource or an alias is not a struct, so Color.members is CHECK-UNKNOWN-METHOD and Id.members is CHECK-UNKNOWN-TYPE.
enum Color
Red
end
def main() -> Void
puts(Color.members.size)
enderror[CHECK-UNKNOWN-METHOD]Type.codec is next to it: the codec of a struct or enum that JSON can read, a Codec[T] with the same members plus decode, encode and from. It is how generic code gets the fields and the JSON of a type it cannot name.
Type parameters #
A struct can take type parameters after its name, as an enum does. The type argument comes from the values you give:
struct Box[T]
value: T
end
struct Pair[A, B]
first: A
second: B
end
def main() -> Void
count = Box(value: 41)
puts(count.value + 1)
pair = Pair(first: "one", second: count)
puts(pair.second.value)
puts(pair)
puts(count.with(value: 7))
end42
41
Pair(first: "one", second: Box(value: 41))
Box(value: 7)count is a Box[Int], so count.value is an Int. A type names all its arguments: Box[Int], Pair[String, Box[Int]]. A bare Box or the wrong number of arguments is CHECK-UNKNOWN-TYPE.
struct Box[T]
value: T
end
def total(box: Box[List[Int]]) -> Int = box.value.sum
def main() -> Void
puts(total(Box(value: [1, 2, 3])))
puts(total(Box(value: [])))
end6
0An empty list or map cannot say what the argument is, so it needs a type from the place where the struct is used: a parameter, as above, a return type, a field or a variable with a type. Without one it is CHECK-ENUM-TYPE-INFERENCE.
struct Box[T]
value: T
end
def main() -> Void
box = Box(value: [])
enderror[CHECK-ENUM-TYPE-INFERENCE]Values that disagree are CHECK-TYPE-MISMATCH. A parameter cannot be a Map key (CHECK-MAP-KEY-TYPE), and a field named with cannot have a parameter as its type (CHECK-REDEFINED-NAME), since the argument could be a function. JSON.encode writes a generic instance, but JSON.decode and JSON.schema refuse one (CHECK-NOT-DECODABLE). An imported struct is written Models.Box[Int].
No methods #
Structs have fields only. A field named to_s shadows the text form, so write functions that take the struct:
struct Rect
width: Int
height: Int
end
def area(r: Rect) -> Int = r.width * r.height
def main() -> Void
puts(area(Rect(width: 3, height: 4)))
end12Equality #
Two structs of the same type are equal when all their fields are equal, compared in depth. Lists, maps, sets, Results and enums compare the same way:
struct User
name: String
tags: List[String]
end
def main() -> Void
a = User(name: "Ana", tags: ["admin"])
b = User(name: "Ana", tags: ["admin"])
puts(a == b)
puts(a.with(tags: []) != b)
puts([a, b] == [b, a])
endtrue
true
trueA struct with a function field (Fn), a task, a channel, a handle or a JSON.Value inside has no equality: == on it is CHECK-TYPE-MISMATCH, and the message names the field. A Float field follows IEEE 754, so a struct that holds a NaN is not equal to itself.
Private fields #
A private line in a struct body, alone with a blank line before and after, makes the fields after it private to the module that declares the struct: its file, or the module block it is in. That module reads, sets and gives them as usual. Elsewhere the value can be passed, stored, sent, compared and printed, but its private fields cannot be read, given or set with with, and the struct is built only by the module’s functions:
module Bank
struct Account
owner: String
private
cents: Int
end
def open(owner: String) -> Account = Account(owner: owner, cents: 0)
def deposit(account: Account, cents: Int) -> Account = account.with(cents: account.cents + cents)
def balance(account: Account) -> Int = account.cents
end
def main() -> Void
account = Bank.deposit(Bank.open("Ana"), 150)
puts("#{account.owner} #{Bank.balance(account)}")
puts(account)
endAna 150
Account(owner: "Ana", cents: 150)== compares every field, and inspect, to_s and interpolation show every field. Outside the module, account.cents, Account(owner: "Bo"), account.with(cents: 0), Account.codec and JSON.encode(account) are CHECK-PRIVATE-FIELD:
module Bank
struct Account
owner: String
private
cents: Int
end
def open(owner: String) -> Account = Account(owner: owner, cents: 0)
end
def main() -> Void
puts(Bank.open("Ana").cents)
enderror[CHECK-PRIVATE-FIELD]agentica doc lists the public fields and says that the struct has private fields.