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);
------------------------------

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
	 
