3.12. Miscellaneous Functions

3.12.1. backquote()

Synopsis

Executes a process and returns a string of the output (stdout only)

Usage
backquote(shell_command_string)
Example
$files = backquote("ls");
Restrictions

Not available with PO_NO_EXTERNAL_PROCESS

Table 3.306. Arguments and Return Values for backquote()

Argument Type

Return Type

Description

String

String

Executes the string passed as a shell command in a subprocess and returns the stdout of the process as a string.


Table 3.307. Exceptions Thrown by backquote()

err

desc

BACKQUOTE-ERROR

An error occurred with the fork() or opening the stdout pipe.


3.12.2. call_builtin_function()

Synopsis

Calls a builtin function and returns the return value, passing the remaining arguments after the function name to the builtin function. This function can be used to override a builtin function's functionality with a custom implementation.

Usage
call_builtin_function(func, [arg1, arg2, ...])
Example
$result = call_builtin_function("func_name", $arg1, $arg2);

Table 3.308. Arguments and Return Values for call_builtin_function()

Argument Type

Return Type

Description

String, Any

Any (depends on function)

Executes the given builtin function with the remainder of the arguments as the arguments to the function.


Table 3.309. Exceptions Thrown by call_builtin_function()

err

desc

CALL-BUILTIN-FUNCTION-ERROR

The first argument must be a string.

INVALID-FUNCTION-ACCESS

Parse options do not allow access to the function.

NO-FUNCTION

The function does not exist.


3.12.3. call_builtin_function_args()

Synopsis

Calls a builtin function and returns the return value, using the optional second argument as a list of arguments for the function.

Usage
call_builtin_function_args(func, [args])
Example
call_builtin_function_args("func_name", $arg_list);

Table 3.310. Arguments and Return Values for call_builtin_function_args()

Argument Type

Return Type

Description

String, [List]

Any (depends on function)

Executes the given builtin function using any second argument as the list of arguments.


Table 3.311. Exceptions Thrown by call_builtin_function_args()

err

desc

CALL-BUILTIN-FUNCTION-ARGS-ERROR

The first argument must be a string.

INVALID-FUNCTION-ACCESS

Parse options do not allow access to the function.

NO-FUNCTION

The function does not exist.


3.12.4. call_function()

Synopsis

Calls a function, closure, or call reference and returns the return value, passing the remaining arguments after the function name to the function, closure, or call reference.

Usage
call_function(func, [arg1, arg2, ...])
Example
$result = call_function("func_name", $arg1, $arg2);
$result = call_function($call_ref, $arg1, $arg2);

Table 3.312. Arguments and Return Values for call_function()

Argument Type

Return Type

Description

String | closure | call reference, Any

Any (depends on function)

Executes the given function, closure, or call reference with the remainder of the arguments as the arguments to the function, closure, or call reference to be called.


Table 3.313. Exceptions Thrown by call_function()

err

desc

CALL-FUNCTION-PARAMETER-ERROR

The first argument must be a string, closure, or call reference.

INVALID-FUNCTION-ACCESS

Parse options do not allow access to the function.

NO-FUNCTION

The function does not exist.


3.12.5. call_function_args()

Synopsis

Calls a function, closure, or call reference and returns the return value, using the optional second argument as a list of arguments for the function, closure, or call reference to be called.

Usage
call_function_args(func, [args])
Example
call_function_args("func_name", $arg_list);
call_function_args($call_ref, $arg_list);

Table 3.314. Arguments and Return Values for call_function_args()

Argument Type

Return Type

Description

String | closure | call reference, [List]

Any (depends on function)

Executes the given function, closure, or call reference using any second argument as the list of arguments.


Table 3.315. Exceptions Thrown by call_function_args()

err

desc

CALL-FUNCTION-ARGS-PARAMETER-ERROR

The first argument must be a string, closure, or call reference.

INVALID-FUNCTION-ACCESS

Parse options do not allow access to the function.

NO-FUNCTION

The function does not exist.


3.12.6. callObjectMethod()

Synopsis

Calls a method of an object, passing the remainder of the arguments to the function as arguments to the method.

Usage
callObjectMethod(object, method_string, [args ...])
Example
$result = callObjectMethod($obj, "method", $arg1, $arg2);

