Nanyx
PlaygroundPackages

prelude: contexts

Equality, ordering, hashing, joining, and converting to and from text

The contexts the operators are read through, and the toString and fromString of the built-in types. They are in the prelude, so no import is needed. How a context is found, and synthesized from the definitions attached to a type, is described in Contexts.

Converting to text

int, float, bool and string each have an attached toString. Each writes the value as string interpolation, "{n}", does, and string.toString gives back the string itself. Interpolation goes through the ToString(a) context, which a type of your own gets by attaching a toString of the same kind. A tag with a payload, a tuple, a record, a list, a map and a set have one the compiler derives from their parts: a map is written as its literal is, [tea => 3, cake => 1], and a set as a list of its elements, [3, 1]. Because they are functions, they can be passed where interpolation cannot:

import nanyx/text

def scores = [3, 14, 15]
def text = scores \map(int.toString) \string.join(", ")
-- "3, 14, 15"

def answer = 42 \toString
-- "42"

A float is written as the shortest decimal that reads back as the same float, as JavaScript and Python’s repr write one, and always with a point, so that it never looks like an int. From 1e-6 up to (but not including) 1e21 it is written in full; otherwise it is one digit, a point, the rest of its digits and an exponent, which is how a float literal is written in Nanyx. NaN and the infinities are written as words, and negative zero keeps its sign:

"{0.1 + 0.2}"        -- "0.30000000000000004"
"{1.0 / 3.0}"        -- "0.3333333333333333"
"{5.0}"              -- "5.0"
"{0.000001}"         -- "0.000001"
"{0.0000001}"        -- "1.0e-7"
"{1.0e20}"           -- "100000000000000000000.0"
"{1.0e21}"           -- "1.0e21"
"{math.sqrt(-1.0)}"  -- "NaN"
"{1.0 / 0.0}"        -- "Infinity"
"{-1.0 / 0.0}"       -- "-Infinity"
"{0.0 * -1.0}"       -- "-0.0"

ToString is synthesized for these types from their toString, as it is for any other type with one attached, so nothing in the compiler treats them specially:

def label: [ToString(a)] a -> string = { x -> "<" ++ toString(x) ++ ">" }

label(42)    -- "<42>"
label(true)  -- "<true>"

Reading from text

int, float and bool each have an attached fromString, on the numbers and prelude pages. Each gives back an option-like union, with its own tag for text it cannot read: int.fromString("42") is #some(42), and bool.fromString("yes") is #invalidBool. The sized number types have one each too, I8.fromString to U64.fromString and F32.fromString, each with its own tag: U8.fromString("300") is #invalidU8.

Each is the mirror of the type’s toString, and, as toString gives a type a ToString, an attached fromString gives it the FromString context. Its associated type failure is what fromString gives back when the text holds no value, so that each type keeps its own tag. A function that reads a value of any type from text requires it, and a call finds the instance as it finds any other: synthesized from the attached fromString of the type it is called at, whose type also fixes failure. At int that is #invalidInt, and a constraint can say so, [FromString(a, failure = #invalidInt)]:

