# Globals

The following global constants and functions are present alongside the standard library's classes.

# Constants

```
const NaN: auto // f32 or f64
```
Not a number as a 32-bit or 64-bit float depending on context. Compiles to a constant.
```
const Infinity: auto // f32 or f64
```
Positive infinity as a 32-bit or 64-bit float depending on context. Compiles to a constant.

# Functions

```
function isNaN<T>(value: T): bool
```
Tests if a 32-bit or 64-bit float is NaN.
```
function isFinite<T>(value: T): bool
```
Tests if a 32-bit or 64-bit float is finite, that is not NaN or +/-Infinity.
```
function parseInt(str: string, radix?: i32): i64
```
Parses a string to a 64-bit integer. Returns 0 on invalid inputs.
```
function parseFloat(str: string): f64
```
Parses a string to a 64-bit float. Returns NaN on invalid inputs.

# Builtins

The following builtins provide direct access to WebAssembly and compiler features. They form the low-level foundation of the standard library, while also being available for everyone to utilize where directly tapping into WebAssembly or the compiler is desired.

# Static type checks

By making use of the following special type checks, especially in generic contexts, untaken branches can be eliminated statically, leading to concrete WebAssembly functions that handle one type specificially.

```
function isInteger<T>(value?: T): bool
```
Tests if the specified type or expression is of an integer type and not a reference. Compiles to a constant.
```
function isFloat<T>(value?: T): bool
```
Tests if the specified type or expression is of a float type. Compiles to a constant.
```
function isSigned<T>(value?: T): bool
```
Tests if the specified type or expression can represent negative numbers. Compiles to a constant.
```
function isReference<T>(value?: T): bool
```
Tests if the specified type or expression is of a reference type. Compiles to a constant.
```
function isString<T>(value?: T): bool
```
Tests if the specified type or expression can be used as a string. Compiles to a constant.
```
function isArray<T>(value?: T): bool
```
Tests if the specified type or expression can be used as an array. Compiles to a constant.
```
function isFunction<T>(value?: T): bool
```
Tests if the specified type or expression is of a function type. Compiles to a constant.
```
function isNullable<T>(value?: T): bool
```
Tests if the specified type or expression is of a nullable reference type. Compiles to a constant.
```
function isDefined(expression: auto): bool
```
Tests if the specified expression resolves to a defined element. Compiles to a constant.
```
function isConstant(expression: auto): bool
```
Tests if the specified expression evaluates to a constant value. Compiles to a constant.
```
function isManaged<T>(expression: auto): bool
```
Tests if the specified type or expression is of a managed type. Compiles to a constant. Usually only relevant when implementing custom collection-like classes.

# Example of static type checking

function add<T>(a: T, b: T): T {
  return a + b // addition if numeric, string concatenation if a string
}

function add<T>(a: T, b: T): T {
  if (isString<T>()) { // eliminated if T is not a string
    return parseInt(a) + parseInt(b)
  } else { // eliminated if T is a string
    return a + b
  }
}

TIP

If you are not going to use low-level WebAssembly in the foreseeable future, feel free to come back to the following paragraphs at a later time.

# Utilities