Table 3.316. Arguments and Return Values for callObjectMethod()

Argument Type

Return Type

Description

Object, String, [args ...]

Any (depends on method)

Calls a method of an object, passing the remainder of the arguments to the function as arguments to the method, and returns the return value, if any.


Table 3.317. Exceptions Thrown by callObjectMethod()

err

desc

METHOD-DOES-NOT-EXIST

The named method does not exist in this class.

ILLEGAL-EXPLICIT-METHOD-CALL

The named method may not be called explicitly.

METHOD-IS-PRIVATE

The named method is private and therefore can only be called within the class.

BASE-CLASS-IS-PRIVATE

The named method is a member of a privately inherited base class.


3.12.7. callObjectMethodArgs()

Synopsis

Calls a method of an object, using the optional third argument as the argument list to the method.

Usage
callObjectMethodArgs(object, method_string, [arg_list])
Example
$result = callObjectMethodArgs($obj, "method", $arg_list);

Table 3.318. Arguments and Return Values for callObjectMethodArgs()

Argument Type

Return Type

Description

Object, String, [args ...]

Any (depends on method)

Calls a method of an object, using the optional third argument as the argument list to the method, and returns the return value, if any.


Table 3.319. Exceptions Thrown by callObjectMethodArgs()

err

desc

METHOD-DOES-NOT-EXIST

The named method does not exist in this class.

ILLEGAL-EXPLICIT-METHOD-CALL

The named method may not be called explicitly.

METHOD-IS-PRIVATE

The named method is private and therefore can only be called within the class.

BASE-CLASS-IS-PRIVATE

The named method is a member of a privately inherited base class.


3.12.8. existsFunction()

Synopsis

Returns True if the function exists in the current program's function name space.

Usage
existsFunction(string)
Example
$bool = existsFunction("func_name");

Table 3.320. Arguments and Return Values for existsFunction()

Argument Type

Return Type

Description

String

Boolean

Returns True if the function exists in the current program's function name space, otherwise returns False.


This function does not throw any exceptions.

3.12.9. functionType()

Synopsis

Returns "builtin", "user", or NOTHING according to the function name passed.

Usage
functionType(string)
Example
$type = functionType("print");

Table 3.321. Arguments and Return Values for functionType()

Argument Type

Return Type

Description

String

Boolean

Returns "builtin" (for a builtin function), "user" (for a user function), or NOTHING (if the function cannot be found) according to the function name passed.


This function does not throw any exceptions.

3.12.10. get_qore_library_info()

Synopsis

Returns a hash of library build and version info with the keys in the table Library Info Hash. For constants giving the same information, see Build and Version Constants.

Usage
get_qore_library_info()
Example
$info = get_qore_library_info();

Table 3.322. Arguments and Return Values for get_qore_library_info()

Arguments

Return Type

Description

n/a

Hash

A hash of library build and version info with the keys in the table Library Info Hash. For constants giving the same information, see Build and Version Constants.


This function does not throw any exceptions.

Table 3.323. Library Info Hash

Key

Description

PlatformOS

The operating system used to build the Qore library.

PlatformCPU

The CPU used as a target for the Qore library build.

VersionString

The full version string for this version of the Qore library.

VersionMajor

An integer giving the Qore library's major version number.

VersionMinor

An integer giving the Qore library's minor version number.

VersionSub

An integer giving the Qore library's release version number.

Build

An integer giving the Qore library's subversion revision number.

BuildHost

A string giving information about the host used to compile the Qore library.

Compiler

The compiler used to build the Qore library.

ModuleDir

The module directory assumed by default in the Qore library.

CFLAGS

The compiler flags used to compile the Qore library.

LDFLAGS

The linker flags used to link the Qore library.


3.12.11. get_qore_option_list()

Synopsis

Returns a list of hashes giving information about Qore library options for the current build. See Library Option Hash for information about the elements in the list returned. See Library Options for information about Qore library options.

Usage
get_qore_option_list()
Example
$list = get_qore_option_list();

Table 3.324. Arguments and Return Values for get_qore_option_list()

Arguments

Return Type

Description

n/a

List

