语言参考（Java → SuperJ）

这是一份面向 SuperJ 程序编写者的参考，不是教程。它假设你已经会 Java，只覆盖差异点：哪些原样保留、哪些移除、哪些改变、哪些新增。入门 walkthrough 见 快速开始；构建工具见 构建系统。

SuperJ 读起来像 Java，跑起来像 C。它不是 Java 的子集 — 它保留高效的部分，丢掉妨碍可预测原生性能的部分，并加入 Java 无从应对的系统级能力。

1. 与 Java 相同的部分

如果你会写 Java，你在 SuperJ 中写的大部分东西都一样：

• 词法语法：// 与 /* */ 注释、标识符、运算符与标点集合、分号、花括号。
• 控制流：if/else、for、增强 for（for-each）、while、do/while、switch、break、continue、return、throw、try/catch/finally、带标签语句与带标签 break L/continue L（Java 语义 — 标签可前缀任意语句；break L 退出任意外层带标签语句，continue L 继续一个外层带标签循环）。
• 类与接口：class/interface、单 extends、多 implements、abstract、final、访问修饰符（public/private/protected/包私有）、static 成员、带 this()/super() 链的构造器、this/super、import/import static、包。
• 泛型：类级与方法级类型参数、有界（<T extends Foo>）、通配符 ? extends / ? super / ?、new 中的菱形 <>。擦除式，和 Java 一样 — 没有具化的类型令牌。
• 枚举：每个常量可有主体、values()、name()、ordinal()。
• 异常：try/catch/finally、multi-catch（catch (A | B e)）、try-with-resources、throw。（但全部为非受检 — 见 §3。）
• 方法引用 :: 指向单抽象方法（SAM）接口。
• 可变参数（T...）。
• @Override 注解。
• 运算符：算术、关系、逻辑、位、移位、赋值、复合赋值、?:、字符串 + 拼接（下放为 StringBuilder）。
• 默认值：字段默认为 0/0.0/false/null，与 Java 一致；局部变量无默认值（见明确赋值，§3）。
• 转型与 instanceof，包括带流作用域的 instanceof 模式匹配（见 §3）。

2. 从 Java 中移除的部分

每一次移除都换来可预测性或消除一类 bug。存在的替代方案列在下方。

3. 与 Java 不同的部分

这些特性仍然存在，但语义不同。习惯了 Java 的话，这里是你会绊倒的地方。

new 是 arena 作用域的（无 GC）

没有追踪式垃圾回收器。new 从一个 arena 分配：

• 默认，使用全局 arena — 存活整个程序周期，可安全地从方法返回或存入字段。
• 在 arena 块内，new 从该作用域 arena 分配，块退出时整体释放（所有内存在一次 O(1) 操作中回收）。

作用域是词法的，不是动态的：一个 new 归属于它被写在其内的那个 arena。你从 arena 块内调用的方法仍然使用全局 arena，除非它自己开了一个块。

Node createNode(int v) {
    return new Node(v);          // 全局 arena — 可安全返回
}

void process() {
    arena temp {
        Buffer buf = new Buffer(1024);  // 在 temp 中
        Node n = createNode(5);         // 在全局中（createNode 没有 arena 块）
        outer = buf;   // OK：逃逸分析把 buf 放置到比 temp 存活更久的地方
    }                    // temp 释放：buf 仍有效，n 仍有效
}

一个超越其 arena 寿命的值会被放置到一个确实比它存活更久的区域 — 若留在帧中则上栈，若离开则上长寿 arena。不被拒绝，不是 use-after-free。逃逸分析在每次构建上运行（--no-escape-analysis 标志关闭的是栈分配优化，而非放置的正确性）。没有 destroy()/finalize() — arena 释放就是回收机制。参见 内存安全。

释放发生在离开块的每一条路径上 — 从结尾掉落、从块内 return、离开块的 break/continue（带标签或不带）。抛出异常是唯一的缺口：它越过帧展开而不释放 arena。

String 不是 arena 内存。 只有 new — 对象、数组、struct — 路由到活动 arena。一个 String 的 body（每个 +、substring、valueOf、StringBuilder.toString()）单独分配且永不回收，无论在 arena 块内还是块外。一个 arena 块不约束构建字符串的代码的开销；在热路径上复用一个 StringBuilder 或在 byte[] 中操作。