```
function sizeof<T>(): usize
```
Determines the byte size of the respective basic type. Means: If T is a class type, the size of usize, the pointer type, is returned. To obtain the size of a class in memory, use offsetof<T>() instead. Compiles to a constant.
```
function offsetof<T>(fieldName?: string): usize
```
Determines the offset of the specified field within the given class type. If fieldName is omitted, this returns what could be interpreted as either the size of the class, or the offset where the next field would be located, before alignment. Compiles to a constant. The fieldName argument must be a compile-time constant string because there is no information about field names anymore at runtime. Therefore, the field's name must be known at the time the returned constant is computed.
```
function alignof<T>(): usize
```
Determines the alignment (log2) of the specified underlying basic type; i.e. If T is a class type, the alignment of usize is returned. Compiles to a constant.
```
function assert<T>(isTrueish: T, message?: string): T
```
Traps if the specified value is not true-ish, otherwise returns the non-nullable value. Like assertions in C, aborting the entire program if the expectation fails. Where desired, the --noAssert compiler option can be used to disable assertions in production.
```
function instantiate<T>(...args: auto[]): T
```
Instantiates a new instance of T using the specified constructor arguments.
```
function changetype<T>(value: auto): T
```
Changes the type of a value to another one. Useful for casting class instances to their pointer values and vice-versa.
```
function idof<T>(): u32
```
Obtains the computed unique id of a class type. Usually only relevant when allocating objects or dealing with RTTI externally.
```
function nameof<T>(value?: T): string
```
Returns the name of a given type.
```
function bswap<T>(value: T): T
```
Reverses the byte order of the specified integer.
```
function bswap16<T>(value: T): T
```
Reverses only the last 2 bytes regardless of the type argument.

# WebAssembly

# Math

The following generic built-ins compile to WebAssembly instructions directly.

```
function clz<T>(value: T): T
```
Performs the sign-agnostic count leading zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered leading if the value is zero.

T Instruction

i8, u8, i16, u16, i32, u32, bool i32.clz

i64, u64 i64.clz
```
function ctz<T>(value: T): T
```
Performs the sign-agnostic count tailing zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered trailing if the value is zero.

T Instruction

i8, u8, i16, u16, i32, u32, bool i32.ctz

i64, u64 i64.ctz
```
function popcnt<T>(value: T): T
```
Performs the sign-agnostic count number of one bits operation on a 32-bit or 64-bit integer.

T Instruction

i8, u8, i16, u16, i32, u32 i32.popcnt

i64, u64 i64.popcnt

bool none
```
function rotl<T>(value: T, shift: T): T
```
Performs the sign-agnostic rotate left operation on a 32-bit or 64-bit integer.

T Instruction

i32, u32 i32.rotl

i64, u64 i64.rotl

i8, u8, i16, u16 emulated

bool none
```
function rotr<T>(value: T, shift: T): T
```
Performs the sign-agnostic rotate right operation on a 32-bit or 64-bit integer.

T Instruction

i32, u32 i32.rotr

i64, u64 i64.rotr

i8, u8, i16, u16 emulated

bool none
```
function abs<T>(value: T): T
```
Computes the absolute value of an integer or float.

T Instruction

f32 f32.abs

f64 f64.abs

i8, i16, i32, i64 emulated

u8, u16, u32, u64, bool none
```
function max<T>(left: T, right: T): T
```
Determines the maximum of two integers or floats. If either operand is NaN, returns NaN.

T Instruction

f32 f32.max

f64 f64.max

i8, u8, i16, u16, i32, u32, i64, u64, bool emulated
```
function min<T>(left: T, right: T): T
```
Determines the minimum of two integers or floats. If either operand is NaN, returns NaN.

T Instruction

f32 f32.min

f64 f64.min

i8, u8, i16, u16, i32, u32, i64, u64, bool emulated
```
function ceil<T>(value: T): T
```
Performs the ceiling operation on a 32-bit or 64-bit float.

T Instruction

f32 f32.ceil

f64 f64.ceil

i8, u8, i16, u16, i32, u32, i64, u64, bool none
```
function floor<T>(value: T): T
```
Performs the floor operation on a 32-bit or 64-bit float.

T Instruction

f32 f32.floor

f64 f64.floor

i8, u8, i16, u16, i32, u32, i64, u64, bool none
```
function copysign<T>(x: T , y: T): T
```
Composes a 32-bit or 64-bit float from the magnitude of x and the sign of y.

T Instruction

f32 f32.copysign

f64 f64.copysign
```
function nearest<T>(value: T): T
```
Rounds to the nearest integer half to even of a 32-bit or 64-bit float.

