Scalar Types

String

A double-quoted string interprets backslash escapes: \n (newline), \t (tab), \r (carriage return), \0 (null), \\ (backslash), \" (double quote), and \u{H...} (a Unicode code point in hex); any other escape is an error. A single-quoted string is raw — every character, backslash included, is literal — which is convenient for regular-expression patterns and paths: '\d+', 'C:\dir'.

Laws:

• s.chars().length = s.length
• s.chars().get(i) = s.char_at(i) for every valid i

Examples:

let xs: Array[Char] := "cat".chars()
print(xs)        -- [#c, #a, #t]
print(xs.length) -- 3
print(xs.get(1)) -- #a

to_bytes() uses UTF-8 encoding and returns an Array[Byte] with byte values in 0..255.

let bytes: Array[Byte] := "cat".to_bytes()
print(bytes) -- [99, 97, 116]

create String.from_bytes(bytes) is the inverse: it decodes an Array[Byte] as UTF-8 and returns the String. It raises if the bytes are not valid UTF-8, rather than substituting replacement characters, so create String.from_bytes(s.to_bytes()) always gives back s exactly.

let bytes: Array[Byte] := "héllo".to_bytes()
let text: String := create String.from_bytes(bytes)
print(text) -- "héllo"

Integer

Integer is a signed 64-bit integer (range -2^63 .. 2^63-1) on every backend. Arithmetic is checked: +, -, *, unary -, and ^ raise on overflow, and / and % raise on a zero divisor.

Integer64 is an alias: it names exactly the same type, so the two are interchangeable everywhere (let n: Integer64 := 5 and let m: Integer := n both typecheck). The fixed-width siblings are Integer16, Integer32 and Byte, below.

Bitwise operations use 32-bit integer semantics. Bit index 0 is the least-significant bit. For method calls on integer literals, wrap the literal in parentheses: (5).bitwise_left_shift(1).

Byte

Byte is an unsigned 8-bit integer (range 0..255). It is the element type of String.to_bytes() and of binary file I/O (Array[Byte]).

Byte is a distinct type, related to Integer the way Integer is related to Real: there is no implicit conversion in either direction.

• Byte literals: an integer literal with a u8 suffix is a Byte: 12u8, 0xFFu8, 0b1010u8, 0o17u8, 1_0u8. The value must be in 0..255, and is checked when the program is parsed. (The suffix is u8, not b, because b is a hex digit.) An unsuffixed literal is always an Integer, so let b: Byte := 65 is a type error; write 65u8. There are no negative byte literals: -5u8 is the Integer -5.
• Making a Byte from a value: n.to_byte() on an Integer (raises unless 0 <= n <= 255), or reading one out of an Array[Byte].
• Getting an Integer: b.to_integer(). Assigning a Byte to an Integer variable or passing it to an Integer parameter is a type error.
• Arithmetic (+ - * / % ^, unary -) promotes to Integer, so the result of b + b is an Integer and cannot overflow a Byte; narrow it back with (b + b).to_byte(). Mixing with Real promotes to Real.
• Comparison (= /= < <= > >=) is between two Bytes. Comparing a Byte with an Integer needs b.to_integer() first, just as comparing an Integer with a Real needs a conversion. b.equals(x) is true only when x is a Byte of the same value.
• convert does not change representation, so convert n to b: Byte on an Integer is rejected; use to_byte(). A Byte held in an Any keeps its type: type_of reports "Byte" and convert a to b: Byte succeeds.
• Bitwise methods work on 8 bits and return a Byte, unlike Integer's 32-bit bitwise operations: (195).to_byte().bitwise_not() is 60. Bit indexes for bitwise_is_set, bitwise_set and bitwise_unset must be in 0..7; shift counts must be non-negative, and shifting by 8 or more clears every bit.
• Java interop: a Byte passed to a Java int or long parameter is passed as an integer. Passed to a Java byte parameter, it is the same 8 bits read as signed, so 200 arrives as -56.

let bytes: Array[Byte] := "é".to_bytes()
let magic: Array[Byte] := [0x89u8, 0x50u8, 0x4Eu8, 0x47u8]
print(bytes)                       -- [195, 169]
let b: Byte := bytes.get(0)
print(b.to_hex())                  -- "c3"
print(b.bitwise_not())             -- 60
let total: Integer := b + bytes.get(1)
print(total)                       -- 364
let narrowed: Byte := (total - 200).to_byte()
print(narrowed)                    -- 164

Integer16 and Integer32

Integer16 and Integer32 are signed fixed-width integers: -32768..32767 and -2147483648..2147483647. They are for binary formats, protocols and interop where a value has an exact width. Like Byte, each is a distinct type related to Integer the way Integer is related to Real.

• No implicit conversion. None of Integer, Integer16, Integer32 and Byte converts to another without a call, in either direction. let b: Integer32 := a where a is an Integer16 is a type error; write a.to_integer32().
• Literals. An integer literal with an i16 or i32 suffix: 300i16, 0xFFFFi32, 1_000i32. A negative one is written with a leading - and is a single literal of that type: -5i16 is an Integer16, and -32768i16 is valid. (Elsewhere -x on a sized variable promotes to Integer, like any arithmetic.) An unsuffixed literal is an Integer, so let a: Integer16 := 5 is a type error; write 5i16. A literal outside the type's range is rejected.
• Conversions. Narrowing is checked: n.to_integer16(), n.to_integer32() and n.to_byte() raise unless the value fits. Widening (Byte to Integer16/Integer32, Integer16 to Integer32) also uses these methods and always succeeds. x.to_integer() gives the Integer.
• Arithmetic (+ - * / % ^, unary - on a variable) promotes to Integer, so the result of a + a is an Integer and cannot overflow the narrow type; narrow it back with (a + a).to_integer16(). Mixing with Real promotes to Real.
• Comparison (= /= < <= > >=) is between two values of the same type. Comparing across types needs a conversion first. a.equals(x) is true only when x has the same type and value.
• convert does not change representation, so convert n to a: Integer16 on an Integer is rejected. A value keeps its type inside an Any: type_of reports "Integer16", and convert x to a: Integer16 succeeds only for one.
• Bitwise methods work on, and wrap to, the type's own width, and return the same type: 0i16.bitwise_not() is -1i16, and 32767i16.bitwise_left_shift(1) is -2i16. Right shift copies the sign bit; bitwise_logical_right_shift shifts in zeros. Bit indexes must be 0..15 (Integer16) or 0..31 (Integer32); shift counts must be non-negative, and shifting by the width or more clears every bit (except an arithmetic right shift of a negative value, which gives -1). abs raises for the minimum value, which has no positive counterpart. (Integer's own bitwise methods keep their 32-bit behaviour.)
• Java interop: passed to a reflective Java call, an Integer16 or Integer32 goes as an integer, so it can be used wherever an Integer can.