A list of hashes giving information about Qore library options for the current build. See Library Option Hash for information about the elements in the list returned.


Table 3.325. Library Option Hash

Key

Description

option

The string description of the option

constant

A string giving the name of the constant that has the boolean value for this option.

type

The type of option.

value

The boolean value of the option.


This function does not throw any exceptions.

3.12.12. getByte()

Synopsis

Returns the byte value of the offset (starting with 0) in the object passed. Of no offset is passed, then the value of the first byte (offset 0) is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.

Usage
getByte(expr, [offset])
Example
$byte = getByte($bin, 2); # returns the thrid byte of the binary object

Table 3.326. Arguments and Return Values for getByte()

Arguments

Return Type

Description

expr, [offset]

Integer

The value of the byte at the offset in the string or binary object. If no offset is passed, then the first byte is returned. If the object is empty or the offset is larger than the object's size, then no value is returned.


3.12.13. getClassName()

Synopsis

Returns the class name of an object.

Usage
getClassName(object)
Example
$name = getClassName($obj);

Table 3.327. Arguments and Return Values for getClassName()

Argument Type

Return Type

Description

Object

String

Returns the class name of the object passed.


This function does not throw any exceptions.

3.12.14. getDBIDriverCapabilities()

Synopsis

Returns an integer representing the capabilities of a DBI driver corresponding to the driver name passed as an argument. See SQL constants for constants for names of drivers shipping with the qore distribution.

Usage
getDBIDriverCapabilities(driver_name)
Example
$caps = getDBIDriverCapabilities("oracle");

Table 3.328. Arguments and Return Values for getDBIDriverCapabilities()

Argument Type

Return Type

Description

String

Integer

Returns an integer representing the capabilities of a DBI driver binary-OR'ed together (see DBI Capability Constants). Returns NOTHING if the driver cannot be found.


This function does not throw any exceptions.

3.12.15. getDBIDriverCapabilityList()

Synopsis

Returns a list of each capability supported by the given DBI driver. See SQL constants for constants giving names of drivers shipping with the Qore distribution.

Usage
getDBIDriverCapabilityList(driver_name)
Example
$list = getDBIDriverCapabilityList("mysql");

Table 3.329. Arguments and Return Values for getDBIDriverCapabilityList()

Argument Type

Return Type

Description

String

List

Returns a list of each capability supported by the given DBI driver (see DBI Capability Constants). Returns NOTHING if the driver cannot be found.


This function does not throw any exceptions.

3.12.16. getDBIDriverList()

Synopsis

Returns a list of strings of DBI drivers currently loaded.

Usage
getDBIDriverList()
Example
$list = getDBIDriverList();

Table 3.330. Arguments and Return Values for getDBIDriverList()

Argument Type

Return Type

Description

n/a

List

Returns a list of strings of DBI drivers currently loaded.


This function does not throw any exceptions.

3.12.17. getFeatureList()

Synopsis

Returns a list of strings of the builtin and module-supplied features of Qore.

Usage
getFeatureList()
Example
$list = getFeatureList();

Table 3.331. Arguments and Return Values for getFeatureList()

Argument Type

Return Type

Description

n/a

List

Returns a list of strings of the builtin and module-supplied features of Qore.


This function does not throw any exceptions.

3.12.18. getMethodList()

Synopsis

Returns a list of strings of the names of the methods of the class of the object passed as a parameter.

Usage
getMethodList(object)
Example
$list = getMethodList($obj);

Table 3.332. Arguments and Return Values for getMethodList()

Argument Type

Return Type

Description

Object

List

Returns all methods in the class, both private and public. Does not return inherited methods. If no object is passed to the function, NOTHING is returned.


This function does not throw any exceptions.

3.12.19. getModuleList()

Synopsis

Returns a list of hashes describing the currently-loaded Qore modules.

Usage
getModuleList()
Example
$list = getModuleList();

Table 3.333. Arguments and Return Values for getModuleList()

Argument Type

Return Type

Description

n/a

List

Each element in the list is a hash describing currently-loaded qore modules.


This function does not throw any exceptions.

3.12.20. get_default_encoding()

Synopsis

Returns the name of the default character encoding for the currently-running Qore process.

Usage
get_default_encoding()
Example
$encoding = get_default_encoding();