T Instruction

f32 f32.nearest

f64 f64.nearest

i8, u8, i16, u16, i32, u32, i64, u64, bool none
```
function reinterpret<TTo>(value: auto): TTo
```
Reinterprets the bits of the specified value as type T.

TTo Instruction

i32, u32 i32.reinterpret_f32

i64, u64 i64.reinterpret_f64

f32 f32.reinterpret_i32

f64 f64.reinterpret_i64
```
function sqrt<T>(value: T): T
```
Calculates the square root of a 32-bit or 64-bit float.

T Instruction

f32 f32.sqrt

f64 f64.sqrt
```
function trunc<T>(value: T): T
```
Rounds to the nearest integer towards zero of a 32-bit or 64-bit float.

T Instruction

f32 f32.trunc

f64 f64.trunc

i8, u8, i16, u16, i32, u32, i64, u64, bool none

T	Instruction
i8, u8, i16, u16, i32, u32, bool	i32.clz
i64, u64	i64.clz

T	Instruction
i8, u8, i16, u16, i32, u32, bool	i32.ctz
i64, u64	i64.ctz

T	Instruction
i8, u8, i16, u16, i32, u32	i32.popcnt
i64, u64	i64.popcnt
bool	none

T	Instruction
i32, u32	i32.rotl
i64, u64	i64.rotl
i8, u8, i16, u16	emulated
bool	none

T	Instruction
i32, u32	i32.rotr
i64, u64	i64.rotr
i8, u8, i16, u16	emulated
bool	none

T	Instruction
f32	f32.abs
f64	f64.abs
i8, i16, i32, i64	emulated
u8, u16, u32, u64, bool	none

T	Instruction
f32	f32.max
f64	f64.max
i8, u8, i16, u16, i32, u32, i64, u64, bool	emulated

T	Instruction
f32	f32.min
f64	f64.min
i8, u8, i16, u16, i32, u32, i64, u64, bool	emulated

T	Instruction
f32	f32.ceil
f64	f64.ceil
i8, u8, i16, u16, i32, u32, i64, u64, bool	none

T	Instruction
f32	f32.floor
f64	f64.floor
i8, u8, i16, u16, i32, u32, i64, u64, bool	none

T	Instruction
f32	f32.copysign
f64	f64.copysign

T	Instruction
f32	f32.nearest
f64	f64.nearest
i8, u8, i16, u16, i32, u32, i64, u64, bool	none

TTo	Instruction
i32, u32	i32.reinterpret_f32
i64, u64	i64.reinterpret_f64
f32	f32.reinterpret_i32
f64	f64.reinterpret_i64

T	Instruction
f32	f32.sqrt
f64	f64.sqrt

T	Instruction
f32	f32.trunc
f64	f64.trunc
i8, u8, i16, u16, i32, u32, i64, u64, bool	none

# Memory

Similarly, the following built-ins emit WebAssembly instructions accessing or otherwise modifying memory.

NOTE

The immOffset and immAlign arguments, if provided, must be compile time constant values.

function load<T>(ptr: usize, immOffset?: usize): T

Loads a value of the specified type from memory. Equivalent to dereferencing a pointer in other languages.

T	Instruction	If contextual type is i64
i8	i32.load8_s	i64.load8_s
u8	i32.load8_u	i64.load8_u
i16	i32.load16_s	i64.load16_s
u16	i32.load16_u	i64.load16_u
i32	i32.load	i64.load32_s
u32	i32.load	i64.load32_u
i64, u64	i64.load	n/a
f32	f32.load	n/a
f64	f64.load	n/a
<ref>	i32/i64.load	n/a

function store<T>(ptr: usize, value: auto, immOffset?: usize): void

Stores a value of the specified type to memory. Equivalent to dereferencing a pointer in other languages and assigning a value.

