Type System in CSL

void type

Expressions of type void have a single possible value. It describes constructs that do not produce a result. For example, blocks are expressions that have type void and void is the return type of functions and builtins that do not return anything. Using a block as an expression, the void value can be expressed with {}:

const void_val = {}; // type is void.
const also_void_val : void = foo();

fn foo() void {}

void is allowed at runtime as a function return type. All other uses of void values must be comptime-known; see Comptime for more information on comptime.

Numeric Types

These types describe numbers:

  • signed integers (i8, i16, i32, i64)

  • unsigned integers (u8, u16, u32, u64)

  • arbitrary precision integers (comptime_int)

  • floating point numbers (f16, f32, comptime_float)

The comptime_int Type

Values of comptime_int type can hold arbitrarily large (or small) integers. Integer literals have type comptime_int:

const ten = 10; // type is comptime_int.
const also_ten : comptime_int = 10;

Character literals also have type comptime_int:

const some_char = 'a';          // type is comptime_int, value is 97
                                // (ASCII value of 'a')
const some_other_char = '\x0a'; // type is comptime_int, value is 10
                                // (i.e., 0x0a, in hexadecimal)
const yet_another_char = '\n';  // type is comptime_int, value is 10
                                // (ASCII value of newline character)

Arithmetic between comptime_int values happen at compile time, produce another comptime_int value, and never underflow or overflow:

const thousand = 1000;
const trillion = thousand * thousand * thousand * thousand;
const one = trillion / trillion;

Operations between a value of type comptime_int and a value of fixed-precision integer type cause the comptime_int value to be converted to the fixed-precision type. An error is emitted upon overflow or underflow:

const thousand = 1000; // comptime_int.
const ten : i16 = 10;  // 10 is converted from comptime_int to i16.
const hundred : i16 = thousand / 10; // thousand is converted to i16.

const overflow : i16 = 10000000000000; // error.

The builtin @as can be used to force literals to have a specific width, for example @as(u16, 1) | 0xbeef.

All values of type comptime_int must be comptime-known, see Comptime for more information on comptime.

The comptime_float Type

Values of comptime_float type can hold any IEEE double precision floating point number. Float literals have type comptime_float:

const ten = 10.0; // type is comptime_float.
const also_ten : comptime_float = 10.0;

Arithmetic between comptime_float values happen at compile time and produce another comptime_float value. If an operation performs division by zero or generates a NaN value, an error is emitted.

Operations between a value of type comptime_float and a value of different float type cause the comptime_float value to be converted to other float type. An error is emitted if this is not possible.

All values of type comptime_float must be comptime-known, see Comptime for more information on comptime.

The type Type

In CSL, the type type can be used to describe values that are themselves types:

const my_type = i16;
const same_type : type = i16;

These values can be used anywhere a type is expected.

const my_type = i16;
const array = @zeros([10]my_type);

fn foo() my_type { ... }

All values of type type must be comptime-known, see Comptime for more information on comptime.

Function Types

Values of function type contain the name of a function and may be used anywhere a function is expected. The type is written as fn(<arg types>) <return_type>.

fn foo(arg1 : i16, arg2 : f16) void {...}

const also_foo1 = foo;
const also_foo2 : fn(i16, f16) void = foo;

also_foo1(10, 10.0);
also_foo2(20, 20.0);

Copying a function value does not create a new function, it copies the name of the function.

All values of function type must be comptime-known, see Comptime for more information on comptime.

Struct Types

There are three kinds of struct types in CSL: anonymous structs, named structs, and comptime_struct.

The Anonymous Struct Types

Anonymous struct types are defined by an optional list of field names and a list of types. Two anonymous struct types are the same if they have the same list of field names (or both lack field names) and the same list of types.

A value of an anonymous struct type with named fields is created with the syntax: .{.field1 = value1, .field2 = value2, ...}. A value of an anonymous struct type with unnamed fields is created with the syntax: .{value1, value2, ...}.

