Docs/Language guide

Structs & named types

Model data with value types, methods, and deliberate type identities.

Struct values#

Fields use name type ordering. A field may share its name with its type, as in Header Header. Recursive owning array or map layouts are unsupported and produce a compiler diagnostic; use explicit pointers for recursive ownership. Struct literals can initialize fields positionally or by name. Struct assignment copies the fields, including owned nested values. Explicit pointers preserve shared references.

A struct groups named fields into one value. Each field has its own type, and field access uses a dot, such as point.x. The type declaration describes the layout; a struct literal constructs a value using that description. A function can return the struct just as it returns an integer or string.

Positional literals follow field declaration order. Keyed literals name the fields they initialize and are useful when a struct has several similar-looking values. Omitted fields receive defaults. Assigning a struct to another variable creates a separate struct value. Owned fields such as strings, arrays, and maps are copied recursively. A pointer field copies its address, so its target remains shared.

Ocean
struct Point {
    x float;
    y float;
}

func origin() Point {
    return Point{0.0, 0.0};
}

The returned Point has both coordinates set to 0.0. A caller can store it with point := origin(); and update point.x. Assigning it to another variable makes a separate struct value, so changing a coordinate in that copy does not change point.

Methods#

Declare methods in the package that defines the receiver type; imported types and aliases of them cannot receive new methods. Place a receiver before the method name. A value receiver works on a copy; a pointer receiver can update the original. When a value stored in a variable calls a pointer-receiver method, Ocean can pass the variable’s address automatically. “Addressable” means the expression refers to storage whose address can be taken; a temporary result is not automatically such storage.

The receiver gives a method access to the value on which it was called. A value receiver is suitable for reading fields or computing a result. A pointer receiver is appropriate when the method needs to modify the original stored fields. The distinction appears directly in the receiver’s type.

Automatic borrowing makes an addressable variable convenient to call without hiding the declaration’s behavior: counter.Increment() still invokes a pointer receiver. A value receiver copies its struct even when the call is made through a pointer.

Ocean
struct Counter { value int; }

func (counter *Counter) Increment() {
    counter.value++;
}

func (counter Counter) Value() int {
    return counter.value;
}

For counter := Counter{0};, calling counter.Increment(); updates the field to one. Calling counter.Value() returns that integer. Methods are associated with their declared types; they are not separate fields storing callable function values.

Definitions and aliases#

type Name Existing creates a distinct type with the same underlying storage layout. type Name = Existing creates another name for exactly the same type. Distinct definitions require explicit casts when converting to or from their underlying type.

A defined type is useful when two values have the same machine representation but mean different things. A user identifier can use integer storage while remaining distinct from an ordinary count. That distinction participates in assignments, function signatures, and generic type checking.

An alias is useful for another spelling of an existing type, such as a shorter name at a package boundary. It does not create a new conversion requirement. Defined types can declare their own methods; aliases use the method set of their target.

Ocean
type UserID int;
type AccountID = UserID;

// Inside a function:
id := 42 -> UserID;
alias: AccountID = id;
number := id -> int;

Here, AccountID and UserID refer to the same type, so assigning id to alias is direct. UserID and int have distinct identities, so the example uses arrow casts to cross that boundary. The underlying integer representation remains the same.

Value parameters#

A struct can carry immutable value parameters before its ordinary fields. They are stored as the first fields, ahead of the fields written in the struct body. The initializer supplies them once, and they cannot be reassigned afterward. They are distinct from compile-time generic type arguments.

Value parameters become stored fields, with names and types, before the fields in the struct body. They can record configuration that is chosen at initialization and should remain unchanged for that value’s lifetime. Their immutability applies to those bindings, including attempts to take a mutable address of them.

Generic type parameters instead choose types during specialization, as in Box<int>. Value parameters do not turn each parameter value into a separately specialized type. Read the initializer in field order: immutable parameter fields first, then ordinary fields.

Ocean
struct Sample(tag int) {
    value float;
}

// Inside a function:
sample := Sample{7, 3.5};
sample.value = 4.0;
// sample.tag is immutable.

The literal initializes tag to 7 and value to 3.5. Updating sample.value is allowed because it is an ordinary mutable field. Assigning another number to sample.tag is rejected by the frontend.