Language Reference (Java → SuperJ)

This is a reference for writers of SuperJ programs, not a tutorial. It assumes you already know Java and covers the deltas: what carries over unchanged, what's removed, what's changed, and what's new. For the ramp-up walkthrough see Getting Started; for the build tool see The Build System.

SuperJ reads like Java and behaves like C. It is not a subset of Java — it keeps the productive parts, drops the parts that fight predictable native performance, and adds systems-level capability Java has no answer for.

1. What's identical to Java

If you can write Java, most of what you write in SuperJ is the same:

• Lexical syntax: // and /* */ comments, identifiers, the operator and punctuator set, semicolons, braces.
• Control flow: if/else, for, enhanced for (for-each), while, do/while, switch, break, continue, return, throw, try/catch/finally.
• Classes & interfaces: class/interface, single extends, multiple implements, abstract, final, access modifiers (public/private/protected/package-private), static members, constructors with this()/super() chaining, this/super, import/import static, packages.
• Generics: class-level and method-level type parameters, bounded (<T extends Foo>), wildcard ? extends / ? super / ?, diamond <> in new. Erased, just like Java — no reified type tokens.
• Enums: with per-constant bodies, values(), name(), ordinal().
• Exceptions: try/catch/finally, multi-catch (catch (A | B e)), try-with-resources, throw. (But all unchecked — see §3.)
• Method references :: targeting a single-abstract-method (SAM) interface.
• Varargs (T...).
• @Override annotation.
• Operators: arithmetic, relational, logical, bitwise, shift, assignment, compound assignment, ?:, string + concatenation (lowered to StringBuilder).
• Default values: fields default to 0/0.0/false/null like Java; locals have no default (see definite assignment, §3).
• Casts and instanceof, including instanceof pattern matching with flow scoping (see §3).

2. What's removed from Java

Each removal buys predictability or removes a class of bug. The replacement, where one exists, is listed.

3. What's changed from Java

These features still exist but their semantics differ. This is where you trip if you're used to Java.

new is arena-scoped (no GC)

There is no tracing garbage collector. new allocates from an arena:

• By default, the global arena — lives for the whole program, safe to return from a method or store in a field.
• Inside an arena block, new allocates from that scoped arena, which is dropped (all memory freed in one O(1) operation) when the block exits.

Scoping is lexical, not dynamic: a new belongs to the arena it's written inside. A method you call from inside an arena block still uses the global arena unless it opens its own block.

Node createNode(int v) {
    return new Node(v);          // global arena — safe to return
}

void process() {
    arena temp {
        Buffer buf = new Buffer(1024);  // in temp
        Node n = createNode(5);         // in global (createNode has no arena block)
        // outer = buf;   // compile error: buf would escape its arena
    }                    // temp dropped: buf freed, n still valid
}

A reference that would outlive its arena is a compile error, not a use-after-free. There is no destroy()/finalize() — arena drop is the reclamation mechanism. See Memory Safety.

local — stack allocation (developer privilege)

local declares a stack-allocated object or array (lowered to alloca):

local Point p = new Point(1, 2);   // on the stack, freed on function return

Constraints: not with primitives (local int x is an error), must have an initializer. The compiler does NOT escape-check local — a local ref that escapes its scope is undefined behavior, like a C stack pointer. Use arena blocks for the checked, safe form.

string / String is UTF-8, byte-indexed

One type (string is a keyword alias for String). Deliberately different from Java:

An embedded NUL is an ordinary byte — "ab\0cd".length() == 5, and all String methods honor the stored length, not the first NUL. The one place NUL bites: the raw C-string view handed to printf("%s")/native code stops at the first NUL. True binary belongs in a byte[], not a String.

Arrays carry a runtime elem_size and are not Object

Layout: { i32 length, i32 elem_size, i8 data[] } — an 8-byte header then elements. Consequences:

• Arrays have no vtable, no type_id — they're not Object, not assignable to Object, not valid instanceof/cast targets.
• System.arraycopy is the structural copy intrinsic; it reads this header.
• Every access is bounds-checked at runtime (ArrayIndexOutOfBoundsException). The --no-bounds-check build flag disables it for hot numeric loops.

Generics are erased, and primitives aren't allowed as type args

T erases to Object; T extends Foo erases to Foo. Bridge methods are generated where erased signatures differ. There is no autoboxing, so List<int> is a compile error — use a primitive-specialized collection (IntArrayList, Int2IntMap, …) or int[].

Exceptions are all unchecked

try/catch/finally/throw/multi-catch/try-with-resources all work as in Java. throws on a declaration is accepted but not enforced — it's documentation. Every exception is unchecked; the compiler never makes you catch or declare one.

instanceof pattern matching with flow scoping

if (obj instanceof String s) {
    // s is in scope and typed String here, and only here
    return s.length();
}
// s is NOT in scope here

Flow scoping: the binding is in scope in the if then-branch, the while loop body, and after a guarding if (!(obj instanceof T t)) return;. The binding is final — reassigning it is a compile error. Arrays are excluded as instanceof/cast targets (no vtable).

Definite assignment is enforced

A local read before it's assigned is a compile error, same as Java — but SuperJ enforces it strictly. No accidental garbage reads.