Anonymous struct types with nameless fields are also known as tuple types. The elements of tuples may be accessed with the [] operator, as long as the index is known at compile time.

// Type: {a : comptime_int, b : comptime_float}
var struct1 = .{.a = 10, .b = 1.0};
var struct2 = .{.a = 20, .b = 2.0};
var struct1 = struct2; // ok, same type!


// Type: {a : comptime_float, b : comptime_float}
var struct3 = .{.a = 10.0, .b = 1.0};
struct3 = struct1;           // error: different types!
var some_float = struct3[1]; // error: struct3 is not a tuple type!

// Type: {comptime_float, comptime_float}
var struct4 = .{10.0, 1.0};
var some_float = struct4[0];       // ok!
var some_other_float = struct4[2]; // error: index 2 is out of bounds!
task t(i: u16) void {
    var yet_another_float = struct4[i]; // error: i is not known
                                        // at comptime!
}

Currently, it is not possible to spell out anonymous struct types using CSL syntax.

The Named Struct Types

Named struct types are similar to anonymous struct types, except that two named struct types defined at different places in the source code are considered to be different types, even if their field names and types are the same.

A named struct type is expressed with the form struct { field1: type1, field2: type2, ... }. Once a named struct type has been defined, a value of that type can be created by giving the name of the type, followed by a field initializer list of the form { .field1 = value1, .field2 = value2, ... }.

const complex = struct {
  real_part: f16,
  imag_part: f16
};

const one = complex { .real_part = 1.0, .imag_part = 0.0 };
const zero = complex { .real_part = 0.0, .imag_part = 0.0 };

As mentioned above, two named struct types are considered equal if and only if they have identical field names and types _and_ they were both defined at the same point in the program (i.e., by the same struct expression).

const some_struct = struct {
  x: i16,
  y: i16
};

const some_other_struct = struct {
  x: i16,
  y: i16
};

comptime {
  @comptime_assert(@is_same_type(some_struct, some_struct));
  @comptime_assert(@is_same_type(some_other_struct, some_other_struct));

  // Although some_struct and some_other_struct have the same field names and
  // types, they are *not* the same type, because they were defined at
  // different source locations.
  @comptime_assert(!@is_same_type(some_struct, some_other_struct));
}

Named struct types can also be returned from functions. When combined with comptime type arguments, this can be used to define parameterized struct types, whose field types can be customized by the user.

fn pair(comptime T1: type, comptime T2: type) type {
  return struct {
    first: T1,
    second: T2
  };
}

const my_pair = pair(i32, comptime_string) {
  .first = 42,
  .second = "this is a struct"
};

comptime {
  @comptime_assert(@is_same_type(@type_of(my_pair),
                                 pair(i32, comptime_string)));
  @comptime_assert(@is_same_type(@type_of(my_pair.first), i32));
  @comptime_assert(@is_same_type(@type_of(my_pair.second), comptime_string));
}

The fields of a struct can be mutated by assigning to them via . syntax.

const s = struct {
   x: i32,
   y: i32
};

comptime {
  var my_s = s {
    .x = 15,
    .y = 99
  };

  @comptime_assert(my_s.x == 15);
  @comptime_assert(my_s.y == 99);

  my_s.x = 0;
  my_s.y = 33;

  @comptime_assert(my_s.x == 0);
  @comptime_assert(my_s.y == 33);
}

The comptime_struct Type

The comptime_struct type serves as a superset of all struct types: any value of any struct type, whether anonymous or named, may be assigned to a variable of type comptime_struct:

comptime {
  // Type: {a : comptime_int, b : comptime_float}
  var some_struct = .{.a = 10, .b = 1.0};

  var any_struct : comptime_struct = some_struct; // ok!

  // Type: {name: comptime_string}
  const different_struct = .{.name = "Bob"};
  any_struct = different_struct; // ok!

  const some_named_struct_ty = struct { name: comptime_string, age: i32 };
  any_struct = some_named_struct_ty { .name = "Mary", .age = 61 }; // ok!
}

