built-in.md

Hook's built-in functions

Hook provides a range of convenient built-in functions that serve various purposes such as printing to the terminal, type checking, and more. These functions can be accessed globally, and this document provides a comprehensive list of all of them.

List of functions

Here is a quick overview of all the functions. Click on a function name to jump to its documentation.

print	println	type	is_nil	is_bool	is_number
is_int	is_string	is_range	is_array	is_struct	is_instance
is_iterator	is_callable	is_userdata	is_object	is_comparable	is_iterable
to_bool	to_int	to_number	to_string	ord	chr
hex	bin	adress	refcount	cap	len
is_empty	compare	split	join	iter	valid
current	next	sleep	exit	assert	panic

Below you will find all functions presented with their signatures, a brief description of their functionality, and examples of how to use them.

print

Prints the given value without a newline.

fn print(value);

Example:

print("Hello, "); // Hello, world!
print("World!");  //

println

Prints the given value with a newline.

fn println(value);

Example:

println("Hello, "); // Hello,
println("World!");  // World!

type

Returns the type of the given value as a string.

fn type(value) -> string;

Example:

println(type(1));     // number
println(type(3.14));  // number
println(type("foo")); // string
println(type(true));  // bool
println(type(nil));   // nil

is_nil

Returns true if the given value is nil.

fn is_nil(value) -> bool;

Example:

println(is_nil(nil)); // true
println(is_nil(1));   // false

is_bool

Returns true if the given value is a boolean.

fn is_bool(value) -> bool;

Example:

println(is_bool(true));  // true
println(is_bool(false)); // true
println(is_bool(1));     // false

is_number

Returns true if the given value is a number.

fn is_number(value) -> bool;

Example:

println(is_number(1));     // true
println(is_number(3.14));  // true
println(is_number("foo")); // false

is_int

Returns true if the given value is an integer number.

fn is_int(value) -> bool;

Example:

println(is_int(1));     // true
println(is_int(3.14));  // false
println(is_int("foo")); // false

is_string

Returns true if the given value is a string.

fn is_string(value) -> bool;

Example:

println(is_string("foo")); // true
println(is_string(1));     // false

is_range

Returns true if the given value is a range.

fn is_range(value) -> bool;

Example:

println(is_range(1..10)); // true
println(is_range(1));     // false

is_array

Returns true if the given value is an array.

fn is_array(value) -> bool;

Example:

println(is_array([1, 2, 3])); // true
println(is_array(1));         // false

is_struct

Returns true if the given value is a structure.

fn is_struct(value) -> bool;

Example:

struct Point { x, y }
println(is_struct(Point)); // true
println(is_struct(1));     // false

is_instance

Returns true if the given value is an instance of a structure.

fn is_instance(value) -> bool;

Example:

println(is_instance(Point { 1, 2 })); // true
println(is_instance(1));              // false

is_iterator

Returns true if the given value is an iterator.

fn is_iterator(value) -> bool;

Example:

println(iter(1..10));     // true
println(iter([1, 2, 3])); // true
println(1);               // false

is_callable

Returns true if the given value is callable (i.e. a function).

fn is_callable(value) -> bool;

Example:

fn foo() {}
println(is_callable(foo));   // true
println(is_callable(|| {})); // true
println(is_callable(print)); // true
println(is_callable(1));     // false

is_userdata

Returns true if the given value is a userdata.

fn is_userdata(value) -> bool;

Example:

import { stdout } from io;
println(is_userdata(stdout)); // true
println(is_userdata(1));      // false

is_object

Returns true if the given value is an object.

fn is_object(value) -> bool;

Example:

println(is_object(1));         // false
println(is_object(3.14));      // false
println(is_object(1..10));     // true
println(is_object("foo"));     // true
println(is_object([1, 2, 3])); // true
println(is_object(print));     // true

is_comparable

Returns true if the given value is comparable.

fn is_comparable(value) -> bool;

Example:

println(is_comparable(1));         // true
println(is_comparable(3.14));      // true
println(is_comparable(1..10));     // true
println(is_comparable("foo"));     // true
println(is_comparable([1, 2, 3])); // true
println(is_comparable(print));     // false

is_iterable

Returns true if the given value is iterable.

fn is_iterable(value) -> bool;

Example:

println(is_iterable(1));         // false
println(is_iterable(3.14));      // false
println(is_iterable("foo"));     // false
println(is_iterable(1..10));     // true
println(is_iterable([1, 2, 3])); // true
println(is_iterable(print));     // false

to_bool

Converts a value to a boolean. In Hook, only nil and false are considered false. All other values are considered true.

fn to_bool(value) -> bool;

Example:

println(to_bool(false)); // false
println(to_bool(nil));   // false
println(to_bool(true));  // true
println(to_bool(0));     // true
println(to_bool(1));     // true
println(to_bool(3.14));  // true
println(to_bool(""));    // true

to_int

Converts a floating point number or a string to an integer number. This function rises an error if the value cannot be converted. In fact, all numbers in Hook are floating point numbers. This function converts the number to an integer by truncating the fractional part.