T	Instruction	If value is i64
i8, u8	i32.store8	i64.store8
i16, u16	i32.store16	i64.store16
i32, u32	i32.store	i64.store32
i64, u64	i64.store	n/a
f32	f32.store	n/a
f64	f64.store	n/a
<ref>	i32/i64.store	n/a

```
function memory.size(): i32
```
Returns the current size of the memory in units of pages. One page is 64kb.
```
function memory.grow(value: i32): i32
```
Grows linear memory by a given unsigned delta of pages. One page is 64kb. Returns the previous size of the memory in units of pages or -1 on failure.

WARNING

Calling memory.grow where a memory manager is present might break it.
```
function memory.copy(dst: usize, src: usize, n: usize): void
```
Copies n bytes from src to dst . Regions may overlap. Emits the respective instruction if bulk-memory is enabled, otherwise ships a polyfill.
```
function memory.fill(dst: usize, value: u8, n: usize): void
```
Fills n bytes at dst with the given byte value. Emits the respective instruction if bulk-memory is enabled, otherwise ships a polyfill.

function memory.repeat(dst: usize, src: usize, srcLength: usize, count: usize): void

Repeats a sequence of bytes given as src with srcLength count times into destination dst.

```
function memory.compare(lhs: usize, rhs: usize, n: usize): i32
```
Compares the first n bytes of left and right and returns a value that indicates their relationship:
- Negative value if the first differing byte in lhs is less than the corresponding byte in rhs.
- Positive value if the first differing byte in lhs is greater than the corresponding byte in rhs.
- Zero if all n bytes of lhs and rhs are equal.
```
function memory.data(size: i32, align?: i32): usize
```
Gets a pointer to a zeroed static chunk of memory of the given size. Alignment defaults to 16. Arguments must be compile-time constants.
```
function memory.data<T>(values: T[], align?: i32): usize
```
Gets a pointer to a pre-initialized static chunk of memory. Alignment defaults to the size of T. Arguments must be compile-time constants.

# Control flow

```
function select<T>(ifTrue: T, ifFalse: T, condition: bool): T
```
Selects one of two pre-evaluated values depending on the condition. Differs from an if/else in that both arms are always executed and the final value is picked based on the condition afterwards. Performs better than an if/else only if the condition is random (means: branch prediction is not going to perform well) and both alternatives are cheap. It is also worth to note that Binaryen will do relevant optimizations like switching to a select automatically, so simply using a ternary ? : may be preferable.
```
function unreachable(): auto
```
Emits an unreachable instruction that results in a runtime error (trap) when executed. Both a statement and an expression of any type. Beware that trapping in managed code will most likely lead to memory leaks or even break the program because it ends execution prematurely.

# Constructing constant vectors

```
function i8x16(a: i8, ... , p: i8): v128
```
Initializes a 128-bit vector from sixteen 8-bit integer values. Arguments must be compile-time constants.
```
function i16x8(a: i16, ..., h: i16): v128
```
Initializes a 128-bit vector from eight 16-bit integer values. Arguments must be compile-time constants.
```
function i32x4(a: i32, b: i32, c: i32, d: i32): v128
```
Initializes a 128-bit vector from four 32-bit integer values. Arguments must be compile-time constants.
```
function i64x2(a: i64, b: i64): v128
```
Initializes a 128-bit vector from two 64-bit integer values. Arguments must be compile-time constants.
```
function f32x4(a: f32, b: f32, c: f32, d: f32): v128
```
Initializes a 128-bit vector from four 32-bit float values. Arguments must be compile-time constants.
```
function f64x2(a: f64, b: f64): v128
```
Initializes a 128-bit vector from two 64-bit float values. Arguments must be compile-time constants.

# Inline instructions

In addition to using the generic builtins above, most WebAssembly instructions can be written directly in AssemblyScript code. For example, the following is equivalent:

// generic builtin
v128.splat<i32>(42);

// inline instruction
i32x4.splat(42);

← Number Types Overview →