def readAll: [FromString(a)] list(string) -> list(#some(a) | failure) = { xs -> xs \list.map(fromString) }

def total: list(#some(int) | #invalidInt) -> int = { results -> results \somes \list.fold(0, { sum, n -> sum + n }) }

def sumAll = { texts -> total(readAll(texts)) }

sumAll(["1", "x", "30"])  -- 31

A type of your own gets one by attaching a fromString, with a tag of its own for text it cannot read:

def Point.fromString: string -> #some(Point) | #invalidPoint = { s -> ... }

Something has to settle a: what the call is given, what its result is passed to, or the type the result is expected to have, as in def ints: list(#some(int) | #invalidInt) = readAll(texts).

Reference

Eq

context Eq(a) = (
  `==`: a, a -> bool
)

How two values of type a are compared. x == y is read through it, and x != y is not (x == y). The compiler has its own for every type that holds no function, which compares by structure: records field by field, lists element by element, tags by name and then payload. Functions have no equality. A function that compares values of one of its type variables requires it: def same: [Eq(a)] a, a -> bool.

Append

context Append(a) = (
  `++`: a, a -> a
)

The values of type a that join, end to end. x ++ y is read through it: def surround: [Append(a)] a, a -> a = { edge, x -> edge ++ x ++ edge } works at string and at any list. A type gets one by attaching def Path.`++` = ....

string.`++`

def string.`++`: string, string -> string

x followed by y.

list.`++`

def list.`++`: list(a), list(a) -> list(a)

The elements of xs followed by those of ys.

Ord

context Ord(a) = (
  compare: a, a -> #less | #equal | #greater
)

How two values of type a are put in order. x < y, x <= y, x > y and x >= y are read through it, so the four cannot disagree. The compiler has its own for numbers, bool (false first), string (by bytes, which is the order of code points), and tuples and lists of them (position by position, and a list that is a prefix of another first). Records and tags have no order: a nominal type gets one by attaching compare, and a list of records is sorted by a key with list.sortBy. A function that orders values of one of its type variables requires it: def largest: [Ord(a)] list(a) -> .... Ord does not require Eq; a type that attaches both should keep them consistent.

int.compare

def int.compare: int, int -> #less | #equal | #greater

Whether x is less than, equal to or greater than y.

float.compare

def float.compare: float, float -> #less | #equal | #greater

Whether x is less than, equal to or greater than y, with NaN after every other float, as __compare orders floats.

bool.compare

def bool.compare: bool, bool -> #less | #equal | #greater

Whether x is less than, equal to or greater than y, with false first.

string.compare

def string.compare: string, string -> #less | #equal | #greater

Whether x is less than, equal to or greater than y, by bytes, which is the order of code points.

Hash

context Hash(a) = (
  hash: a -> int
)

How a value of type a is hashed: an int that is the same for any two values == finds equal, so that a map can find a key by its hash. The compiler has its own for every type it has its own Eq for, which hashes by structure. A nominal type that attaches its own == must attach a hash that agrees with it, or it has none: def Email.hash = { e -> string.hash(lower(e)) } for an == that ignores case. A function that hashes values of one of its type variables requires it: def bucket: [Hash(a)] a, int -> int.

int.hash

def int.hash: int -> int

The compiler’s own hash of x, as Hash gives it to a type with no hash of its own.

float.hash

def float.hash: float -> int

The compiler’s own hash of x, as Hash gives it to a type with no hash of its own.

bool.hash

def bool.hash: bool -> int

The compiler’s own hash of x, as Hash gives it to a type with no hash of its own.

string.hash

def string.hash: string -> int

The compiler’s own hash of s, as Hash gives it to a type with no hash of its own.

ToString

context ToString(a) = (
  toString: a -> string
)

How a value of type a is written as text. A hole in a string, "Total: {total}", is written through it, so a type can be interpolated when it has one: a type gets one by attaching a toString, def Point.toString = { p -> "({p.x}, {p.y})" }, and a block can load another with use. The compiler has its own for int, float, bool, string and tags without a payload, and derives one for a tag with a payload, a tuple, a record, a list, a map and a set from the ToString of each part: #some(3), (1, two), (x = 1, y = 2), [1, 2, 3], [a => 1].

int.toString

def int.toString: int -> string

n in decimal, with a leading - when it is negative.

float.toString

def float.toString: float -> string

x in decimal, with the fewest digits that read back as x.

bool.toString

def bool.toString: bool -> string

true or false.

string.toString

def string.toString: string -> string

s itself.

FromString

context FromString(a) = (
  failure: type
  fromString: string -> #some(a) | failure
)

How a value of type a is read from text, with failure for text that does not hold one: int.fromString gives back #some(int) | #invalidInt, so int’s failure is #invalidInt. A type gets one by attaching a fromString, as int, float and bool do, which also fixes its failure, so a function can read a value of whichever type it is called at: def readAll: [FromString(a)] list(string) -> list(#some(a) | failure).

Typed

context Typed(a) = (
  typeOf: Type(a)
)

The type a as a value, which the compiler gives for every type: a function that is given a value of type a can require Typed(a) and read typeOf, instead of also taking the type argument type a, def encode: [Typed(a)] a -> Json = { value -> encodeAt(value, typeOf) }. A use can load another, but the only Type(a) value is type a, so it stands for the same type.

Default

context Default(a) = (
  default: a
)

A value of type a to fall back on, or to fill with: def valueOrDefault: [Default(a)] #some(a) | #none -> a. A type gets one by attaching a default value, def Point.default = Point(x = 0, y = 0), as each built-in type does.

int.default

def int.default: int

0.

float.default

def float.default: float

0.0.

string.default

def string.default: string

"", the empty string.

bool.default

def bool.default: bool

false.

list.default

def list.default: list(a)

[], the empty list.

Yield

context Yield(a) = (
  yield: a -> seq(a)
)

The keyword yield, of kind #yield: a block or lambda with yield x in it is a lazy sequence of the values it yields, and the code after a yield runs only when the sequence is pulled that far. seq { yield 1 yield 2 } gives 1 and 2, and xs \list.select { x -> if x > 0 then yield x } keeps the positive ones. Nothing loads this context: the compiler rewrites the block into calls to seq.cons and seq.empty, so the sequence needs no context of its own.