local — 栈分配（开发者特权）

local 声明一个栈分配的对象或数组（下放为 alloca）：

local Point p = new Point(1, 2);   // 在栈上，函数返回时释放

约束：不能用于原始类型（local int x 是错误），必须有初始化器。编译器不对 local 做逃逸检查 — 一个逃逸出其作用域的 local 引用是未定义行为，就像 C 的栈指针。需要经过检查的安全形式时用 arena 块。

string / String 是 UTF-8，按字节索引

单一类型（string 是 String 的关键字别名）。刻意与 Java 不同：

内嵌的 NUL 是一个普通字节 — "ab\0cd".length() == 5，所有 String 方法都遵循存储的长度，而非第一个 NUL。NUL 唯一咬人的地方：交给 printf("%s")/原生代码的原始 C 字符串视图会在第一个 NUL 处停止。真正的二进制数据应放在 byte[]，而不是 String。

数组携带运行时 elem_size，且不是 Object

数组没有对象头 — 一个小的 length/elem_size 前缀然后是元素。后果：

• 数组不是 Object，不能赋值给 Object，也不能作为 instanceof/转型的目标。
• System.arraycopy 是结构化拷贝内联函数。
• 每次访问在运行时都做越界检查（ArrayIndexOutOfBoundsException）。--no-bounds-check 构建标志可为热数值循环禁用它。

泛型是擦除式的，原始类型不能作为类型参数

T 擦除为 Object；T extends Foo 擦除为 Foo。在擦除签名不同处生成桥接方法。没有自动装箱，所以 List<int> 是编译错误 — 使用原始类型特化集合（IntArrayList、Int2IntMap、…）或 int[]。

异常全部为非受检

try/catch/finally/throw/multi-catch/try-with-resources 都和 Java 一样工作。声明上的 throws 被接受但不强制 — 它只是文档。每个异常都是非受检的；编译器从不要求你捕获或声明一个。

instanceof 模式匹配与流作用域

if (obj instanceof String s) {
    // s 在此作用域内且类型为 String，仅在此处
    return s.length();
}
// s 在此处不在作用域内

流作用域：绑定在 if 的 then 分支、while 循环体中，以及在守卫 if (!(obj instanceof T t)) return; 之后有效。绑定是 final — 重新赋值是编译错误。数组被排除作为 instanceof/转型目标（无对象头）。

明确赋值被强制

局部变量在赋值前读取是编译错误，与 Java 相同 — 但 SuperJ 严格执行。不会意外读到垃圾值。

4. SuperJ 中新增的（Java 没有）

arena 块 — 作用域内存

arena temp {
    // new 从 temp 分配
}   // temp 在这里释放 — O(1)，无扫描，无停顿

词法的，不是动态的。编译期逃逸检查让悬空引用成为编译错误。见上文 §3 与 内存安全。

local — 栈作用域分配

见 §3。开发者特权，逃逸即 UB — 需要检查形式时用 arena。

宽整数：i128、i256、i512

一等公民有符号原语，可在 int/long 能用的任何地方使用：

i128 mask  = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFL;
i256 big   = mask * mask;
i512 huge  = ...;
long  to   = (long) mask;        // 收窄转型

• 全部有符号；无无符号变体。
• 字面量：十进制/十六进制/八进制/二进制，后缀 L/i128/i256/i512，_ 数字分隔符。
• i512 不能出现在 native 方法签名中（无 C ABI 描述符）。三种宽整数（i128/i256/i512）都是合法的 struct 字段类型。
• Math.*Exact 为较窄宽度提供检查算术；宽整数算术在溢出时回绕（二进制补码）。

复数：cdouble、cfloat

一等公民复数原语 — 两个浮点值（实部 + 虚部）打包为一个原语类型：

• cdouble（128 位）：两个 double — 默认复数类型。
• cfloat（64 位）：两个 float — 用于带宽敏感场景（数组、SIMD）。