Table 3.334. Arguments and Return Values for get_default_encoding()

Argument Type

Return Type

Description

n/a

String

Returns the name of the default character encoding.


This function does not throw any exceptions.

3.12.21. getpwuid()

Synopsis

Returns a hash representing the user information for the user ID passed.

Usage
getpwuid(integer_uid)
Example
$hash = getpwuid(0); # returns the login information for root

Table 3.335. Arguments and Return Values for getpwuid()

Argument Type

Return Type

Description

Integer

Hash

Returns a hash representing the user information for the user ID passed. If the uid does not exist, NOTHING is returned. Otherwise the hash has the following keys: pw_name, pw_passwd, pw_gecos, pw_dir, pw_shell, pw_uid, pw_gid.


This function does not throw any exceptions.

3.12.22. get_script_path()

Synopsis

Returns the path (directory and filename) of the current script. Returns NOTHING if unknown (i.e. no parent script, script read from stdin, etc).

Usage
get_script_path()
Example
$path = get_script_path();

Table 3.336. Arguments and Return Values for get_script_path()

Argument Type

Return Type

Description

n/a

String or NOTHING

Returns the path name of the current script, or NOTHING if unknown.


This function does not throw any exceptions.

3.12.23. get_script_dir()

Synopsis

Returns the name of the directory from which the current script was executed. Returns NOTHING if the parent script is unknown (i.e. no parent script, script read from stdin, etc).

Usage
get_script_dir()
Example
$dir = get_script_dir();

Table 3.337. Arguments and Return Values for get_script_dir()

Argument Type

Return Type

Description

n/a

String or NOTHING

Returns the name of the directory for the current script, or NOTHING if unknown.


This function does not throw any exceptions.

3.12.24. get_script_name()

Synopsis

Returns the filename of the current script if known; returns NOTHING if not (i.e. no parent script, script read from stdin, etc).

Usage
get_script_name()
Example
$name = get_script_name();

Table 3.338. Arguments and Return Values for get_script_name()

Argument Type

Return Type

Description

n/a

String or NOTHING

Returns the filename of the current script, or NOTHING if unknown.


This function does not throw any exceptions.

3.12.25. hash_values()

Synopsis

Returns a list of all the values in the hash argument passed.

Usage
hash_values(hash)
Example
$list = hash_values($hash);

Table 3.339. Arguments and Return Values for hash_values()

Argument Type

Return Type

Description

Hash

List

Returns a list of all the values in the hash argument passed. If no hash is passed, returns NOTHING.


This function does not throw any exceptions.

3.12.26. hextoint()

Synopsis

Returns an integer for a hexadecimal string value.

Usage
hextoint(hex_string)
Example
$int = hextoint("ab3d4e0f12");

Table 3.340. Arguments and Return Values for hextoint()

Argument Type

Return Type

Description

String

Integer

Returns an integer for a hexadecimal string value.


This function does not throw any exceptions.

3.12.27. html_decode()

Synopsis

Returns a string with any HTML escape codes translated to the original characters.

Usage
html_decode(string)
Example
html_decode("&lt;hello&gt;"); # returns "<hello>"

Table 3.341. Arguments and Return Values for html_decode()

Argument Type

Return Type

Description

String

String

Returns a string with any HTML escape codes (ie &amp; -> &, etc) translated to the original characters.


This function does not throw any exceptions.

3.12.28. html_encode()

Synopsis

Returns a string with any characters that can be escaped translated to HTML escape codes.

Usage
html_encode(string)
Example
$str = html_encode("<hello>"); # returns "&lt;hello&gt;"

Table 3.342. Arguments and Return Values for html_encode()

Argument Type

Return Type

Description

String

String

Returns a string with characters needed HTML escape code transation (ie & -> &amp; etc) translated to the escape codes.


This function does not throw any exceptions.

3.12.29. inlist()

Synopsis

Tests if the first argument is a member of the second argument list; types are converted if necessary. If the second argument is NOTHING, then False is returned unconditionally (i.e. even if the first argument is NOTHING as well), however if the second argument is not a list then the return value of the function is the comparison of the two arguments. For a version of this function that requires types to be equal for the comparison to succeed, see inlist_hard().

