All Features

Here is a summary of all the features of C3 and how it differs from C.

Symbols and literals

Changes relating to literals, identifiers etc.

Added

0o prefix for octal.
0b prefix for binary.
Optional _ as digit separator.
Hexadecimal byte data, e.g x"abcd".
Base64 byte data, e.g. b64"QzM=".
Type name restrictions (PascalCase).
Variable and function name restrictions (must start with lower case letter).
Constant name restrictions (no lower case).
Character literals may be 2, 4, 8, 16 bytes long. (2cc, 4cc etc).
Raw string literals between ”`”.
\e escape character.
Source code must be UTF-8.
Assumes \n for newlines. \r is stripped from source.
Integer suffixes are fixed size: L, UL is 64-bit literals on all platforms, LL and ULL are guaranteed 128-bit literals.
The null literal is a pointer value of 0.
The true and false are boolean constants true and false.

Removed

Trigraphs / digraphs.
0123-style octal.
z, LL and ULL suffixes.

Built-in types

Added

Type declaration is left to right: int[4]*[2] a; instead of int (*a[2])[4];
Simd vector types using [<>] syntax, e.g. float[<4>], use [<*>] for inferred length.
Slice type built in, using [] suffix, e.g. int[]
typedef is similar to C’s typedef but forms a new type. (Example: the String type is a new type with char[] internal representation)
Built-in 128-bit integer on all platforms.
char is an unsigned 8-bit integer. ichar is its signed counterpart.
Well-defined bitwidth for integer types: ichar/char (8 bits), short/ushort (16 bits), int/uint (32 bits), long/ulong (64 bits), int128/uint128 (128 bits)
Pointer-sized iptr and uptr integers.
isz and usz integers corresponding to the size_t bitwidth.
Optional types are formed using the ? suffix.
bool is the boolean type.
typeid is a unique type identifier for a type, it can be used at runtime and compile time.
any contains a typeid and void* allowing it to act as a reference to any type of value.
fault a constant representing an error (see below).

Changed

Inferred array type uses [*] (e.g. int[*] x = { 1, 2 };).
Flexible array member uses [*].

Removed

The C “spiral rule” type declaration (see above).
Complex types (implemented as user-defined types instead).
size_t, ptrdiff_t (see above).
Array types do not decay.

Types

Added

bitstruct a struct with a container type allowing precise control over bit-layout, replacing bitfields and enum masks.
fault a constant with unique values which are used together with optional.
Vector types.
Optional types.
Operator overloading for arithmetics, bit operators and equality.
enum allows a set of unique constants to be associated with each enum value.
Compile time reflection and limited runtime reflection on types (see “Reflection”)
All types have a typeid property uniquely referring to that particular type.
Distinct types, which are similar to aliases, but represent distinctly different types.
Types may have methods. Methods can be added to any type, including built-in types.
Subtyping: using inline on a struct member allows a struct to be implicitly converted to this member type and use corresponding methods.
Using inline on a typedef allows it to be implicitly converted to its base type (but not vice versa).
Types may add operator overloading to support foreach and subscript operations.
Generic types through generic modules, using { ... } for the generic parameter list (e.g. List{ int } list;).
Interface types and any types, which allow dynamic invocation of methods.
Types may overload arithmetic operators to implement new numerical types.

Changed

C’s typedef is replaced by alias and has somewhat different syntax (e.g. alias MyTypeAlias = int;).
Function pointer syntax is prefixed by an fn and followed by a regular function declaration without the function name. For example, fn void(int) is the type for a function that takes an int and returns nothing. Named parameters and default arguments are also permitted, such as fn void(int num = 0).
typedef in C3 creates a new type which can have its own methods, but shares the same common internal representation as the original type.

Removed

Enums, structs and unions no longer have distinct namespaces.
Enum, struct and union declarations should not have a trailing ’;’
alias can only be used at the top level, not inside a function.
Anonymous structs are not allowed.
Type qualifiers are all removed, including const, restrict, and volatile. However, const may be applied to compile-time values and each such constant must have its name written in ALL_CAPS.
Function pointers types cannot be used “raw”, but must always be used through a type alias.

Introspection

Compile time type methods: alignof, associated, elements, extnameof, inf, inner, kindof, len, max, membersof, min, nan, names, params, returns, sizeof, typeid, values, qnameof, is_eq, is_ordered.

Runtime type methods: inner, kind, len, names, sizeof.

Expressions

Added

Array initializers may use ranges. (e.g. int[256] x = { [0..128] = 1 })
?: operator, returning the first value if it can be converted to a boolean true, otherwise the second value is returned.
Optionals support an “or else” operator ?? returning the first value if it is a normal (non-fault) result or else the second value if the first value is an abnormal (fault-containing) Optional value. Thus, ?? provides a mechanism for returning default values when evaluations encounter problems.
Rethrow ! suffix operator which implicitly returns the Optional value if it was an abnormal (fault-containing) Optional value.
Dynamic calls, allowing function calls to be made on generic data of type any or to use interfaces as a dynamic dispatching mechanism.
Create a slice using a range subscript (e.g. a[4..8] to form a slice from element 4 to element 8).
Two range subscript methods: [start..inclusive_end] and [start:length]. Start, end and length may be omitted for default values.
Indexing from end: slices, arrays and vectors may be indexed from the end using ^. ^1 represents the last element. This works for ranges as well.
Range assignment, assign a single value to an entire range e.g. a[4..8] = 1;.
Slice assignment: copy one range to the other range, e.g. a[4..8] = b[8..12];.
Array, vector and slice comparison: == can be used to make an element-wise comparison of two containers.
? suffix operator turns a fault into an optional value.
!! suffix panics if the value is an optional value.
$defined(...) returns true if the outermost expression contained within it is defined. Sub-expressions must also be valid.
Compile time “and” and “or” using &&& and |||. Both sides of the operator should be compile-time constants. If the left hand side of &&& is false, the right hand side is not type-checked. For ||| the right hand side is not type-checked if the left hand side is true.
Lambdas (anonymous functions) may be defined. They work just like functions and do not capture any state (i.e. are not “closures”, unlike in some other languages). Not capturing state makes it easier for C3 to retain a simpler lifetime model.
Simple bitstructs (only containing booleans) may be manipulated using bit operations & ^ | ~ and assignment.
Structs may implicitly convert to their inline member if they have one.
Pointers to arrays may implicitly convert to slices.
Any pointer may implicitly convert to an any with type being the pointee.
An optional values will implicitly invoke “flatmap” on an expression it is a subexpression of.
Swizzling for arrays and vectors. For example, to reverse a 3-element vector vec via swizzling you can use vec.xyz = vec.zyx;.

Changed

Operator precedence of bit operations is higher than + and -.
Well defined-evaluation order: left-to-right, assignment after expression evaluation.
sizeof is $sizeof and only works on expressions. Use Type.sizeof on types.
alignof is $alignof for expressions. Types use Type.alignof.
Narrowing conversions are only allowed if all sub-expressions are as small or smaller than the type.
Widening conversions are only allowed on simple expressions (i.e. most binary expressions and some unary may not be widened).

Removed

The comma operator is removed.

Cast changes

Functions

Added

Functions may be called using named arguments. The name is the same as the parameter name, but followed by : in the call. For example: foo(name: a, len: 2).
Typed vaargs are declared Type... argument, and will take 0 or more arguments of the given type.
It is possible to “splat” an array or slice into the location of a typed vararg using ...: foo(a, b, ...list)
any vaargs are declared as argument... (i.e. without a type in the function parameter list). Such a vaarg list can take 0 or more arguments of any type. All passed arguments are implicitly converted to the any type when the function is called.
The function declaration may have @inline or @noinline as a default.
Using @inline or @noinline on a function call expression will override the function default.
Type methods are functions defined in the form fn void Foo.my_method(Foo* foo) { ... }. They can be invoked using dot syntax.
Type methods may be attached to any type, even arrays and vectors.
Error handling uses Optional return types, which are similar to tagged unions that either contain a valid result or a fault state.

Changed

Function declarations use the fn prefix.

Removed

Functions with C-style vaargs may be called, and declared as external functions, but not used for C3 functions.

Attributes

C3 adds a long range of attributes in the form @name(...). It is possible to create custom attribute groups using attrdef (e.g. attrdef MyAttribute(usz align) = { @aligned(align) @weak };) which groups certain attributes. Empty attribute groups are permitted.

The complete list: @align, @benchmark, @bigendian, @builtin, @callconv, @deprecated, @dynamic, @export, @extern, @if, @inline, @interface, @littleendian, @local, @maydiscard, @naked, @nodiscard, @noinit, @noreturn, @nostrip, @obfuscate, @operator, @overlap, @priority, @private, @public, @pure, @reflect, @section, @test, @used, @unused.

Declarations

Added

var declaration for type inferred variables in macros. E.g. var a = some_value;.
var declaration for new type variables in macros. E.g. var $Type = int;.
var declaration for compile time mutable variables in functions and macros. E.g. var $foo = 1;.
const declarations may be untyped. Such constants are not stored in the resulting binary.

Changed

tlocal declares a variable to be thread local.
static top level declarations are replaced with @local. (static in functions is unchanged)

Removed

restrict removed.
atomic should be replaced by atomic load/store operations.
volatile should be replaced by volatile load/store operations.

Statements

Added

Match-style variant of the switch statement, which allows each case to hold an expression to test.
Switching over type with typeid.
asm blocks for inline assembly.
nextcase to fallthrough to the next case.
nextcase <expr> to jump to the case with the expression value. This may be an expression evaluated at runtime.
nextcase default to jump to the default clause.
Labelled while/do/for/foreach to use with break nextcase and continue.
foreach to iterate over arrays, vectors, slices and user-defined containers using operator overloading.
foreach_r to iterate in reverse.
foreach / foreach_r may take the element by value or reference. The index may optionally be provided.
$if, $switch, $for, $foreach statements executing at compile time.
$echo printing a message at compile time.
$assert compile time assert.
defer statement to execute statements at scope exit.
defer catch and defer try, which are similar to defer but execute only if the Optional value contains a fault or a normal result respectively.
do statements may omit while, behaving same as while (0).
if may have a label. Labelled if may be exited using labelled break.
if (try ...) statements run code when an expression is a “valid”/“normal” result (i.e. to handle the “happy path” when working with Optionals).
if (catch ...) statements run code when an expression is an “invalid”/“abnormal” (fault-containing) result (i.e. to handle the “failure path” when working with Optionals). It can be used to implicitly unwrap variables.
Exhaustive switching on enums.

Changed

Switch cases will have implicit break, rather than implicit fallthrough.
assert is an actual statement and may take a string or a format + arguments.
static_assert from C and C++ corresponds to $assert in C3 and is a statement.

Removed

goto has been removed and replaced by labelled break, continue and nextcase.

Compile time evaluation

Added

@if(cond) to conditionally include a struct/union field, a user-defined type, etc.
Compile time variables with $ prefix, e.g. $foo.
$if...$else...$endif and $switch...$endswitch inside of functions to conditionally include code.
$for and $foreach to loop over compile time variables and data.
$typeof determines an expression type without evaluating it.
Type properties may be accessed at compile time.
$defined returns true if the expression (variable, function, type, etc) passed to it would compile. The expression passed to $defined is not actually executed though and thus does not have side effects.
$error emits an error if encountered.
$embed includes a file as binary data.
$include includes a file as text.
$exec includes the output of a program as code.
$evaltype takes a compile time string and turns it into a type.
$eval takes a string and turns it into an identifier.
$extnameof turns an identifier into its string external name.
$nameof turns an identifier into its local string name.
$qnameof turns an identifier into its local string name with the module prefixed.
Compile time constant values are always compile time folded for arithmetic operations and casts.
$$FUNCTION returns the current function as an identifier, as if its name had been written in place of $$FUNCTION.

Changed

#define for constants is replaced by untyped constants, e.g. #define SOME_CONSTANT 1 becomes const SOME_CONSTANT = 1;.
#define for variable and function aliases is replaced by alias, e.g. #define native_foo win32_foo becomes alias native_foo = win32_foo;
In-function #if...#else..#endif is replaced by $if and #if...#elif...#endif is replaced by $switch.
For converting code into a string use $stringify.
Macros for date, line etc are replaced by $$DATE, $$FILE, $$FILEPATH, $$FUNC, $$LINE, $$MODULE, $$TIME.

Removed

Top level #if...#endif does not have a counterpart. Use @if instead.
No #include directives, $include will include text, but normally C3 code will use import to access code from other modules.

Macros

Added

macro for defining macros.
“Function-like” macros have no prefix and have only regular parameters or type parameters.
“At”-macros are prefixed with @ and may also have compile time values, expression parameters, and a trailing body.
Type parameters are prefixed with $ and conform to C3’s required type naming convention (e.g. $TypeFoo, a.k.a. “PascalCase”).
Expression parameters (i.e. macro parameters prefixed with #) are unevaluated expressions. This is similar to arguments to #define in C.
Compile time values have a $ prefix and must contain compile time constant values.
Any macro that evaluates to a constant result can be used as if it was the resulting constant.
Macros may be recursively evaluated.
Macros are inlined at the location where they are invoked.
Unless resulting in a single constant, macros implicitly create a runtime scope.

Removed

No #define macros.
Macros cannot be incomplete statements.

Features provided by builtins

Some features are provided by “builtins” in the standard library, and appear like normal functions and macros in the standard library, but nonetheless provided unique functionality:

@likely(...) / @unlikely(...) on branches affects compilation optimization.
@anycast(...) casts an any with an optional result.
unreachable(...) marks a path as unreachable with a panic in safe mode.
unsupported(...) similar to unreachable but for functionality not implemented.
@expect(...) expect a certain value with an optional probability for the optimizer.
@prefetch(...) prefetches a pointer, meaning that the memory at the pointed to address will be loaded before it is necessarily required, thus possibly improving performance under the right conditions.
swizzle(...) swizzles a vector.
@volatile_load(...) and @volatile_store(...) volatile load/store.
@atomic_load(...) and @atomic_store(...) atomic load/store.
compare_exchange(...) atomic compare exchange.
Saturating add, sub, mul, shl on integers.
Vector reduce operations: add, mul, and, or, xor, max, min.

Modules

Modules are defined using module <name>;, where <name> is of the form foo::bar::baz.
Modules can be split into an unlimited number of module sections, each starting with the same module name declaration if intended to become part of the same module. Multiple differently named modules can also be defined per file.
The import statement imports a given module.
Each module section has its own set of import statements.
Importing a module gives access to the declarations that are @public.
Declarations are default @public, but a module section may set a different default (e.g. module my_module @private;).
@private means the declaration is only visible in the current module.
@local means the declaration is only visible in the current module section. This also implies that the declaration will not be visible outside the current file either.
Imports are recursive. For example, import my_lib will implicitly also import my_lib::net.
Multiple imports may be specified with the same import, e.g. import std::net, std::io;.
Generic modules are not type checked until any of their types, functions or globals are instantiated.
Generic modules are not type checked until any of its types, functions or globals are instantiated.

Contracts

Doc contracts (starting with <* and ending with *>) are parsed for correct contract syntax and semantics. They are not inert comments, despite also serving as documentation comments.
The first part, up until the first @ directive on a new line, is ignored.
The @param directive for pointer arguments may define usage constraints [in] [out] and [inout].
Pointer argument constraints may add a & prefix to indicate that they may not be null, e.g. [&inout].
Contracts may be attached to generic modules, functions and macros.
@require directives are evaluated given the arguments provided. Failing them may be a compile time or runtime error.
The @ensure directive is evaluated at exit – if the return is a “valid”/“normal” (non-fault) result and not an “invalid”/“abnormal” (fault-containing) Optional.
return can be used as a variable identifier inside of @ensure, and holds the return value.
@return? optionally lists the errors used. This will be checked at compile time.
@pure says that no writing to globals is allowed inside and only @pure functions may be called.

Benchmarking

Benchmarks are indicated by @benchmark.
Marking a module section @benchmark makes all functions inside of it implicitly benchmarks.
Benchmarks are usually not compiled.
Benchmarks are instead only run by the compiler on request.

Testing

Tests are indicated by @test.
Marking a module section @test makes all functions inside of it implicitly tests.
Tests are usually not compiled.
Tests are instead only run by the compiler on request.

Safe / fast

Compilation has two modes: “safe” and “fast”. Safe mode will insert checks for out-of-bounds access, null-pointer deref, shifting by negative numbers, division by zero, violation of contracts and asserts.

Fast mode will assume that all of those checks always pass. This means that unexpected behaviour may result from violating those checks. It is recommended to develop in “safe” mode.

If debug symbols are available, C3 will produce a stack trace in safe mode where an error occurs.