cdouble z  = ComplexMath.fromPair(3.0, 4.0);   // 3 + 4i
cdouble j  = 0.0 + 1.0i;                        // 虚数字面量 → 1i
cdouble w  = z * z;                              // (3+4i)² = -7+24i
double  r  = ComplexMath.real(z);               // 3.0
double  im = ComplexMath.imag(z);               // 4.0
double  a  = ComplexMath.abs(z);                 // 5.0
cdouble e  = ComplexMath.exp(j);                // e^i = cos(1)+i·sin(1)

字面量语法： i 后缀表示虚数单位 — 3.0i 是一个实部=0、虚部=3.0 的 cdouble；2.5fi 是一个实部=0、虚部=2.5 的 cfloat。组合实部与虚部字面量可构造一个复数值：ComplexMath.fromPair(3.0, 4.0) 产生 3 + 4i。

算术语义：

• +、-、*、/ 与一元 - 作用于复数值 — * 是复数乘法（非逐元素）：(a+bi)(c+di) = (ac-bd) + (ad+bc)i。
• == 与 != 比较两个分量；</<=/>/>=/% 是编译错误（复数无序）。
• double → cdouble 加宽设虚部=0；cdouble → double 收窄丢弃虚部。float ↔ cfloat 同理。
• cfloat → cdouble 加宽每个分量；cdouble → cfloat 收窄每个分量（需显式转型）。

数组： cdouble[] 与 cfloat[] 是普通数组 — 每个元素是一个连续的实部+虚部对。热数值循环可用 --no-bounds-check。

ComplexMath SDK 类（sj.lang.ComplexMath）：静态方法对应 java.lang.Math，基于 C99 <complex.h>：

浮点确定性注意： 复数 * 与 / 涉及多次浮点运算（可能应用融合乘加），因此结果是架构相关的 — 不要跨架构断言逐位相同的复数浮点输出。这与实数浮点注意事项一致：跨平台比较复数结果时使用容差。

struct — 固定布局线上类型

一个 struct 是一个具有已知、紧凑字节布局的值类型 — 无对象头、无同一性、无继承、无接口。为线上格式与零拷贝协议代码设计。深入讲解见 struct 指南。

struct Header {
    int    magic;
    long   timestamp;
    byte[16] uuid;          // 定长数组字段
    string payload;         // 变长：尾部数据区中的 UTF-8 文本
}

• 紧凑、小端、声明顺序 = 字节顺序（无填充）。
• 两种构造模式：new Header()（arena 分配，零初始化，预留变长数据空间）与轻量 Header.view(buf, off) — 绑定到已有字节上，无拷贝、无分配（热路径）。bindTo(buf, off) 重新指向。
• 读取字段返回其声明类型 — 这是要弄对的部分：一个 string 字段被赋一个 String 并读回为 String（h.payload = "hi"; String s = h.payload; dst.payload = src.payload;）；一个 bytes 字段读回为 byte[]。（new String(field) 在 string 字段上也可用。）没有对象被序列化 — 文本/字节按值内联存储；String/byte[] 只是访问器的返回值。要把一个变长字段作为原始字节读，把它声明为 bytes。
• 变长 bytes/string 字段：固定区中一个 8 字节槽（4 字节偏移 + 4 字节长度）指向尾部数据区。写入严格按声明顺序，每个字段至多一次；reset() 开始一次新的构建。
• Header.SIZE（一个 static final int）是固定区大小；totalSize() 返回 SIZE 加上已写变长长度之和 — 即要成帧/发布的字节数。
• 字段不能是类引用或动态 T[] 数组 — 线上字节中的指针跨进程无意义。string/bytes 指的是按值存储的变长文本/二进制块，不是指针。

合成的访问器 — 写入与读取 — 在一次轻量往返中：

struct Order {
    long   id;          // 固定原语
    int    qty;
    byte   side;        // 0 = buy, 1 = sell
    string symbol;      // 变长 UTF-8 文本
    bytes  memo;        // 变长原始字节
}