All values of type comptime_struct must be comptime-known, see Comptime for more information on comptime.

Enumeration Types

An enumeration type is a set of named elements, each of which is represented by a unique integer value:

const colors = enum(u16) { red, white, blue };
const favorite = colors.red;

The underlying integer type is specified by the type argument (u16 in the example above) and it can be any fixed-precision integer type (e.g. i16 or u32).

Any element can be assigned a comptime-known integer value:

const colors = enum(u16) { red, white = 1, blue };

The values assigned must be unique within the type. Any element not assigned a value will be assigned a value by the compiler. The compiler assigns values from left to right, using consecutive integers starting with zero. In the example above, the compiler will assign the value 0 to red and the value 2 to blue. If white is instead assigned the value 4, then the compiler will assign the value 0 to red and 1 to blue.

Enumeration type values can be cast to and from their underlying numeric values using the @as() builtin, as the following assertions demonstrate:

@comptime_assert(@as(i16, colors.red) == 0);
@comptime_assert(@as(u16, colors.white) == 1);
@comptime_assert(@as(f32, colors.blue) == 2.0);
@comptime_assert(@as(colors, 1) == colors.white);

An enumeration type can be cast to and from any numeric type regardless of its underlying integer type, subject only to the general compatibility rules of type casts.

An enumeration value cannot be cast directly to a value of another enumeration type, but the same effect can be achieved by casting via a numeric type:

const game = enum(i16) {rock, paper = -3, scissors};
// @as(color, game.rock)  <= Error!
const myred = @as(colors, @as(u16, game.rock)); // OK
@comptime_assert(@as(colors, as(i16, colors.white) + 1)) == colors.blue);

Two expressions of the same enumeration type can be compared using the == and != operators.

Enumeration Type Equality

Two enumeration types are the same if and only if both of the following conditions are true:

  • they have the same structure, i.e., the same underlying integer type, and the same set of element values, each of which is assigned the same numeric value.

  • their definitions originate at the same source code location.

const e1 = enum(i16) {red, white};
const e2 = enum(i16) {red, white};

fn enum_type(base_type: type) type {
  return enum(base_type) {red, white};
};

const e3 = enum_type(i16);
const e4 = enum_type(i32);
const e5 = e1;
const myred = e1.red;