Both types have the same methods. T below is the type itself.

let port: Integer16 := 8080i16
let offset: Integer32 := -70000i32
print(port.to_string(16))            -- "1f90"
print(offset.abs())                  -- 70000
print(port.bitwise_left_shift(4))    -- -1792 (129280 wrapped to 16 bits)
let wide: Integer := port + offset   -- arithmetic promotes to Integer
print(wide)                          -- -61920
let back: Integer16 := (wide + 61920 + 100).to_integer16()
print(back)                          -- 100

Real

Real literals must include at least one digit after the decimal point. Valid forms include 3.14, 10.0, .5, and 12.0e-3. Forms such as 10. and 12.e-3 are not valid real literals.

Real is an IEEE-754 double on every backend, in representation and arithmetic. Division by zero follows IEEE rather than raising: 1.0 / 0.0 is Infinity, -1.0 / 0.0 is -Infinity, and 0.0 / 0.0 is NaN. (Integer division by zero, by contrast, raises.)

The math methods follow IEEE-754 as division does: outside a function's domain the result is NaN or an infinity, not an error. (-1.0).sqrt and 2.0.asin are NaN, 0.0.log is -Infinity. Test with is_nan/is_finite. Only the Integer-returning round, floor, ceiling and truncate raise, since no Integer stands for NaN, an infinity, or a value outside the Integer range.

let area: Real := Real.PI * (r ^ 2)
let angle: Real := 45.0.to_radians
print(angle.sin)                  -- 0.7071067811865475

Boolean

Char

Examples

let s := "  Nex  "
print(s.trim().to_upper())        -- "NEX"
print(s.contains("ex"))           -- true

let n: Integer := 7
print(n.plus(5))                  -- 12
print(n.pick())                   -- random integer in [0, 7)
print(5.bitwise_left_shift(1))    -- 10
print(6.bitwise_and(3))           -- 2

let r: Real := 3.6
print(r.round())                  -- 4

let b: Boolean := true
print(b.and(false))               -- false