// 写入 — 把一个轻量绑定到缓冲区并填充字段（无逐字段分配）：
byte[] buf = new byte[256];
Order w = Order.view(buf, 0);
w.id = 42;
w.qty = 100;
w.side = 1;
w.symbol = "GOOG";                // string 字段  <- 一个 String
w.memo   = new byte[]{7, 8, 9};   // bytes  字段  <- 一个 byte[]
int n = w.totalSize();            // Order.SIZE + 4 ("GOOG") + 3 (memo)；要发送的字节

// 读取 — 把一个新视图绑定到这些字节；每个字段读回为其声明类型：
Order r = Order.view(buf, 0);
long   id   = r.id;               // 原语  -> 其值  (42)
int    qty  = r.qty;              //               (100)
String sym  = r.symbol;           // string 字段 -> 一个 String  ("GOOG")
byte[] memo = r.memo;             // bytes  字段 -> 一个 byte[]   ({7,8,9})
// String s = new String(r.symbol);   // 也可用：一个独立副本

你按声明类型赋值每个字段，并以同样方式读回 — 一个 string 字段两侧都是 String，一个 bytes 字段两侧都是 byte[]。变长字段（symbol、memo）按声明顺序写入；reset() 回卷以重新填充同一缓冲区。

矩形数组：int[,]、int[,,]

连续、按步长索引，与锯齿 int[][] 是不同的类型：

int[,] m = new int[3, 4];     // 单次分配，行主序
m[1, 2] = 7;
int total = m.length;         // 12（各维度之积）

• 逗号数 + 1 = 秩（int[,] 秩 2，int[,,] 秩 3）。
• 每个维度在创建时确定大小 — 无锯齿/空维度。
• .length 是总元素数；各维度大小不暴露。
• 不能赋值给 int[][]、int[] 或 Object。

一等公民 SIMD 向量

通过内建 Simd 类访问 — 无新语法、无新关键字。小型定长数组是容器；Simd 方法把它们当作向量寄存器操作：

float[4] a = ..., b = ..., c = new float[4];
Simd.addFloat4(a, 0, b, 0, c, 0);   // c = a + b，4 个通道同时

向量族（元素类型 + 通道数，编码在方法名后缀中）：

i128 与 boolean 不是 SIMD 元素类型。命名：Simd.operation<Family>(src, srcOff, …, dst, dstOff)。操作：算术、位、比较（产生掩码通道 0/-1）、blend、转换（加宽/收窄）、归约（sum/min/max/any/all）、数学（sqrt/floor/fma）、gather/scatter、点积、前缀和、加载/存储（对齐 + 非对齐）。完整操作列表见 SIMD 参考（随 SDK 源码发布）。--simd=sse2|avx2|none 选择目标 ISA（sse2 默认；avx2 启用 256 位族）。

native 方法 — 直达 C ABI

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

• 声明以 ; 结尾（无方法体）；编译器发出外部 declare，链接器解析符号。
• 符号修饰：sj_<package>_<Class>_<method>__<argDescriptor>（i128→Q，i256→O，cfloat→M，cdouble→N；i512 不允许）。实例 native 接收 this 作为隐式第一个 C 参数。
• String 入参编组为 const char*（NUL 结尾 UTF-8），出参为 char*；其他引用为 void*。原始类型映射到显而易见的 C 类型。cfloat/cdouble 编组为一个双元素结构体（{float,float} / {double,double}）。
• native 通过 SuperJ 分配器分配 — 使用 malloc 并返回它是 UB。
• 通过运行时异常辅助函数抛出 SuperJ 异常（它们不返回）。

系统 SDK（一览）

开箱即用；每个包都在 sj.* 下：

用 superj doc --list 与 superj doc <class-fqn> 发现 API。

5. 速查语法表

扫一眼找到你需要的构造。"Java 形式"是你在 Java 中会写的；"SuperJ 形式"是你在这里写的。

6. 保留关键字

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

相比 Java 新增：arena（作用域内存）、local（栈分配）、i128/i256/i512（宽整数）、cdouble/cfloat（复数）、string（String 的别名）、struct（线上格式类型）。

保留但未使用（继承自 Java 关键字集合，未实现）：const、goto、assert、strictfp、transient、synchronized、volatile。它们被保留以防止你用作标识符；它们在 Java 中对应的特性已被移除（§2）或未实现。