// different types, not originating from the same location:
@comptime_assert(!@is_same_type(e1, e2));
// different types, same originating location, but not same structure
@comptime_assert(!@is_same_type(e3, e4));
@comptime_assert(@is_same_type(e5, e1)); // same type
@comptime_assert(@is_same_type(@type_of(myred), e5); // same type

Array Types

An array type is parameterized by an element type, describing a collection of elements of the base type. An array type whose element type is T can be written as [size]T.

The element type must not be another array type. Multidimensional arrays are specified with a sequence of dimensions: [size1, size2, size3]T.

var 1d_array = @zeros([10]u16);
var 2d_array = @zeros([10, 10]u16);
var another_array = [2]i16 {1,2}

Pointer Types

A value of pointer type contains the memory address where a variable is located.

Pointer types are described by an element type and an optional const qualifier.

In CSL, pointers are only created by taking the address of a variable. This provides the property that pointers always point to valid data when they are created.

There are two kinds of pointers in CSL: pointers to a single element and pointers to an unknown number of elements.

Pointers to a Single Element

A pointer to a single value of type T is written as *T. For example:

  • a pointer to a single i16 is written as *i16

  • a pointer to a single array of ten integers is written as *[10]i16.

Pointers to a single element are created with the address-of operator (&):

var array = @zeros([10]u16);
const ptr = &array;
const same_ptr:*[10]u16 = &array;

The only operation allowed on pointers to a single element is to dereference them with the dereference .* operator:

var array = @zeros([10]i32);
const ptr = &array;
ptr.* = @constants([10]i32, 42);
ptr.*[2] = 1;

Pointer types may be const qualified, indicating that this pointer may not be used to modify the underlying memory:

var array = @zeros([10]i32);
var ptr:*const[10]i32 = &array;
ptr.* = @constants([10]i32, 42); // Error: pointer type is const qualified.
ptr.*[2] = 1; // Error: pointer type is const qualified.
const array = @zeros([10]i32);
var ptr = &array;  // Type of ptr is *const[10]i32
ptr.* = @constants([10]i32, 42); // Error: pointer type is const qualified.
ptr.*[2] = 1; // Error: pointer type is const qualified.

In the example above, ptr itself is mutable, but the memory it points to is not.

Pointers to Unknown Number of Elements

A pointer to an unknown number of elements of type T is written as [*]T. For example, a pointer to an unknown number of f16 elements is written as [*]f16.

Pointers to an unknown number of elements are created through coercion from pointers to a single element of array type (e.g. *[2]i16):

fn foo(ptr : [*]i32) void {
 // ...
}

var array10 = @zeros([10]i32);
var array20 = @zeros([20]i32);
foo(&array10); // ok!
foo(&array20); // ok!

var array_float = @zeros([20]f16);
foo(&array_float); // Error: base type mismatch.

var ptr : [*]i32 = &array10;
ptr = &array20;

The original array must have rank one:

var array = @zeros([3,3,3]i32);
var ptr : [*]i32 = &array; // Error.

Dereferencing a pointer to an unknown number of elements is not allowed. The access operator [] must be used instead:

fn foo(ptr : [*]i32) void {
  ptr.* = 10; // Error: dereferencing is not allowed.
  ptr[0] = 10;
}

It is illegal to access an element whose index is out-of-bounds on the original array:

fn foo(ptr : [*]i32) void {
  ptr[1000] = 10;
}

var array10 = @zeros([10]i32);
foo(&array10); // Bad: will create out-of-bounds access.

An error is emitted if the compiler is able to detect an out-of-bounds access.

The comptime_string Type

Warning

Support for compile-time strings is still experimental, and the set of operations available on the type comptime_string is very limited.

Values of comptime_string type hold immutable strings that can be manipulated at compile time. All values of type comptime_string must be comptime-known. See ref:language-comptime for more information on comptime.

const hello = "abc"; // type is comptime_string

fn bool_to_str(b: bool) comptime_string {
   if (b) {
     return "true";
   } else {
     return "false";
   }
}

comptime {
  const true_str = bool_to_str(true);
  @comptime_assert(true_str == "true");

  var s = "hello";
  @comptime_assert(s == "hello");
  s = "goodbye";
  @comptime_assert(s != "hello");
  @comptime_assert(s == "goodbye");
}

As in C and C++, strings in CSL are sequences of bytes. A Unicode character may correspond to a sequence of more than one byte, and CSL does not have a “wide character” type.

Like std::string in C++, but unlike char * strings in C, strings in CSL are not null-terminated. This means that the NUL character can occur anywhere in a string. For example, the following @comptime_asserts will succeed:

@comptime_assert("abc\x00xyz" != "abc")
@comptime_assert("abc\x00xyz" == "abc\x00xyz")
@comptime_assert(@strlen("abc\x00xyz") != 3)
@comptime_assert(@strlen("abc\x00xyz") == 7)

UTF-8 encoded text is allowed in string literals, but if the text contains non-ASCII characters, the length of the string (as returned by @strlen) will not necessarily match the number of characters in the string. For example, the @comptime_asserts in the following code will succeed:

// Note: The UTF-8 encoding of the "thumbs up" emoji is F0 9F 91 8D.

const thumbs_up = "👍";
@comptime_assert(@strlen(thumbs_up) == 4);

var as_array: [4]u8 = @get_array(thumbs_up);
@comptime_assert(as_array[0] == 0xf0);
@comptime_assert(as_array[1] == 0x9f);
@comptime_assert(as_array[2] == 0x91);
@comptime_assert(as_array[3] == 0x8d);

The imported_module Type

TODO.

The direction Type

TODO.