Skip to content

built-ins-binary-data.md

Latest commit

 

History

History
88 lines (58 loc) · 6.61 KB

built-ins-binary-data.md

File metadata and controls

88 lines (58 loc) · 6.61 KB
Raw

Binary Data Built-ins

ArrayBuffer, SharedArrayBuffer, Atomics, DataView, and TypedArray API reference.

Executive Summary

  • ArrayBuffer — raw binary data buffers with fixed-length and resizable modes, transfer semantics, and detachment
  • SharedArrayBuffer — fixed-length binary buffer with the same API shape as ArrayBuffer but as a distinct type
  • Atomics — atomic read-modify-write, wait/notify, waitAsync, and pause operations over shared integer TypedArray views
  • DataView — endian-aware typed reads and writes over ArrayBuffer and SharedArrayBuffer storage
  • TypedArrays — array-like views over buffer data with 12 element types (Int8 through Float64, BigInt64, BigUint64)
  • Uint8Array encoding — Base64 and hex encoding/decoding

ArrayBuffer (Goccia.Builtins.GlobalArrayBuffer.pas, Goccia.Values.ArrayBufferValue.pas)

Implements the ECMAScript ArrayBuffer. See MDN ArrayBuffer reference for the full API.

Full standard compliance — includes resizable buffers (maxByteLength), transfer, and transferToFixedLength.

Immutable buffers — the Immutable ArrayBuffers proposal is supported: transferToImmutable([newLength]) returns a fixed-length immutable buffer, the immutable getter reports the state, an immutable buffer cannot be detached (transfer, transferToFixedLength, and transferToImmutable throw on it), and writes through a backing view are rejected — TypedArray indexed assignment, set, fill, sort, copyWithin, reverse, integer-index defineProperty, Atomics, and DataView setters. Immutable buffers also back the default export of bytes module imports.

Internally backed by a zero-initialized TBytes array. ArrayBuffer instances are cloneable via structuredClone.

SharedArrayBuffer (Goccia.Values.SharedArrayBufferValue.pas)

Implements the ECMAScript SharedArrayBuffer. See MDN SharedArrayBuffer reference for the full API.

Full standard compliance. In GocciaScript, SharedArrayBuffer has the same API as ArrayBuffer but is a distinct type (not an instance of ArrayBuffer). SharedArrayBuffer instances are cloneable via structuredClone.

Atomics (Goccia.Builtins.Atomics.pas)

Implements the ECMAScript Atomics namespace for shared integer TypedArray views.

Supported operations: add, and, compareExchange, exchange, isLockFree, load, notify, or, pause, store, sub, wait, waitAsync, and xor.

Atomic memory operations require an integer TypedArray backed by SharedArrayBuffer. wait, waitAsync, and notify require Int32Array or BigInt64Array views.

DataView (Goccia.Values.DataViewValue.pas)

Implements the ECMAScript DataView. DataView instances provide endian-aware typed reads and writes over ArrayBuffer and SharedArrayBuffer storage.

Full standard compliance — includes integer, BigInt, Float16, Float32, and Float64 getters and setters, buffer, byteLength, byteOffset, and detached/out-of-bounds buffer checks. Auto-length views over resizable ArrayBuffer instances track the current buffer length.

TypedArrays (Goccia.Values.TypedArrayValue.pas)

Implements the ECMAScript TypedArray. See MDN TypedArray reference for the full API.

Full standard compliance for the supported types. All standard constructors, static methods (from, of), instance properties, and prototype methods are available.

Supported types:

Type Element size Value range
Int8Array 1 byte -128 to 127
Uint8Array 1 byte 0 to 255
Uint8ClampedArray 1 byte 0 to 255 (clamped)
Int16Array 2 bytes -32768 to 32767
Uint16Array 2 bytes 0 to 65535
Int32Array 4 bytes -2147483648 to 2147483647
Uint32Array 4 bytes 0 to 4294967295
Float16Array 2 bytes IEEE 754 half-precision
Float32Array 4 bytes IEEE 754 single-precision
Float64Array 8 bytes IEEE 754 double-precision
BigInt64Array 8 bytes -2⁶³ to 2⁶³-1 (BigInt)
BigUint64Array 8 bytes 0 to 2⁶⁴-1 (BigInt)

Value encoding: Integer types use fixed-width truncation (overflow wraps). Uint8ClampedArray clamps to [0, 255] with half-to-even rounding. Float16Array rounds to IEEE 754 half precision (max finite ±65504, epsilon 2⁻¹⁰ at 1.0). Float32Array rounds to IEEE 754 single precision. Float64Array preserves full double precision. NaN is stored as 0 in integer types and as NaN in float types.

Uint8Array Base64/Hex encoding (Goccia.Values.Uint8ArrayEncoding.pas)

Uint8Array Base64/Hex encoding. These methods are available only on Uint8Array, not on other TypedArray types.

Static method Description
Uint8Array.fromBase64(string [, options]) Decode a base64 string to a new Uint8Array. Options: alphabet ("base64" or "base64url"), lastChunkHandling ("loose", "strict", or "stop-before-partial")
Uint8Array.fromHex(string) Decode a hex string (case-insensitive) to a new Uint8Array. Throws SyntaxError on odd length or invalid characters
Prototype method Description
u8.toBase64([options]) Encode bytes as a base64 string. Options: alphabet ("base64" or "base64url"), omitPadding (boolean, default false)
u8.toHex() Encode bytes as a lowercase hex string
u8.setFromBase64(string [, options]) Decode base64 into this array. Returns { read, written }. Same options as fromBase64
u8.setFromHex(string) Decode hex into this array. Returns { read, written }

Related documents