Docs/Language guide

Generics & interfaces

Reusable types and functions with explicit specialization and type constraints.

Type parameters#

Generic declarations accept type parameters in angle brackets. An omitted constraint defaults to any. Calls require explicit type arguments: Ocean does not currently infer generic function arguments. Each concrete set of type arguments selects a version of the declaration with those types substituted. This concrete version is called a specialization; for example, Box<int> uses int wherever the declaration uses T.

A type parameter lets one declaration describe several concrete functions or data layouts. Inside Box<T>, the field’s type is whichever concrete type was supplied for T. A generic function uses the same idea in its parameters and result. The compiler specializes concrete uses rather than requiring the caller to pass a runtime type descriptor for an ordinary concrete struct.

any is the default constraint when no narrower requirement is written. A constraint limits which types are accepted. Type parameters are not values: for example, zero(T) constructs a default value of the selected type.

Ocean
struct Box<T> { value T; }

func identity<T>(value T) T {
    return value;
}

// Inside a function:
box := Box<int>{42};
answer := identity<int>(box.value);

The struct literal produces a Box<int> with an integer field. identity<int> then accepts that integer and returns an integer. Write the call’s type arguments explicitly even when their intended types look obvious from the value arguments.

Method interfaces and type lists#

An interface can contain method signatures and embedded type constraints, including a type list separated by |. Method receivers are implied, parameter names are optional, and methods can have their own generic type parameters. The func keyword is optional on interface method signatures. A type-list interface may omit its final semicolon.

An exact type list such as int | float accepts int, float, and aliases of either type. It does not accept a distinct defined type merely because that type uses integer storage. For example, type ID int; declares a new type; ~int accepts both int and defined types whose underlying type is int, including ID. The narrower types i8 and i32 have different underlying storage types and are not included by ~int.

Type lists also work directly in function parameter lists. Equality (== and !=) is available on every generic type parameter, including unconstrained T. Other operators on generic and interface operands require every possible type to support them. Numeric int | float lists support arithmetic and comparisons; integer-only operators require integer-only lists. In add<T Number>(x, y T), both arguments are checked against the one concrete type chosen for T. In sum(x, y int | float), each argument is an independent interface value: one may hold an int while the other holds a float. An operator used on those independent values must work for every permitted combination of their types.

Ocean
interface Arithmetic {
    func add(int) int;
    func subtract(other int) int;
    func multiply<T int | float>(T) float;
}
interface Number { int | float }
interface Integer { ~int }

func add<T Number>(x, y T) T { return x + y; }
func sum(x, y int | float) int | float { return x + y; }

Use type lists to describe the types allowed by a constraint. Older operator-requirement syntax and membership forms such as -Type, +Type, and =Type are not the current syntax. Interfaces may combine method signatures with embedded type constraints. Use named receiver methods for custom struct operations; struct operator overloading is unsupported. Calls through boxed method interfaces dispatch to the concrete receiver, including explicit generic method specializations, variadic calls, embedded methods, and deferred calls.

Generic methods#

Receiver arguments bind the struct’s type parameters. A method may introduce separate generic parameters after its name; pass those arguments explicitly at the call.

The receiver Box<T> introduces the struct’s type parameter to the method’s signature and body. You do not declare it again after the method name. A second parameter such as U belongs to the method itself, so it is declared after the method name and must have a different name.

This allows a method to combine a value stored in the receiver with a separately typed argument. Its result signature can refer to both parameters. Each concrete receiver and method argument combination gets its own specialization.

Ocean
func (box Box<T>) Pair<U>(other U) (T, U) {
    return box.value, other;
}

// Inside a function:
box := Box<int>{3};
number, flag := box.Pair<bool>(true);

With Box<int> as the receiver and <bool> at the call, the result types are (int, bool). The bindings receive 3 and true. Method type arguments are explicit, just like direct generic function type arguments.

Interfaces and mixed arrays#

Method interfaces describe required method signatures. T[] is homogeneous, even when T is an interface: elements share a concrete type. mixed T[] permits multiple concrete types satisfying the interface. any is the empty interface.

An interface specifies method names and exact signatures that a concrete type must satisfy. If a required method is implemented only with a pointer receiver, a pointer to that concrete type satisfies the interface; a non-pointer value of the type does not gain that method merely from automatic borrowing at a direct method call. any has no method requirements, so it can hold a boxed value of any supported concrete type.

An interface bound does not by itself make an array heterogeneous. For example, any[]{1, 2} is homogeneous because both elements are integers, but any[]{1, "two"} is rejected because it combines an integer and a string. Use mixed any[]{1, "two"} for that mixture. Adding mixed permits different concrete element types, provided each one satisfies the interface bound. This distinction is checked both statically where possible and at runtime for boxed conversions and writes.

Maps use a different rule: an interface in either map[K]V position always permits mixed concrete types on that side. Thus map[any]any{1: "one", "two": 2} needs no mixed keyword. Every key and value must still satisfy its own declared interface constraint.

Ocean
interface Value { Get() int; }
struct Reading { value int; }
func (r Reading) Get() int { return r.value; }

// Inside a function:
items := mixed any[]{42, "Ocean", true};

The Reading type satisfies Value through its Get method. The separate mixed any[] literal can contain an integer, a string, and a boolean together. For example, reading: Value = Reading{value:42}; supports reading.Get() directly. Mixed Value arrays and map values also support method calls.

Narrow with a type switch#

A type-guard switch inspects concrete identity. Put specific cases before broad family cases. Box matches any specialization; Box<int> matches its integer specialization. In a case naming one specific type, the case-local variable is checked as that type, allowing operations such as reading the concrete type’s fields.

A broad generic family name can describe several specializations when used as a constraint. For example, a parameter declared as Box can receive both Box<int> and Box<bool>. The actual concrete identity is retained so a type switch can distinguish them.

Inside a single-type case, the case binding has that case’s type constraint. This permits concrete field operations after narrowing. A family case such as case Box: says only that the value is some Box specialization; it does not choose a field type for T. Use a more specific case such as case Box<int>: before reading or operating on fields that depend on T.

Ocean
func inspect(box Box) int {
    switch (item := box.(type)) {
    case Box<int>:
        return item.value;
    case Box:
        return 0;
    default:
        return -1;
    }
}

An integer box reaches the first branch, where item.value has type int. Another box specialization reaches the family branch and returns zero. The more specific case must come first because cases are considered in source order.

Current boundaries#

Struct operator overloading is not supported. Define named receiver methods for custom struct operations. Generic functions require explicit type arguments before use as values. Type argument inference and values made by extracting a method from its receiver, such as counter.Increment are not implemented by the backend. Parser acceptance alone does not guarantee executable support. Use ocean check to validate the complete path through native linking.

Separate the syntax accepted by the parser from operations that the native backend can actually compile. An unsupported construct can parse successfully and then fail during checking or code generation. ocean check exercises the full compilation path without executing the program, which is the most useful validation when experimenting with a feature.

For current code, prefer direct calls, concrete specializations, and explicit type switches. Declared interface methods support dynamic dispatch to the boxed concrete receiver. Generic calls still require explicit type arguments; extracting a bound method value remains unsupported.