Skip to content

Special properties

Chung Leong edited this page Apr 25, 2024 · 5 revisions

Each Zig object has a set of special properties:

dataView

The DataView of the object's underlying bytes. Should be considered volatile as its buffer can become detached during WebAssembly memory reallocation. Do not create a long-living reference to it.

base64

A base64 string containing the object's underlying bytes. Can be used to embed the content of a struct into a URL. Example:

pub const Hello = struct {
    number1: i32 = 0,
    number2: i32 = 0,
    number3: i32 = 0,
};
import { Hello } from './base64-example-1.zig';

const hello = new Hello({ number1: 1000, number2: 2000 });
const url = new URL(`http://example.net/?s=${hello.base64}`);
const helloCopy = new Hello({ base64: url.searchParams.get('s') });
console.log(hello.valueOf());
console.log(helloCopy.valueOf());
{ number1: 1000, number2: 2000, number3: 0 }
{ number1: 1000, number2: 2000, number3: 0 }

typedArray

TypedArray view the object's underlying bytes. Should be consider volatile as well.

Arrays and slices of numeric types have this property:

pub const Int32Array4 = [4]i32;
pub const Float32Slice = []f32;
import { Float32Slice, Int32Array4 } from './typed-array-example-1.zig';

const array = new Int32Array4([ 1, 2, 3, 4 ]);
console.log(array.typedArray);
const slice = new Float32Slice((function*() {
  for (let i = 1; i <= 10; i++) {
    yield Math.PI * i;
  }
})());
console.log(slice.typedArray);
Int32Array(4) [ 1, 2, 3, 4 ]
Float32Array(10) [
  3.1415927410125732,
  6.2831854820251465,
  9.42477798461914,
  12.566370964050293,
  15.707962989807129,
  18.84955596923828,
  21.991147994995117,
  25.132741928100586,
  28.274333953857422,
  31.415925979614258
]

Vectors have it too:

pub const Float32Vector4 = @Vector(4, f32);
import { Float32Vector4 } from './typed-array-example-2.zig';

const vector = new Float32Vector4([ 1, 2, 3, 4 ]);
console.log(vector.typedArray);
Float32Array(4) [ 1, 2, 3, 4 ]

Multi-dimensional arrays and slices inherit this property from their elements:

pub const Float32Vector3Slice = []@Vector(3, f32);
import { Float32Vector3Slice } from './typed-array-example-3.zig';

const slice = new Float32Vector3Slice((function*() {
    for (let i = 1; i <= 4; i++) {
        yield [ 1, 2, 3 ].map(n => n * i);
    }
})());
console.log(slice.valueOf());
console.log(slice.typedArray);
[ [ 1, 2, 3 ], [ 2, 4, 6 ], [ 3, 6, 9 ], [ 4, 8, 12 ] ]
Float32Array(16) [
  1, 2,  3, 0, 2, 4,
  6, 0,  3, 6, 9, 0,
  4, 8, 12, 0
]

Note the gaps within the Float32Array due to []@Vector(3, f32) having a 16-byte alignment.

string

The content of the object interpreted as a Unicode string. Available only for arrays and slices of u8 and u16.

$ (dollar-sign)

The dollar-sign property represents the value of the object. Its main purpose is to allow you to assign a new value to the object as a whole. For example, suppose you have an instance of the following struct:

pub const Hello = struct {
    number1: i32 = 0,
    number2: i32 = 0,
    number3: i32 = 0,
};

Assignment to its $ would basically reinitialize the object:

import { Hello } from './dollar-sign-example-1.zig';

const hello = new Hello({ number1: 1000, number2: 2000 });
console.log(hello.valueOf());
hello.$ = { number3: 3000 };
console.log(hello.valueOf());
{ number1: 1000, number2: 2000, number3: 0 }
{ number1: 0, number2: 0, number3: 3000 }

The dollar sign is also the mean by which you can access the value of a standalone scalar:

pub const I32 = i32;
import { I32 } from './dollar-sign-example-2.zig';

const number = new I32(1234);
console.log(number);
console.log(number.$);
i32 {
  [Symbol(memory)]: DataView {
    byteLength: 4,
    byteOffset: 0,
    buffer: ArrayBuffer { [Uint8Contents]: <d2 04 00 00>, byteLength: 4 }
  }
}
1234

Special methods

Clone this wiki locally