numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/interpreter/interpreterSpecialBuiltins.d.ts

@@ -12,7 +12,7 @@ export interface InterpreterContext {
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
     callFunction: (name: string, args: unknown[], nargout: number) => unknown;
     rt: Runtime;
-    /** Optimization mode: "0" = no JIT, "1" = JS-JIT, "e3" = C-JIT scalar loops. */
+    /** Optimization mode: "0" = no JIT, "1" = JS-JIT, "2" = C-JIT. */
     optimization: import("../executors/plugins.js").OptLevel;
     /** Resolve a workspace function or class name to its source file,
      *  or undefined if no workspace file provides that name.

package/dist-lib/numbl-core/jit/builtins/defs/_shared.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Helpers shared across multiple builtin files.
+ */
+import type { Span } from "../../parser/index.js";
+import { type Type, type NumericType } from "../../lowering/types.js";
+export declare function requireScalarRealDouble(t: Type, what: string, span?: Span): void;
+/** Like `requireScalarRealDouble` but accepts non-scalar real doubles
+ *  (the elemwise path). Logical also accepted (stored as double in C). */
+export declare function requireRealDouble(t: Type, what: string, span?: Span): void;
+/** Accepts a real or complex numeric (double / logical). Used by the
+ *  unary math builtins and the scalar/tensor arithmetic paths that
+ *  contaminate to complex when either operand is complex. */
+export declare function requireRealOrComplex(t: Type, what: string, span?: Span): void;
+/** Require a scalar numeric (real or complex). */
+export declare function requireScalarRealOrComplex(t: Type, what: string, span?: Span): void;
+export declare function exactDouble(t: Type): number | undefined;
+export declare function exactRealArray(t: Type): Float64Array | undefined;
+/** Read a scalar-complex exact value if present. Returns `{re, im}`
+ *  when the type's `exact` is the scalar-complex carrier, or `undefined`
+ *  otherwise. */
+export declare function exactComplex(t: Type): {
+    re: number;
+    im: number;
+} | undefined;
+/** Read a complex-tensor split-buffer exact carrier if present.
+ *  Returns the `{re, im}` Float64Array pair when the type's `exact` is
+ *  the complex-tensor carrier (parallel to `exactRealArray` but for
+ *  complex tensors); returns `undefined` for any other shape (no exact,
+ *  scalar number, real-array, scalar-complex `{re: number}`). */
+export declare function exactComplexArray(t: Type): {
+    re: Float64Array;
+    im: Float64Array;
+} | undefined;
+/** Convenience: project a scalar exact value (real or complex) into a
+ *  `{re, im}` pair, returning `undefined` if neither carrier matches. */
+export declare function exactScalarAsComplex(t: Type): {
+    re: number;
+    im: number;
+} | undefined;
+/** True when this numeric is statically known to be complex (the static
+ *  flag, not the runtime value). Centralizes the predicate so callers
+ *  don't sprinkle `(t as NumericType).isComplex` checks. */
+export declare function isStaticComplex(t: Type): t is NumericType;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/_elemwise.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared infrastructure for elementwise real binary builtins
+ * (`plus`, `minus`, `times`, `rdivide`).
+ */
+import { type DimInfo, type NumericType, type Sign } from "../../../lowering/types.js";
+import type { Builtin } from "../../registry.js";
+/** Result of broadcast shape resolution for the elementwise binary path.
+ *  `outDims` is the output's per-axis dim info (MATLAB-style implicit
+ *  expansion: align on axis 1, pad with 1s on the right, axis-wise
+ *  `da == db || da == 1 || db == 1`). `bcast` is true when the C runtime
+ *  needs the broadcasting helper rather than the fast `_tt` path —
+ *  either the ndims differ or at least one statically-singleton axis
+ *  needs to be replicated against a non-singleton sibling. */
+type ResolvedShape = {
+    outDims: DimInfo[];
+    /** True when broadcast (any axis where one side is statically 1 but
+     *  the other is not, OR ndims differ). False when the two arg shapes
+     *  match dim-for-dim (modulo unknowns the runtime trusts). */
+    bcast: boolean;
+};
+/** Shape resolution for elementwise binary. Returns `null` for scalar+
+ *  scalar; otherwise computes the broadcast output shape and whether
+ *  broadcasting is required. Throws on statically incompatible axes
+ *  (no span — the framework's `withSpan` wrapper attaches the call-site
+ *  span). Exported for `power.ts`, which shares the same broadcast rules. */
+export declare function elemwiseResultShape(a: NumericType, b: NumericType, name: string): ResolvedShape | null;
+/** True iff an elementwise binary op on tensor operands `a` and `b`
+ *  needs the broadcasting `_bcast_tt` helper rather than the same-shape
+ *  `_tt` fast path. Mirrors the per-axis compatibility logic inside
+ *  `elemwiseResultShape` but returns just the bool — codegen call
+ *  sites don't need to thread the resolved output shape from transfer.
+ *  Exported for `power.ts`, which shares the same codegen discipline. */
+export declare function needsBroadcast(a: NumericType, b: NumericType): boolean;
+/** Compute the broadcast-aware elementwise fold over `a` and `b` for
+ *  the given (fully-exact) output shape, applying `step` per slot.
+ *  Both sides must already carry exact data (a `Float64Array` or a
+ *  scalar `number`); the caller is responsible for the
+ *  `EXACT_ARRAY_MAX_ELEMENTS` cap. Singleton axes on either side get
+ *  stride 0 so they broadcast against non-singleton output axes;
+ *  output is filled in column-major order to match the runtime layout.
+ *  Exported for `power.ts`, which shares the same broadcast rules. */
+export declare function broadcastFoldExact(a: NumericType, b: NumericType, outShape: number[], step: (av: number, bv: number) => number): Float64Array;
+/** Build a real elementwise binary builtin: scalar, scalar+tensor,
+ *  tensor+scalar, tensor+tensor. Folds when every input is exact.
+ *  `helperBase` names the matching set of C runtime helpers
+ *  (mtoc2_tensor_<helperBase>_tt / _ts / _st). Commutative ops set
+ *  `commutative=true` so the scalar-first path reuses `_ts` with
+ *  swapped operands.
+ *
+ *  The four shape combos and what they emit:
+ *
+ *  | a       | b       | C output                                   |
+ *  |---------|---------|--------------------------------------------|
+ *  | scalar  | scalar  | `(argsC[0] cOp argsC[1])`                  |
+ *  | tensor  | scalar  | `mtoc2_tensor_<helperBase>_ts(a, b)`       |
+ *  | scalar  | tensor  | commutative → `_ts(b, a)`; else `_st(a,b)` |
+ *  | tensor  | tensor  | `mtoc2_tensor_<helperBase>_tt(a, b)`       |
+ *
+ *  `complexFold` / `complexScalarExpr` / `complexRuntimeDeps` are
+ *  optional; when set, a scalar+scalar op with at least one complex
+ *  operand routes through them (and `transfer` returns a complex
+ *  result). Phase 1 wires complex scalars; tensor+complex paths are
+ *  rejected until Phase 3 lands the runtime helpers.
+ */
+export declare function defineElemwiseRealBinary(opts: {
+    name: string;
+    cOp: string;
+    helperBase: string;
+    commutative: boolean;
+    fold: (a: number, b: number) => number;
+    signRule: (a: NumericType, b: NumericType) => Sign;
+    /** Scalar-complex fold. Receives two `{re, im}` operands. */
+    complexFold?: (a: {
+        re: number;
+        im: number;
+    }, b: {
+        re: number;
+        im: number;
+    }) => {
+        re: number;
+        im: number;
+    };
+    /** Scalar-complex C expression. Defaults to the same `(a cOp b)`
+     *  infix as the real path — works for `+ - *` because C99 promotes
+     *  real↔complex automatically. Divide overrides to route through
+     *  `mtoc2_cdiv(a, b)`. */
+    complexScalarExpr?: (aC: string, bC: string) => string;
+    /** Extra runtime snippet activations needed by the complex scalar
+     *  path (e.g. `mtoc2_cdiv` for division). The real-only `_real`
+     *  helper still activates unconditionally for the tensor path. */
+    complexRuntimeDeps?: string[];
+}): Builtin;
+/** Same as `defineElemwiseRealBinary`, but the scalar path emits a C
+ *  function call (`fmod(a,b)`, `atan2(a,b)`, …) instead of an infix
+ *  operator. The tensor helpers still follow the `_tt`/`_ts`/`_st`
+ *  naming convention; supply the appropriate `runtimeDep` for the
+ *  snippet that defines them (`mtoc2_tensor_elemwise_real_fn`
+ *  covers `mod`/`rem`/`atan2`/`hypot`). */
+export declare function defineElemwiseRealBinaryFn(opts: {
+    name: string;
+    cFn: string;
+    helperBase: string;
+    commutative: boolean;
+    fold: (a: number, b: number) => number;
+    signRule: (a: NumericType, b: NumericType) => Sign;
+    runtimeDep: string;
+    /** Optional JS scalar form. Defaults to `${cFn}(${a}, ${b})` (works
+     *  when `cFn` happens to be a JS function on the surrounding scope
+     *  — almost never the case). Pass `(a, b) => "Math.atan2(...)"`
+     *  for `atan2`/`hypot`, an explicit JS-modulo expression for
+     *  `mod`/`rem`, etc. */
+    jsScalarExpr?: (aJs: string, bJs: string) => string;
+}): Builtin;
+export declare function signSum(a: NumericType, b: NumericType): Sign;
+export declare function signDiff(a: NumericType, b: NumericType): Sign;
+export declare function signProd(a: NumericType, b: NumericType): Sign;
+/** Sign of `a / b`. Almost the same shape as `signProd`, but the
+ *  divisor's sign tells a different story: `x / 0` is ±Inf (or NaN
+ *  when `x` is also 0), NOT zero, so a zero divisor degrades the
+ *  result to `unknown`. A zero numerator with a non-zero divisor is
+ *  zero. */
+export declare function signQuot(a: NumericType, b: NumericType): Sign;
+export {};

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/minus.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const minus: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/mpower.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `mpower` builtin — backs the `^` binary operator.
+ *
+ * v1 supports only the scalar-on-both-sides case (which delegates to
+ * `power`, the `.^` builtin). Matrix power on a square base would
+ * require eigendecomposition for non-integer exponents and repeated
+ * `mtimes` for integer exponents — a real slope of its own. Numbl's
+ * `mPow` (helpers/arithmetic.ts:1006) is the reference; we punt on it
+ * entirely for now.
+ */
+import { type Builtin } from "../../registry.js";
+export declare const mpower: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/mrdivide.d.ts

@@ -0,0 +1,5 @@
+import { type Builtin } from "../../registry.js";
+/** `mrdivide` (matrix /): mirrors `rdivide` when at least one arg is
+ *  scalar; rejects the both-tensor case until matrix right-division
+ *  is implemented. */
+export declare const mrdivide: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/mtimes.d.ts

@@ -0,0 +1,2 @@
+import { type Builtin } from "../../registry.js";
+export declare const mtimes: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/plus.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const plus: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/power.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `power` builtin — backs the `.^` (elementwise power) binary
+ * operator.
+ *
+ * Mirrors `mElemPow` in `../numbl/src/numbl-core/helpers/arithmetic.ts`
+ * (line 1075) modulo the complex-result paths. Numbl produces a
+ * complex result for `(neg)^(non-integer)`; mtoc2 has no complex
+ * type and rejects that combination at lowering time (same precedent
+ * as `sqrt` / `log` rejecting out-of-domain real inputs).
+ *
+ * Shape rules follow the rest of the elementwise binary family:
+ *   - scalar OP scalar → scalar; tensor OP scalar / scalar OP tensor /
+ *     same-shape tensor OP tensor.
+ *   - exact-fold within EXACT_ARRAY_MAX_ELEMENTS when every input
+ *     element is exact AND every output element is finite.
+ *
+ * Sign refinement:
+ *   - exponent exact zero → `positive` (x^0 == 1 for every x, even 0
+ *     and Inf per IEEE-754 / MATLAB).
+ *   - base statically `positive` → `positive`.
+ *   - base statically `nonneg` AND exponent statically `nonneg` → `nonneg`.
+ *   - otherwise → `unknown`.
+ *
+ * Domain rejection: when the base could be negative (i.e. its sign
+ * isn't statically nonneg) AND the exponent isn't an exact integer
+ * (or any exact value at all), reject with a clear span — that's the
+ * "complex-result" case numbl handles but mtoc2 v1 doesn't.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const power: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/rdivide.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const rdivide: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/times.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const times: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/arithmetic/uminus.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const uminus: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/_compare.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared infrastructure for scalar comparison builtins
+ * (`eq`, `ne`, `lt`, `le`, `gt`, `ge`).
+ *
+ * Complex scalar handling (MATLAB rule):
+ *   - `eq` / `ne` compare both real and imaginary parts.
+ *   - `<` / `<=` / `>` / `>=` compare on the real part only; the
+ *     imaginary part is dropped. (numbl matches.)
+ */
+import type { Builtin } from "../../registry.js";
+export type CompareKind = "eq" | "ne" | "rel";
+export declare function defineCompare(name: string, cOp: string, fold: (a: number, b: number) => boolean, kind?: CompareKind): Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/eq.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const eq: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/ge.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const ge: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/gt.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const gt: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/le.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const le: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/lt.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const lt: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/compare/ne.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const ne: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/diag/assert.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `assert(cond)` / `assert(cond, msg)` / `assert(cond, fmt, args...)` —
+ * runtime + compile-time assertion.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const assert: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/io/_format_args.d.ts

@@ -0,0 +1,17 @@
+import { type Type } from "../../../lowering/types.js";
+/** Validate that args at positions [from..) are legal `mtoc2_fprintf_arg_t`
+ *  slots — scalar real numeric, text, or real multi-element tensor.
+ *  Throws TypeError / UnsupportedConstruct (no span — framework attaches
+ *  via `withSpan`). Shared by `fprintf`, `error`, future `sprintf`. */
+export declare function validateFormatArgs(builtinName: string, argTypes: ReadonlyArray<Type>, from: number): void;
+/** Emit one `mtoc2_fprintf_arg_t` slot for `argsC[i]` typed `argTypes[i]`.
+ *  Used to build the compound-literal slot array for fprintf / error /
+ *  sprintf call sites. ANF in the lowerer guarantees multi-element
+ *  tensor args are bare Var lvalues (so `&c` is well-defined). */
+export declare function emitFormatSlot(builtinName: string, c: string, t: Type, argIndex: number): string;
+/** Build the `(const mtoc2_fprintf_arg_t[]){ ... }` compound literal
+ *  from a slice of slots (or the `{ {0} }` empty form C99 needs to
+ *  avoid the zero-length-array GNU extension). */
+export declare function emitFormatSlotArray(slots: ReadonlyArray<string>): string;
+/** Adapter expression for a text-typed format arg → `mtoc2_text_view_t`. */
+export declare function emitTextView(c: string, t: Type): string;

package/dist-lib/numbl-core/jit/builtins/defs/io/disp.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const disp: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/io/error.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const errorBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/io/fprintf.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const fprintf: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/io/sprintf.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const sprintfBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/io/warning.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `warning(fmt, args...)` and `warning('id:topic', fmt, args...)` —
+ * print `Warning: <message>\n` to stdout. Matches numbl
+ * (`numbl-core/runtime/specialBuiltins.ts:190`).
+ *
+ * Unlike `error`, `warning` doesn't throw and has no `try/catch`
+ * interaction; the identifier-bearing form is accepted for
+ * source-level compatibility but the id is dropped (numbl wires it
+ * into a `lastwarn` state mtoc2 doesn't expose).
+ *
+ * The state-query form `warning('on'/'off', id)` and the no-arg
+ * call `warning()` are deferred — chunkie doesn't use them.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const warningBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/_shortcircuit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared scaffold for the two short-circuit logical builtins
+ * (`||` → `oror`, `&&` → `andand`).
+ *
+ * **Scope decision: scalar operands only.**
+ *
+ * MATLAB requires scalar operands for `||` and `&&`; numbl is more
+ * permissive (routes both operands through `toBool` to accept
+ * tensors — see `interpreter/interpreterExec.ts` lines 650–661,
+ * `runtime/convert.ts:44`). mtoc2 v1 takes the MATLAB-strict path so
+ * the result type stays a scalar logical and the codegen stays
+ * trivial (`(a) || (b)` / `(a) && (b)` in C, which short-circuits
+ * natively).
+ *
+ * Compile-time fold:
+ *   - both operands exact → fold to scalar logical with concrete value.
+ *   - LHS exact + truthy (for `||`) or falsy (for `&&`) → result is
+ *     the LHS's logical value regardless of RHS. This honors
+ *     short-circuit semantics at the type level so a runtime-only RHS
+ *     doesn't pollute the result type. (mtoc2 always evaluates the
+ *     RHS at the type-system layer, but the fold value still skips
+ *     it.)
+ *   - otherwise → scalar logical, no exact.
+ *
+ * **The runtime side already short-circuits** via C's `||` / `&&`
+ * operators, independent of the fold rule.
+ */
+import type { Builtin } from "../../registry.js";
+export type ShortCircuitKind = "or" | "and";
+export declare function defineShortCircuit(name: string, surface: string, kind: ShortCircuitKind): Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/_unary_pred.d.ts

@@ -0,0 +1,30 @@
+import type { Builtin } from "../../registry.js";
+interface ComplexPredSpec {
+    /** C scalar expression: given `(re, im)` text, return the per-element
+     *  boolean expression. The factory wraps it in a ternary that maps
+     *  to `1.0` / `0.0`. */
+    cScalarComplex: (re: string, im: string) => string;
+    /** JS scalar expression: same shape as `cScalarComplex` but for
+     *  the js-aot path; operates on real-and-imag JS expressions. */
+    jsScalarComplex: (re: string, im: string) => string;
+    /** JS fold / interpreter rule on a `{re, im}` value. */
+    jsFnComplex: (re: number, im: number) => boolean;
+    /** Runtime tensor helper name (in `tensor_predicate_complex.h`). */
+    tensorHelperComplex: string;
+}
+export interface UnaryPredOpts {
+    name: string;
+    /** C scalar expression given the arg's C text. */
+    cScalar: (arg: string) => string;
+    /** JS scalar expression given the arg's JS text. */
+    jsScalar: (arg: string) => string;
+    /** JS fold / interpreter rule. */
+    jsFn: (x: number) => boolean;
+    /** Runtime tensor helper name (in `tensor_predicate.h`). */
+    tensorHelper: string;
+    /** Optional complex-input support. Predicates that MATLAB accepts
+     *  on complex (`isnan`, `isinf`, `isfinite`, …) declare this. */
+    complex?: ComplexPredSpec;
+}
+export declare function defineUnaryPred(opts: UnaryPredOpts): Builtin;
+export {};

package/dist-lib/numbl-core/jit/builtins/defs/logical/and.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `and(a, b)` — the function form of `&`. See `or.ts` for why this
+ * routes through the short-circuit scaffold.
+ */
+export declare const andBuiltin: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/andand.d.ts

@@ -0,0 +1 @@
+export declare const andand: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/boolconst.d.ts

@@ -0,0 +1,3 @@
+import type { Builtin } from "../../registry.js";
+export declare const trueBuiltin: Builtin;
+export declare const falseBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/classBuiltin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `class(x)` — return the static type name as a char (single-quoted)
+ * value.
+ *
+ * Always static in mtoc2: the type lattice knows every value's kind
+ * (numeric/double, numeric/logical, char, string, struct, class
+ * instance, cell, function-handle). The transfer attaches the
+ * resolved name to the `CharType`'s `exact` slot so subsequent
+ * `strcmp` / `if class(x) == 'double'` patterns see a folded value.
+ *
+ * Matches numbl `introspection.ts`:
+ *   - number / complex-number / sparse / real-numeric tensor → "double"
+ *   - boolean / logical-flagged tensor → "logical"
+ *   - char → "char", string → "string"
+ *   - struct / struct-array → "struct"
+ *   - cell → "cell"
+ *   - class instance → its `className`
+ *   - function handle → "function_handle"
+ */
+import type { Builtin } from "../../registry.js";
+export declare const classBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/fieldnames.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `fieldnames(s)` — returns an N×1 cell of char-array field names
+ * for a struct or class instance. Matches numbl's
+ * `introspection.ts:fieldnamesApply` semantics, with the result's
+ * cell-element type being `char` (matches MATLAB; numbl wraps as
+ * string but mtoc2 follows MATLAB by emitting chars).
+ *
+ * Interpreter-only for now; the AOT path would need to materialize
+ * a heterogeneous-len cell of chars which is a different feature
+ * class. The `emitC` / `emitJs` hooks exist so the registry-shape
+ * invariant holds but they raise `UnsupportedConstruct` rather than
+ * letting the framework's generic "no emitC hook" surface.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const fieldnames: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isa.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `isa(value, 'ClassName')` — checks whether `value` is an instance
+ * of the named class (or matches one of MATLAB's primitive class
+ * names: `double`, `logical`, `char`, `string`, `struct`,
+ * `function_handle`, `cell`, `numeric`).
+ *
+ * Always static: mtoc2 knows every value's type at lowering time and
+ * folds to a scalar logical literal. Matches numbl's
+ * `runtimeDispatch.ts:isa` minus the inheritance-chain walk (mtoc2
+ * has no inheritance in v1).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const isa: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/iscell.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `iscell(x)` — folds true if the argument's static type is a Cell,
+ * false otherwise. Always static because the kind is part of the type.
+ *
+ * Matches numbl `introspection.ts:173-180` (returns `1` / `0`).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const iscell: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isempty.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const isempty: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isequal.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const isequal: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isfield.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `isfield(s, name)` — does the struct/class `s` have a field/property
+ * named `name`?
+ *
+ * Numbl semantics
+ * (`numbl-core/interpreter/builtins/type-constructors.ts`):
+ *   - Struct or class instance → `true` iff `name` is in the field list.
+ *   - Anything else (numeric tensor, `[]`, char, string, handle, …) →
+ *     `false`. There is no "empty matrix as struct" coercion; the
+ *     non-struct branch just returns `false` so `isfield([], 'foo')`
+ *     naturally yields `false`.
+ *
+ * mtoc2 restricts the second argument to a Char or String literal
+ * (`.exact` set) — sufficient for the common `isfield(s, 'name')` /
+ * `isfield(s, "name")` shape. Runtime-only names would need a string
+ * comparison against the (compile-time-known) struct field set, which
+ * isn't worth wiring until something needs it.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const isfield: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isinf.d.ts

@@ -0,0 +1,2 @@
+export declare const isinf: import("../../registry.js").Builtin;
+export declare const isfinite: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isnan.d.ts

@@ -0,0 +1 @@
+export declare const isnan: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isnumeric.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `isnumeric(x)` — folds true if the argument's static type is a
+ * Numeric (real or complex, scalar or tensor, double or logical?
+ * MATLAB excludes logical). Matches numbl's introspection.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const isnumeric: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isreal.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const isreal: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isscalar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `isscalar(x)` — does `x` hold a single element?
+ *
+ * Numbl semantics
+ * (`numbl-core/interpreter/builtins/introspection.ts`, plus the
+ * `jitEmit` shortcut for `string`):
+ *   - Real or logical scalar number → `true`.
+ *   - Complex scalar → `true`.
+ *   - Tensor → `true` iff `numel == 1`.
+ *   - String handle (`"..."`) → `true` (single handle = scalar).
+ *   - Char array (`'...'`) → `false`, even for `'a'` — char arrays
+ *     are 1×N and treated as non-scalar.
+ *   - Struct / class instance / function handle → `false`.
+ *
+ * The result folds at type-check time whenever the shape is known
+ * (which is the common case). When a tensor's shape is opaque the
+ * emit paths fall back to a `numel == 1` runtime check.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const isscalar: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/isstruct.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `isstruct(x)` — folds true if the argument's static type is a
+ * struct, false otherwise. Class instances are NOT structs (matches
+ * MATLAB / numbl `introspection.ts:182`).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const isstruct: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/logical.d.ts

@@ -0,0 +1 @@
+export declare const logical: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/not.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `not` builtin — backs the `~` unary operator.
+ *
+ * Elementwise logical NOT. Numbl's `not(v)` in
+ * `runtime/runtimeOperators.ts` line 100:
+ *   - scalar 0          → logical true
+ *   - scalar nonzero    → logical false
+ *   - tensor            → logical tensor of same shape; element-wise
+ *                         `(x == 0) ? 1 : 0`
+ *
+ * Type result is always logical (mtoc2's `NumericType.elem = "logical"`).
+ * Sign is `nonneg` since outputs are in {0, 1}.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const notBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/or.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `or(a, b)` — the function form of `|`. For scalar arguments,
+ * mtoc2 routes this through the same scaffold as `||` (`oror`): the
+ * result type is scalar logical, the codegen uses C's `||` operator,
+ * and the only semantic difference (short-circuit on `||` vs.
+ * eager-evaluate on `|` / `or`) is moot — by the time the function
+ * is called, both arguments have already been computed by the
+ * call-site machinery, so the C-level short-circuit is harmless.
+ * Tensor / elementwise behavior is deferred.
+ */
+export declare const orBuiltin: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/oror.d.ts

@@ -0,0 +1 @@
+export declare const oror: import("../../registry.js").Builtin;