Usage
inlist(value, list)
Example
my $bool = inlist(123, (True, "123", False); # this will return True

Table 3.343. Arguments and Return Values for inlist()

Argument Type

Return Type

Description

value, list

Boolean

Returns True if value is a member of list; types are converted if necessary.

value, NOTHING

Boolean

Always returns False.

value1, value2

Boolean

Returns the value of the comparison of value1 with value2; types are converted if necessary.


This function does not throw any exceptions.

3.12.30. inlist_hard()

Synopsis

Tests if the first argument is a member of the second argument list; no type conversions are performed (i.e. the comparison fails if types are not equal). If the second argument is NOTHING, then False is returned unconditionally (i.e. even if the first argument is NOTHING as well), however if the second argument is not a list then the return value of the function is the comparison of the two arguments (types must be equal). For a "soft" version of this function that performs type conversions when doing the comparison, see inlist().

Usage
inlist_hard(value, list)
Example
my $bool = inlist_hard(123, (True, "123", False); # this will return False

Table 3.344. Arguments and Return Values for inlist_hard()

Argument Type

Return Type

Description

value, list

Boolean

Returns True if value is a member of list; no type conversions are performed (the comparison fails if types are not equal).

value, NOTHING

Boolean

Always returns False.

value1, value2

Boolean

Returns the value of the comparison of value1 with value2; no type conversions are performed (the comparison fails if the types are not equal).


This function does not throw any exceptions.

3.12.31. load_module()

Synopsis

Loads in a Qore module at run-time. If a feature with the same name already exists, then this feature's code is imported into the current Program object if necessary and no further action is taken. Note that modules providing objects resolved at parse time (classes, constants, functions, etc) must be loaded with the %requires directive instead, unless all references to the objects provided by the module will be made in code embedded in Program objects.

See also getFeatureList() for a function providing a list of available features.

Usage
load_module(module_name)
Example
load_module("pgsql");

Table 3.345. Arguments and Return Values for load_module()

Argument Type

Return Type

Description

String

String

Loads the module with the given name if possible, otherwise throws an exception. This function returns no value.


Table 3.346. Exceptions Thrown by load_module()

err

desc

LOAD-MODULE-ERROR

An error occurred loading the module (module not found, libraries not resolved, wrong module API, etc).


3.12.32. makeBase64String()

Synopsis

Returns a base64-encoded representation of a binary object or a string (see also makeHexString()).

Usage
makeBase64String(arg)
Example
$str = makeBase64String($bin);

Table 3.347. Arguments and Return Values for makeBase64String()

Argument Type

Return Type

Description

Binary or String

String

Returns a base64-encoded representation of a binary object or a string.


This function does not throw any exceptions.

3.12.33. makeHexString()

Synopsis

Returns a hex-encoded representation of a binary object or a string (see also makeBase64String()).

Usage
makeHexString(arg)
Example
$str = makeHexString($bin);

Table 3.348. Arguments and Return Values for makeHexString()

Argument Type

Return Type

Description

Binary or String

String

Returns a hex-encoded representation of a binary object or a string.


This function does not throw any exceptions.

3.12.34. max()

Synopsis

Returns the maximum value in a list (see also min()). Without a callback, this function will only work on basic data types. A closure or call reference can be used to find the maximum value of a list of complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than, equal to, or greater than the second, respectively.

Usage
max(list, [callback])
max(elem1, elem2[, ...])
Example
$max = max($complex_list, \callback_function());
$max = max(1, 2, 3, 4);

Table 3.349. Arguments and Return Values for max()

Argument Type

Return Type

Description

list, [callback]

Any

Finds the maxmimum value in the list and returns that value. The list must be made up of basic data types unless a closure or call reference is used as described above.

elem1, elem2[, ...]

Any

Finds the maximum value in the list of simple data types passed as top-level arguments to the function and returns that value. No callback reference can be specified with this variant.


This function does not throw any exceptions (note a closure or call reference could throw an exception).

3.12.35. min()

Synopsis

Returns the minumum value in a list (see also max()). Without a callback, this function will only work on basic data types. A closure or call reference can be used to find the minimum value of a list of complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than, equal to, or greater than the second, respectively.

Usage
min(list, [callback])
min(elem1, elem2[, ...])
Example
$min = min($complex_list, \callback_function());
$min = min(1, 10, 2, 3);

Table 3.350. Arguments and Return Values for min()

Argument Type

Return Type

Description

list, [callback]

Any

Finds the minimum value in the list and returns that value. The list must be made up of basic data types unless a closure or call reference is used as described above.

elem1, elem2[, ...]

Any

Finds the minimum value in the list of simple data types passed as top-level arguments to the function and returns that value. No closure or call reference can be specified with this variant.


This function does not throw any exceptions (note that a closure or call reference could throw an exception).

3.12.36. parse()

Synopsis

Adds the text passed to the current program's code.

Usage
parse(code_string, label_string)
Example
parse($code, "label");

Table 3.351. Arguments and Return Values for parse()

Argument Type

Return Type

Description

String

n/a

Parses the string passed and adds the code to the current program.


Table 3.352. Exceptions Thrown by parse()

err

desc

PARSE-ERROR

An error occurred parsing the text.


3.12.37. parseBase64String()

Synopsis

Parses a base64 encoded string and returns the binary object (see also parseHexString()).

Usage
parseBase64String(base64_string)
Example
$bin = parseBase64String($base64_string);

Table 3.353. Arguments and Return Values for parseBase64String()

Argument Type

Return Type

Description

String

Binary

Parses a base64 encoded string and returns the binary object. If anything is passed other than a string as an argument, no action is taken and the function returns NOTHING.


Table 3.354. Exceptions Thrown by parseBase64String()

err

desc

BASE64-PARSE-ERROR

A syntax error occurred parsing the base64 string (invalid character, etc).


3.12.38. parseDatasource()

Synopsis

Returns a hash of the components of a datasource string.

Usage
parseDatasource(datasource_string)
Example
$hash = parseDatasource($ds_string);

Table 3.355. Arguments and Return Values for parseDatasource()

Argument Type

Return Type

Description

String

Hash

Returns a hash of the components of a datasource string. A datasource string has the following structure: driver:user/pass@db(charset)%host:port, where driver, charset, host, and port are optional. See parseDatasource() hash for a description of the output hash of this function.


Table 3.356. Exceptions Thrown by parseDatasource()

err

desc

DATASOURCE-PARSE-ERROR

A syntax error occurred parsing the datasource string (missing field, unexpected character, etc).


Table 3.357. parseDatasource() hash

Key

Description

type

the name of the driver, if present

user

the username given in the string

pass

the password for the connection

db

the database name for the connection

charset

The name of the DB-specific character encoding to use for the connection, if present in the string

host

the hostname for the connection, if present in the string

port

the port number to use for the connection, if present in the string


3.12.39. parseHexString()

Synopsis

Parses a hex-encoded string and returns the binary object (see also parseBase64String()).

Usage
parseHexString(hex_string)
Example
$bin = parseHexString($hex_string);

Table 3.358. Arguments and Return Values for parseHexString()

Argument Type

Return Type

Description

String

Binary

Parses a hex-encoded string and returns the binary object. If anything is passed other than a string as an argument, no action is taken and the function returns NOTHING.


Table 3.359. Exceptions Thrown by parseHexString()

err

desc

PARSE-HEX-ERROR

A syntax error occurred parsing the hex string (odd number of digits, invalid character, etc).


3.12.40. parseURL()

Synopsis

Parses a URL string and returns a hash of the components.

Usage
parseURL(url_string)
Example
$hash = parseURL($url_string);

Table 3.360. Arguments and Return Values for parseURL()

Argument Type

Return Type

Description

String

Hash

Parses a URL string and returns a hash of the components. URLs have the format: protocol://username:password@hostname:port/path, where only the hostname is mandatory.


This function does not throw any exceptions.

3.12.41. rand()

Synopsis

Returns a random integer number (uses the C library function random() to generate the number).

Usage
rand()
Example
$num = rand();

Table 3.361. Arguments and Return Values for rand()

Argument Type

Return Type

Description

n/a

Integer

A random integer number is returned. See srand() for a function to seed the random number generator.


This function does not throw any exceptions.

3.12.42. remove_signal_handler()

Synopsis

Removes a signal handler and returns the signal handling state to the default. By the time this function returns, changes to the signal handling thread have already been effected. See Signal Handling for more information.

Usage
remove_signal_handler(signal)
Example
remove_signal_handler(SIGINT);
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.362. Arguments and Return Values for remove_signal_handler()

Argument Type

Return Type

Description

Integer

n/a

The signal number to process.


This function does not throw any exceptions.

3.12.43. reverse()

Synopsis

Reverses a string or a list (depending on the argument) and returns the new string or list. Works properly on UTF-8 strings with multi-byte characters as well.

Usage
reverse(string_or_list)
Example
$str = reverse("ABCDEF"); # returns "FEDCBA"

Table 3.363. Arguments and Return Values for reverse()

Argument Type

Return Type

Description

List

List

The list with its elements reversed.

String

String

The string with its characters reversed.


This function does not throw any exceptions.

3.12.44. set_signal_handler()

Synopsis

Sets or replaces a signal handler according to the signal number and closure or call reference (function or object method reference) passed. By the time this function returns, changes to the signal handling thread have already been effected. See Signal Handling for more information.

When a signal is raised and the signal handler code is called, the signal number is passed as an integer argument to the signal handling code.

Usage
set_signal_handler(signal, closure | call_reference)
Example
set_signal_handler(SIGINT, \signal_handler());
Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.364. Arguments and Return Values for set_signal_handler()

Argument Type

Return Type

Description

Integer, closure | Call Reference

n/a

The signal number to process and reference to the code to execute when the signal is raised.


This function does not throw any exceptions.

3.12.45. sort()

Synopsis

Performs an unstable sort in ascending order and returns the new list (for a stable version see sortStable()). Without a callback, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.

Usage
sort(list, [callback])
Example
$list = sort($complex_list, \callback());

Table 3.365. Arguments and Return Values for sort()

Argument Type

Return Type

Description

List, [closure | Call Reference]

List

Sorts the list passed in ascending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used.


This function does not throw any exceptions.

3.12.46. sortDescending()

Synopsis

Performs an unstable sort in descending order and returns the new list (for a stable version see sortDescendingStable()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.

Usage
sortDescending(list, [callback])
Example
$list = sortDescending($complex_list, \callback());

Table 3.366. Arguments and Return Values for sortDescending()

Argument Type

Return Type

Description

List, [closure | Call Reference]

List

Sorts the list passed in descending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used.


This function does not throw any exceptions.

3.12.47. sortDescendingStable()

Synopsis

Performs a stable sort in descending order and returns the new list (for an unstable version see sortDescending()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.

Usage
sortDescendingStable(list, [callback])
Example
$list = sortDescendingStable($complex_list, \callback());

Table 3.367. Arguments and Return Values for sortDescendingStable()

Argument Type

Return Type

Description

List, [closure | Call Reference]

List

Sorts the list passed in descending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used.


This function does not throw any exceptions.

3.12.48. sortStable()

Synopsis

Performs a stable sort in ascending order and returns the new list (for an unstable version see sort()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.

Usage
sortStable(list, [callback])
Example
$list = sortStable($complex_list, \callback());

Table 3.368. Arguments and Return Values for sortStable()

Argument Type

Return Type

Description

List, [closure | Call Reference]

List

Sorts the list passed in ascending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used.


This function does not throw any exceptions.

3.12.49. srand()

Synopsis

Seeds the random number generator with the integer passed (uses the C library function srandom()).

Usage
srand(integer)
Example
srand(now()); # seeds with current time

Table 3.369. Arguments and Return Values for srand()

Argument Type

Return Type

Description

Integer

n/a

Seeds the random number generator with the integer passed. See rand() for a function to get a random number.


This function does not throw any exceptions.

3.12.50. strtoint()

Synopsis

Returns an integer corresponding to the string passed with the possibility to specify the base (default base 10).

Usage
strtoint(string, [base])
Example
$int = strtoint("41", 8);

Table 3.370. Arguments and Return Values for strtoint()

Argument Type

Return Type

Description

String

Integer

Returns an integer corresponding to the string value in the base specified. If no base is passed, then base 10 is assumed.


This function does not throw any exceptions.