SPL Builtins Function Library

This module contains the SPL 'standard' builtin functions. It does not
need to be loaded explicitely, most SPL runtimes load it automatically
for you.

builtin write(text, encoding);
builtin read(prompt, encoding);
builtin chr(number);
builtin ord(text);
builtin hex(text);
builtin oct(text);
builtin bin(text);
builtin fmt(text, @args);
builtin rand(max);
builtin setlocale(category, locale);
builtin bindtextdomain(domain, directory);
builtin textdomain(domain);
builtin gettext(message);
builtin dgettext(domain, message);
builtin _(message, domain, @args);
builtin acos(x);
builtin asin);
builtin atan(x);
builtin atan2(x, y);
builtin cos(x);
builtin sin(x);
builtin tan(x);
builtin sqrt(x);
builtin round(x);
builtin ceil(x);
builtin floor(x);

builtin write(text, encoding);

Write the text passed as argument to standard ouput. Some SPL runtimes
replace this function with their own output function.

If the output should not be UTF-8 encoded, the encoding must be specified
with a 2nd parameter. Valid encodings are the same as for the '#encoding'
compiler pragma (see 'SPL Language Reference' for a list).

builtin read(prompt, encoding);

Read a line from the standard input. Some SPL runtimes replace this
function with their own input function. The read text (or undef on
end-of-file) is returned.

The fist parameter can be used to specify a prompt to be displayed for
reading the line.

If the output is not UTF-8 encoded, the encoding must be specified with a
2nd parameter. Valid encodings are the same as for the '#encoding' compiler
pragma (see 'SPL Language Reference' for a list).

If UTF-8 encoding is expected but the output fails to pass the UTF-8 test,
the output is assumed to be latin1 encoded.

builtin chr(number);

Create a (unicode) charater from the number passed as argument.

builtin ord(text);

Return the unicode character number of the first character in the text.

builtin hex(text);

Convert a string holding a hexadezimal number to an integer value. A
leading "0x" or "0X" is ignored. Zero is returned if there is no
hexadezimal number in the string.

builtin oct(text);

Convert a string holding an octal number to an integer value. A
leading "0o" or "0O" is ignored. Zero is returned if there is no
octal number in the string.

builtin bin(text);

Convert a string holding a binary number to an integer value. A
leading "0b" or "0B" is ignored. Zero is returned if there is no
binary number in the string.

builtin fmt(text, @args);

A C printf()-like format function. The formatted string is returned.
The following special sequences are supported:

	%%	A '%' character
	%s	A string
	%d	A decimal integer
	%x	A hexadecimal integer (lowercase letters)
	%X	A hexadecimal integer (uppercase letters)
	%o	An octal integer
	%b	A binary integer
	%f	A floating point number

The field width and precision format of printf() is also supported. But
currently there is no support for 'N$' argument specifications.

builtin rand(max);

Returns a random integer number, larger then or equal to zero and smaller
then the 'max' argument.

When the argument is 0 or missing, the return value is a floating point
number between 0 and 1. When the argument is -1, the return value is an
integer between 0 and RAND_MAX.

builtin setlocale(category, locale);

The setlocale() function is used to set or query the program's current locale.

This is a simple wrapper for the C setlocale() function. The 'category'
argument is passed as string. E.g.:

	setlocale("LC_ALL", "C");

builtin bindtextdomain(domain, directory);

The bindtextdomain() function sets the base directory of the hierarchy
containing message catalogs for a given message domain.

This is a simple wrapper for the C bindtextdomain() function.

builtin textdomain(domain);

The textdomain() function sets or retrieves the current message domain.

This is a simple wrapper for the C textdomain() function.

builtin gettext(message);

The gettext() function attempts to translate a text string into the user's
native language, by looking up the translation in a message catalog.

This is a simple wrapper for the C gettext() function.

builtin dgettext(domain, message);

The dgettext() function attempts to translate a text string into the user's
native language, by looking up the translation in a message catalog.

This is a simple wrapper for the C gettext() function.

builtin _(message, domain, @args);

This function is implementing the backend functionality of the SPL
translation prefix for strings (_).

It translates the message using the gettext() function and then
substitutes '{N}' with the strings passed as additional arguments (N
beeing the index in @args) and '{}' with a simple '{'.

builtin acos(x);

arc cosine function

builtin asin);

arc sine function

builtin atan(x);

arc tangent function

builtin atan2(x, y);

arc tangent function of two variables

builtin cos(x);

cosine function

builtin sin(x);

sine function

builtin tan(x);

tangent function

builtin sqrt(x);

square root function

builtin round(x);

round to nearest integer

builtin ceil(x);

smallest integral value not less than argument

builtin floor(x);

largest integral value not greater than argument