Optional
Optional[T] is some(value) or none. Use it for a value that may be missing: a struct field, a parameter, a return, a list or map item. map.get(key) and text.index_of(part) give one.
struct User
name: String
age: Optional[Int]
end
def main() -> Void
users = [User(name: "Ana", age: some(31)), User(name: "Bo", age: none)]
for user in users
case user.age
some(n) -> puts("#{user.name} is #{n}")
none -> puts("#{user.name} gave no age")
end
end
endAna is 31
Bo gave no ageA case needs both arms, some(n) -> and none ->, or a final _. An arm with a literal inside, such as some(0) ->, may fail, so it covers nothing: add some(n) -> or _ after it. Patterns inside patterns shows an Optional in a user enum or a Result. == compares two Optionals whose items have ==: age == none, age == some(31). An Optional prints as some(31) or none. A field or parameter may default to none: port: Optional[Int] = none. In JSON, none is null (a missing key when decoding) and some(x) is x.
Fields, parameters, items and generics #
Optional[T] goes wherever a type does, T may be a type parameter, and Optionals nest. A parameter or field defaults to none, and a caller leaves it out or passes some(x).
struct Config
host: String
port: Optional[Int] = none
end
struct Box[T]
item: Optional[T]
end
def greet(name: String, title: Optional[String] = none) -> String = "#{title.unwrap_or("Mx")} #{name}"
def first_or_none[T](xs: List[T]) -> Optional[T]
return none if xs.length == 0
some(xs[0])
end
def main() -> Void
puts(Config(host: "localhost"))
puts(Box(item: some(3)))
puts(greet("Ana"))
puts(greet("Ana", some("Dr")))
puts(first_or_none(["a", "b"]))
empty: List[Int] = []
puts(first_or_none(empty))
scores: Map[String, Optional[Int]] = {"ana": some(9), "bo": none}
items: List[Optional[Int]] = [some(1), none, some(3)]
puts(scores)
puts(items.reduce(0) do |sum, o| sum + o.unwrap_or(0) end)
endConfig(host: "localhost", port: none)
Box(item: some(3))
Mx Ana
Dr Ana
some("a")
none
{"ana": some(9), "bo": none}
4Lookups #
map.get(key) and text.index_of(part) give an Optional: some when the key or the text is there, none when it is not. Pick the way to read it: unwrap_or for a default, case to act on each side, unwrap! only when none would be a bug.
def main() -> Void
stock = {"apple": 3, "pear": 0}
puts(stock.get("apple").unwrap_or(0))
puts(stock.get("kiwi").unwrap_or(0))
case "hello world".index_of("wor")
some(i) -> puts("found at #{i}")
none -> puts("not found")
end
end3
0
found at 6some #
some(value: T) -> Optional[T]def main() -> Void
puts(some(3))
puts(some("yes"))
endsome(3)
some("yes")none #
none -> Optional[T]The type comes from an annotation, a return type, a parameter or a field. A bare x = none is CHECK-OPTIONAL-TYPE.
def find(names: List[String], wanted: String) -> Optional[Int]
index = 0
for name in names
return some(index) if name == wanted
index += 1
end
none
end
def main() -> Void
puts(find(["a", "b"], "b"))
puts(find(["a", "b"], "z"))
endsome(1)
noneOptional.unwrap_or #
Optional.unwrap_or(optional: Optional[T], default: T) -> TGives the value, or the default for none. The default is always computed.
def main() -> Void
age: Optional[Int] = none
puts(age.unwrap_or(0))
puts(some(7).unwrap_or(0))
end0
7Optional.unwrap! #
Optional.unwrap!(optional: Optional[T]) -> TGives the value, or stops the program with RUNTIME-UNWRAP-NONE.
def main() -> Void
puts(some(5).unwrap! * 2)
end10Optional.map #
Optional.map(optional: Optional[T], block: Fn[T, U]) -> Optional[U]Gives some of the block’s value, or none without calling the block.
def main() -> Void
age: Optional[Int] = none
puts(some(20).map do |n| n + 1 end)
puts(age.map do |n| n + 1 end)
endsome(21)
noneOptional.some? and Optional.none? #
Optional.some?(optional: Optional[T]) -> Bool
Optional.none?(optional: Optional[T]) -> Booldef main() -> Void
age: Optional[Int] = none
puts(some(1).some?)
puts(age.none?)
endtrue
trueOptional.to_result #
Optional.to_result(optional: Optional[T], message: String) -> Result[T]Gives ok(value), or error(message) for none, so try can pass the error on.
def first_even(numbers: List[Int]) -> Optional[Int]
for n in numbers
return some(n) if n % 2 == 0
end
none
end
def half(numbers: List[Int]) -> Result[Int]
n = try first_even(numbers).to_result("no even number")
ok(n / 2)
end
def main() -> Void
puts(half([3, 8]))
puts(half([3, 5]))
endok(4)
error("no even number")Optional or Result #
Use an Optional when having no value is normal and needs no reason: a lookup that finds nothing, a setting the caller left out. Use a Result when something failed and the caller needs to know why, such as a parse or a file read. to_result("message") turns the first into the second when a missing value is an error for the caller. List.find and Lazy.find give a Result with error("not found"), not an Optional.