Operators
Expression binding order
Calls, member selection, indexing, slicing and postfix non-null ! chain on their target before prefix operators. Thus value!.read() checks value before calling read, and !callback!() negates the checked callback's result. Prefix !, +, -, ^, *, &, <-, go, and await bind before type assertions (as? T, as! T) and result propagation (?). Binary expressions then group by the table below. Parentheses override that order; write (<-channel)! to assert the received reference, not the channel itself.
Binary precedence
From lowest to highest; every binary group is left-associative:
| Level | Operators | Operand summary |
|---|---|---|
| 1 | ?? | Nil fallback, or missing-key/closed-receive fallback for value payloads |
| 2 | || | boolean |
| 3 | && | boolean |
| 4 | ==, !=, ===, !== | Compatible comparable values |
| 5 | <, <=, >, >= | Compatible ordered values |
| 6 | +, -, ` | , ^` |
| 7 | *, /, %, <<, >>, &, &^ | Numeric/integer as applicable |
The grouping follows the implemented Go-compatible bitwise precedence. a + b << c means a + (b << c); a | b + c means (a | b) + c.
Null coalescing
v0.4.12 builds support value ?? fallback. The left operand runs once; the right operand runs only when the value is null or Go nil. This tests absence, not truthiness: zero, false and empty text are ordinary values. Those scalar types cannot be nullable; a literal null ?? 0 is allowed and takes its result type from the fallback or an explicit destination type.
For a direct map lookup values[key] or receive (<-channel) with a payload that has no nil representation, ?? checks the operation's success flag. The fallback runs only for a missing key or closed receive; present 0, false, empty text and zero-valued records are preserved. This also lets a record or fixed array containing non-null references supply a valid initialized default. Reference payloads keep the ordinary nil test, including a present nil payload. The receive keeps Go blocking behavior.
import go fmt from "fmt";
class User {
constructor(public name: string) {}
}
struct Row {
public user: User;
}
function main(): void {
const users = makeMap<string, Row>();
const row = users["missing"] ?? Row { user: new User("guest") };
fmt.Println(row.user.name);
const counts = makeMap<string, int>();
counts["zero"] = 0;
let defaults = 0;
const fallback = (): int => { defaults++; return 9; };
fmt.Println(counts["zero"] ?? fallback());
fmt.Println(counts["missing"] ?? fallback());
fmt.Println(defaults);
const channel = goChannel<int>(1);
channel <- 0;
closeGoChannel(channel);
fmt.Println((<-channel) ?? 7);
fmt.Println((<-channel) ?? 7);
}guest
0
9
1
0
7Generic payloads need a constraint that consistently permits nil or consistently contains value types. For an open T or a reference/value mixture, use the explicit [value, ok] form and check the flag. Ordinary array/slice indexing does not produce a missing-key flag or intercept bounds panics.
constraint Mixed = ~int | ~*int;
function choose<T extends Mixed>(values: Map<int, T>, fallback: T): T {
return values[0] ?? fallback;
}import go fmt from "fmt"
class User {
constructor(public name: string) {}
}
function main(): void {
let calls = 0
const find = (present: boolean): User | null => {
calls++
if (present) { return new User("金木犀") }
return null
}
const missing = find(false) ?? new User("fallback")
const found = find(true) ?? find(false)!
fmt.Println(missing.name, calls)
fmt.Println(found.name)
}The fallback must be assignable to the left operand's non-null type, or to a compatible explicit destination type (for example, a base class or interface). A nullable fallback retains T | null. Choosing a non-null result does not narrow the original nullable binding. Result and Task are not unwrapped; handle them explicitly, including the requirement to consume a Task on every reachable path if await occurs in a conditional fallback.
Chains group left to right. Mixing ?? with && or || requires parentheses, such as null ?? (ready || retry). A bare null ?? null needs a concrete nullable destination type. Go interfaces use their existing nil comparison: an interface containing a typed nil pointer does not select the fallback. For several value-type lookups, nest defaults explicitly: first[key] ?? (second[key] ?? 0).
An inferred result containing an unexported Go type is supported when the storage is a pointer, slice, map, channel or interface and the fallback is a static zero-argument function with matching storage type. Otherwise, supply a compatible public result type, such as an exported Go interface; an unnameable result is diagnosed in Kinmokusei source.
const count = 0 ?? 1Boolean and comparison operators
Prefix ! accepts one boolean. && and || accept boolean operands, evaluate left to right, and short-circuit the right operand when the result is already known.
The two equality spellings are semantic aliases: == and === both perform typed equality, while != and !== both perform typed inequality. None performs JavaScript-style coercion. Operands must have compatible identical types and be comparable; slices, maps, and functions are not generally comparable. A concrete nil-capable or nullable counterpart is required when comparing with nil or null.
Ordering accepts two values of the same ordered type. Numeric widths and signedness are not mixed implicitly; strings use Go's byte-wise lexicographic order.
Numeric identity
Typed binary operands normally require identical numeric types. A representable untyped constant can combine with a typed operand. Operations preserve defined-type identity where Go does. No implicit signed/unsigned or width conversion occurs.
function combine(left: int, right: int32): int {
return left | right;
}Dynamic fixed-width arithmetic preserves Go overflow behavior. Statically known out-of-range constants are source diagnostics.
Unary + and - require numeric values. Binary +, -, *, and / require compatible numeric operands; % is integer-only. + also concatenates two compatible strings. Constant integer division or remainder by zero is rejected, while a data-dependent zero divisor retains Go's runtime panic behavior.
function divide(value: int): int {
value /= 0;
return value;
}Shifts and bitwise operators
&, |, ^, &^, <<, and >> require integers; unary ^ is integer complement. Shift operands need not share a type, and the result has the left operand's type.
Negative constant shifts and the compiler's constant-shift limit are rejected before generation. Dynamic negative shifts retain Go runtime panic behavior. Unary &value is address acquisition; binary left & right is bitwise AND.
function move(value: int): int {
return value << -1;
}For a nonconstant shift such as 1 << n, an untyped left operand takes its integer type from the destination or a typed peer. This also permits 1.0 << n in an integer context: the literal is exactly representable as an integer. Array indices, slice bounds and allocation sizes supply an int context.
import go fmt from "fmt";
function mask(n: uint): byte {
return 1 << n;
}
function main(): void {
const n: uint = 2;
const values = make[int[]](1.0 << n, 2.0 << n);
fmt.Println(mask(n), len(values), cap(values));
}The left operand must fit that type before shifting: 300 << n cannot produce a byte, even if a particular shift count would discard the high bits. A floating-point destination is invalid. Without an integer context, const value = 1.0 << n defaults to a floating-point type and is rejected. An already stored runtime value keeps its type; a later use cannot retroactively change the type of its initializer.
function mask(n: uint): byte {
return 300 << n;
}The numeric and bitwise recipe traces masks, complement, signed shift behavior, compound updates, and explicit width conversion in one runnable program.
Pointer operators
| Operator | Meaning |
|---|---|
&value | Address of an addressable value |
*pointer | Dereference a pointer |
Non-addressable temporaries are rejected. Nil pointer dereference preserves Go panic behavior.
struct Point {
public x: int;
}
function makePoint(): Point {
return Point { x: 1 };
}
function invalid(): *Point {
return &makePoint();
}Updates
Supported update statements:
+= -= *= /= %= &= |= ^= &^= <<= >>= ++ --Targets can be identifiers, writable fields/properties, assignable indexes, or pointer dereferences. Property updates require an accessible getter and setter and perform ordered read/modify/write calls, not atomic mutation. Generated compound assignment evaluates a selector/index/pointer target once. ++ and -- never produce a value.
Strings support only +=. Remainder and bitwise updates require integers. Map indexes are writable; string indexes, methods, constants, and non-addressable temporary fields/array indexes are not.
Assertions and conversions
Postfix value! checks a nullable or raw nil-capable reference once and yields its non-null value. A nil value panics at the assertion's source filename, line and column. This is an actual runtime check, not TypeScript's erased assertion. An interface holding a typed nil pointer is still a non-nil interface; the check does not inspect hidden pointees. Result, Task, scalars and structs cannot be unwrapped this way. A newline before ! starts a prefix operation instead.
import go { Println } from "fmt"
class User {
constructor(public name: string) {}
}
function configuredUser(): User | null {
return new User("Kinmokusei")
}
function main(): void {
const user = configuredUser()!
Println(user.name)
}as? Type performs a checked Go-interface or class downcast and returns value plus boolean. as! Type is forced and panics on failure. Both evaluate the source once.
Explicit conversions to non-null source function and anonymous interface contracts also reject a nil result at the conversion's source location. Checked non-null conversions and forced source assertions establish a proof for a nullable snapshot; raw Go conversions and raw Go assertion targets keep their existing nil semantics. See explicit conversions.
v0.4.12 builds require [value, ok] and a successful flag check before using an unsafe-zero checked assertion payload. Forwarding the unchecked pair directly through a function return or argument list is rejected; split it and handle failure explicitly. Whole-result _ discard remains explicit discard.
Native generic class downcasts check the source type arguments, not just their generated Go storage. Box<bstring> is not Box<string>, even when the raw bytes happen to be valid UTF-8. The same distinction applies inside arrays, other generic arguments, and nullable types. A matching native construction can round-trip through its base class; a mismatched checked cast returns false, and a mismatched forced cast panics. Downcasting never validates or converts the contents of a box.
Native calls carry private contract information through generic functions and constructors. Public Go function and method signatures remain unchanged, but a direct Go call supplies no proof of native-only qualifiers. Boxes constructed through that path, or generic arguments erased by an ordinary Go method or interface call, cannot subsequently establish a native generic downcast when its source contract is unknown. Use a Kinmokusei factory to construct boxes that must later be recovered by native checked downcasts. Public Go conversion helpers retain Go projection behavior; they are not native contract validators.
Type-name calls such as int64(value) or UserID(text) are explicit conversions and follow representability, identity, and Go convertibility rules for the source/target pair.
Result propagation
Postfix ? accepts Result<T>, a compatible Go (T, error) result, or a single error inside a Result-returning function. It evaluates the operation once and returns early when the error is non-nil.
A non-void propagated value must directly initialize one binding; propagation cannot be buried in an arbitrary expression. A void or single-error operation may stand alone. Use Failures, Result, and exceptions for the full return and cleanup contract.