fn to_int(value: number|string) -> number;

Example:

println(to_int(1));      // 1
println(to_int(3.14));   // 3
println(to_int("3.14")); // 3
println(to_int("foo"));  // Raises an error.

to_number

Converts a string to a floating point number. This function rises an error if the value cannot be converted.

fn to_number(value: number|string) -> number;

Example:

println(to_number(1));      // 1
println(to_number(3.14));   // 3.14
println(to_number("3.14")); // 3.14
println(to_number("foo"));  // Raises an error.

to_string

Converts a value to a string. Some types of values aren't convertible to a string.

fn to_string(value: nil|bool|number|string) -> string;

Example:

println(to_string(1));         // "1"
println(to_string(3.14));      // "3.14"
println(to_string(true));      // "true"
println(to_string(nil));       // "nil"
println(to_string([1, 2, 3])); // Raises an error.
println(to_string(print));     // <callable print>

ord

Returns the ASCII code of the first character of the given string.

fn ord(value: string) -> number;

Example:

println(ord("a")); // 97

chr

Returns a string that contains the character with the given ASCII code.

fn chr(value: number) -> string;

Example:

println(chr(97)); // "a"

hex

Converts a string to a hexadecimal string.

fn hex(value: string) -> string;

Example:

println(hex("foo")); // "666f6f"

bin

Converts a string to a binary string.

fn bin(value: string) -> string;

Example:

println(bin("666f6f")); // "foo"

address

Returns a hexadecimal string that represents the memory address of the given value if it is an object. Otherwise, it returns "(nil)".

fn address(value) -> string;

Example:

println(address(1));     // (nil)
println(address(3.14));  // (nil)
println(address("foo")); // 0x563ff4a0f730
println(address(1..10)); // 0x555b2c87dac0

refcount

Returns the reference count of the given value if it is an object. Otherwise, it returns 0.

fn refcount(value) -> number;

Example:

println(refcount(1));     // 0
println(refcount(3.14));  // 0
println(refcount("foo")); // 1
println(refcount(1..10)); // 1

cap

Returns the capacity of the given string or array.

fn cap(value: string|array) -> number;

Example:

println(cap("foo"));     // 8
println(cap([1, 2], 3)); // 8

len

Returns the length of the given compond value.

fn len(value: string|range|array|struct|instance) -> number;

Example:

println(len("foo"));     // 3
println(len([1, 2, 3])); // 3
println(len(1..10));     // 10

is_empty

Returns true if the given compound value is empty.

fn is_empty(value: string|range|array|struct|instance) -> bool;

Example:

println(is_empty(""));        // true
println(is_empty([]));        // true
println(is_empty(1..1));      // false
println(is_empty("foo"));     // false
println(is_empty([1, 2, 3])); // false

compare

Compares two values and returns a number that represents the result of the comparison.

fn compare(val1, val2) -> number;

Example:

println(compare(1, 2)); // -1
println(compare(2, 1)); // 1
println(compare(1, 1)); // 0

split

Splits the given string into an array of strings using the given separator.

fn split(str: string, separator: string) -> array;

Example:

println(split("foo,bar,baz", ",")); // ["foo", "bar", "baz"]

join

Joins the given array of strings into a single string containing the given separator between each element.

fn join(arr: array, separator: string) -> string;

Example:

println(join(["foo", "bar", "baz"], ",")); // "foo,bar,baz"

iter

Creates an iterator from a range or an array. This function raises an error if the given value is not iterable.

fn iter(value: iterator|range|array) -> iterator;

Example:

for (x in iter(1..3)) { // 1
  println(x);           // 2
}                       // 3

valid

Returns true if the given iterator has a valid current value.

fn valid(it: iterator) -> bool;

Example:

var it = iter(1..3);
println(valid(it)); // true
it = next(it);
println(valid(it)); // true
it = next(it);
println(valid(it)); // true
it = next(it);
println(valid(it)); // false

current

Returns the current value of the given iterator.

fn current(it: iterator) -> any;

Example:

var it = iter(1..3);
println(current(it)); // 1
it = next(it);
println(current(it)); // 2
it = next(it);
println(current(it)); // 3
it = next(it);
println(current(it)); // nil

next

Advances the given iterator to the next value and returns an updated iterator.

fn next(it: iterator) -> iterator;

Example:

var it = iter(1..3);
println(current(it)); // 1
it = next(it);
println(current(it)); // 2
it = next(it);
println(current(it)); // 3

sleep

Sleeps for the given number of milliseconds.

fn sleep(ms: number);

Example:

sleep(1000); // Sleeps for 1 second.

exit

Exits the program with the given exit code.

fn exit(code: number);

Example:

exit(0); // Exits the program with exit code 0.

assert

Raises an error if the given assertion is false.

fn assert(assertion: bool, msg: string);

Example:

assert(1 == 2, "1 is not equal to 2"); // Raises an error.

panic

Raises an error with the given message.

fn panic(msg: string);

Example:

panic("something went wrong!"); // panic: something went wrong!