4. What's new in SuperJ (not in Java)

arena blocks — scoped memory

arena temp {
    // new allocates from temp
}   // temp dropped here — O(1), no scan, no pause

Lexical, not dynamic. The compile-time escape check makes a dangling reference a compile error. See §3 above and Memory Safety.

local — stack-scoped allocation

See §3. Developer-privilege, UB-on-escape — use arena for the checked form.

Wide integers: i128, i256, i512

First-class signed primitives, usable everywhere int/long are:

i128 mask  = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFL;
i256 big   = mask * mask;
i512 huge  = ...;
long  to   = (long) mask;        // narrowing cast

• All signed; no unsigned variant.
• Literals: decimal/hex/octal/binary, suffix L/i128/i256/i512, _ digit separators.
• i512 cannot appear in a native method signature (no C ABI descriptor) and is not a struct field type; i128/i256 can.
• Math.*Exact gives checked arithmetic for the narrow widths; wide-int arithmetic wraps on overflow (two's complement).

struct — fixed-layout wire types

A struct is a reference type with a known byte layout — no vtable, no inheritance, no interfaces. Designed for wire formats and zero-copy protocol code. Full spec: doc/struct.md (shipped with the SDK sources).

struct Header {
    int    magic;
    long   timestamp;
    byte[16] uuid;          // fixed-length array field
    string payload;         // var-length: UTF-8 text in the trailing data area
}

• Packed, little-endian, declaration order = byte order (no padding).
• Two construction modes: new Header() (arena allocation, zero-init) and the flyweight Header.view(buf, off) — binds a reference to existing bytes, no copy, no allocation. bindTo(buf, off) re-points it.
• Var-length bytes/string fields: an 8-byte slot in the fixed area (4-byte offset + 4-byte length) points into a trailing data area. Writes are strict declaration order, at most once each; reset() starts a fresh build.
• sizeof is Header.SIZE (a static final int).
• No class references as fields — a pointer in wire bytes is meaningless across processes. string/bytes mean the var-length text/blob, not a pointer.

Rectangular arrays: int[,], int[,,]

Contiguous, stride-indexed, a distinct type from jagged int[][]:

int[,] m = new int[3, 4];     // single allocation, row-major
m[1, 2] = 7;
int total = m.length;         // 12 (product of dimensions)

• Number of commas + 1 = rank (int[,] rank 2, int[,,] rank 3).
• Every dimension sized at creation — no jagged/empty dims.
• .length is the total element count; per-dimension sizes are not exposed.
• Not assignable to int[][], int[], or Object.

First-class SIMD vectors

Accessed via the builtin Simd class — no new syntax, no new keywords. Small fixed-size arrays are the container; Simd methods operate on them as vector registers:

float[4] a = ..., b = ..., c = new float[4];
Simd.addFloat4(a, 0, b, 0, c, 0);   // c = a + b, 4 lanes at once

Vector families (element type + lane count, encoded in the method-name suffix):

i128 and boolean are not SIMD element types. Naming: Simd.operation<Family>(src, srcOff, …, dst, dstOff). Operations: arithmetic, bitwise, compare (produce mask lanes 0/-1), blend, convert (widen/narrow), reduce (sum/min/max/any/all), math (sqrt/floor/fma), gather/scatter, dot, prefix-sum, load/store (aligned + unaligned). Full list: SIMD.md (shipped with the SDK sources). --simd=sse2|avx2|none selects the target ISA (sse2 default; avx2 enables the 256-bit families).

native methods — straight to the C ABI

public class Crypto {
    public native static long hash(byte[] data, int len);
}

• Declaration ends with ; (no body); the compiler emits an external declare, the linker resolves the symbol.
• Symbol mangling: sj_<package>_<Class>_<method>__<argDescriptor> (JNI-style; i128→Q, i256→O; i512 not allowed). Instance natives receive this as an implicit first C param.
• String marshals as const char* (NUL-terminated UTF-8) in and char* out; other references are void*. Primitives map to the obvious C types.
• Natives allocate through the global arena (sj_galloc) — using malloc and returning that is UB.
• Raise SuperJ exceptions via sj_throw* helpers (they don't return).

The systems SDK (at a glance)

Batteries included; every package is under sj.*:

Discover the API with superj doc --list and superj doc <class-fqn>.

5. Quick syntax table

Scan for the construct you need. "Java form" is what you'd write in Java; "SuperJ form" is what you write here.

6. Reserved keywords

abstract   boolean    break      byte       case       catch      char
class      const      continue   default    do         double     else
enum       extends    final      finally    float      for        goto
if         implements import     i128       i256       i512       int
interface  instanceof local      long       native     new        null
package    private    protected  public     return     short      static
string     struct     super      switch     synchronized this     throw
throws     try        transient  void       volatile   while      assert
strictfp

New vs Java: arena (scoped memory), local (stack allocation), i128/i256/i512 (wide ints), string (alias for String), struct (wire-format type).

Reserved-but-unused (inherited from Java's keyword set, not implemented): const, goto, assert, strictfp, transient, synchronized, volatile. They're reserved so you can't use them as identifiers; the features they name in Java are removed (§2) or not implemented.