Qore v0.8.3

Calls to static class methods are made by giving the class name followed by two colons and then the method name. The method name must be implemented and accessible (i.e. not private and accessed outside the class) somewhere within the class hierarchy and must be static or a parse exception will occur.

class_name::method_name( [argument_expressions...] )

class_name

The name of the class implementing the static method.

method_name

The name of the static method to call.

[argument_expressions...]

Expressions passing arguments to the static method.

TimeZone::setRegion("Europe/Prague");

The find expression can be used to quickly find data in a hash of lists (such as a query result set returned by the Datasource::select() or SQLStatement::fetchColumns() methods). The find expression will loop through a data structure, and for each element in the structure where the where expression is True, it will evaluate and return a result expression. If the where expression only is true for one element in the list, it will return the result of evaluating the result expression directly, otherwise if the where expression is true more than once, then a list of the results of evaluting the result expression for each element is returned. In each expression in the find expression, column names can be referred to by preceding the name with a '%" character (as with context statements).

find result_expression in data_expression where ( where_expression )

result_expression

This expression will be evaluated and returned when the where_expression evaluates to True.

data_expression

This expression must evaluate to a hash of lists, so that the internal context can be set up for the find loop.

where_expression

This expression will be evaluated for each row in the data_expression. Each time it evaluates to True, the result_expression will be evaulated and used for the return value for the find expression.

$rlist = find %name, %id in $data where (%name =~ /Smith/);

References to functions or object methods are called call references. A call reference can be used like a function pointer; a call reference is a Qore data type that can be returned by functions or methods or assigned to variables.

Note that it is currently not legal to assign a call reference to a constant. This restriction may be lifted in a future version of Qore.

Function Call References

Call references to functions are resolved at parse time; if the function does not exist a parse exception will be thrown.

Object Method Call References

Call references to object methods are executed and resolved at run time; if the object expression does not evaluate to an object at run-time, an OBJECT-METHOD-REFERENCE-ERROR exception will be thrown. If the method does not exist, a METHOD-DOES-NOT-EXIST run-time exception will be thrown.

When called, a call reference to an object method will be executed in the context of the object originally referenced.

Object method call references do not prolong the lifetime of an object; if the object is deleted (for example, by going out of scope), then if called the call reference will cause a OBJECT-ALREADY-DELETED exception to be thrown.

\function_name();
\object_expression.method_name();

\function_name()

This form gives a function call references. The function name can be any valid user or builtin function name. Note the backslash at the beginning and the empty pair of parentheses at the end; these are required when specifying a call reference.

\object_expression.method_name()

This form gives an object method call reference. The object expression can be any valid Qore expression that evaluates to an object. The method_name must be an unquoted string (see examples below) and must represent a valid method name of the object's class.

my code $call_ref = \func_name();
$call_ref = \$object.method_name();

A closure is an anonymous function used as a value. Closures can be returned from functions or methods, assigned to variables, or passed as arguments to other functions.

Note that it is not legal to assign a closure to a constant.

[return_type] sub ([[type] variable1, ...]) { code... }

or the alternate syntax with the returns keyword after the parameters:

sub ([[type] variable1, ...]) [returns type] { code... }

Closures encapsulate the state and value of local variables of the outer code block referenced from within the closure when the closure is created. Whenever local variables are bound within a closure, these variables are subject to concurrent thread access protection (locking) just as with global variables, in order to allow closures to be used in any context without restriction and to preseve thread-safety regarding bound local variables.

Note that returning a closure from within an object method encapsulates the state of the object as well (it's legal to refer to $self and $.<variable> from within closures created from objects) and additionally prolongs the scope of the object for the lifetime of the closure.

Note that parameter and return types are required when the PO_REQUIRE_TYPES or PO_REQUIRE_PROTOTYPES parse options are set.

# if $b is a local variable in the function where the closure is created
# then $b will be bound to the closure when the closure is created
my code $closure = int sub (int $a) { return $a + $b; };

Implicit arguments are arguments not captured by parameter variables as well as automatic arguments in list-processing operator expressions. A special syntax to reference these arguments is documented here.

$<integer> # for a single implicit argument
$$         # for the entire implicit argument list

Implicit arguments can be directly referenced using the dollar sign ($) and either a number from 1 onwards (giving the position in the argument list, where 1 is the first element) or a double dollar sign ($$) giving the entire implicit argument list.

For unassigned arguments to functions or methods, this syntax supplements the automatic $argv variable holding all function arguments not assigned to parameter variables.

This syntax is particularly useful when writing expressions for the map, map, foldr, and select operators, where implicit argument references are the only way the operator expressions can reference the current list values that are populated as implicit arguments as the operators traverse the list.

# extract a list of even numbers from a list
my $l = select $list, !($1 % 2);

The current list index position when implicitly iterating through lists can be referenced using the implicit index reference characters: $#.

$#

The implicit index reference characters ($#) can be used whenever a list is iterated implicitly, such as with foreach statements and the map, foldl, foldr, and select operators.

# create a list of indexes with negative values
my list $l = map $#, $list, ($1 < 0);

Executes the shell command in a separate process and returns the stdout as a string. To perform the same action using a Qore expression, see the backquote() function.

`shell_command`

string

$dirlisting = `ls -l`

Retrieves the value of hash key or object member by evaulating an expression.

container_expression{expression}

any

printf("%s\n", $hash{getName()});

Retrieves the value of a hash key or object member using a literal identifier or an expression.

container_expression.identifier
container_expression.method_identifier([arguments...])
container_expression.expression

any

printf("%s\n", $hash.name);

$obj.method("argument");

Retrieves the value of a list element, the given character of a string, or the integer value of a byte for a binary object. If the index value is not valid for the argument, NOTHING is returned. Note that this operator only works as a list dereferencing operator in lvalue expressions; you cannot assign a character or a byte value to strings or binaries using this operator.

list_expression[expression]
string_expression[expression]
binary_expression[expression]

any

printf("%s\n", $list[2]);
printf("%s\n", $str[2]);
printf("0x%x\n", $binary[2]);

increments an lvalue and returns the incremented value.

++lvalue

int

++$i;

increments an lvalue and returns the value before the increment.

lvalue++

any

$i++;

decrements an lvalue and returns the decremented value.

--lvalue

int

--$i;

decrements an lvalue and returns the value before the decrement.

lvalue--

any

$i--;

Creates an instance of a class by running the class' constructor on the new class (if any exists) and returns the new object.

Note that it is normally better to declare an object with its type and use the abbreviated form to construct the object as follows:

my Mutex $m();

This provides type information to the parser which allows more errors to be caught at parse time (instead of at run time), and furthermore allows Qore improve performance by performing more work once at parse time rather than for every time the object is accessed at run time (for example, method and variant resolution).

new class_identifier(constructor_arguments ...)

specific class, an object of the class given

$obj = new Qore::Mutex();

Start a background thread and return the TID (thread ID).

background expression

int

background startThread();

The delete operator deletes the contents of an lvalue. If the delete operator is called on an object, the object will be destroyed unconditionally. The delete operator does not return any value.

When called on a hash key, the key is removed from the hash entirely; when called on a list element, the element is assigned NOTHING (i.e. the list size does not change).

The delete operator will delete multiple keys from a hash (i.e. delete a slice from a hash) when called on a hash dereferenced by a list of strings, giving the keys to delete (see example below).

In the case the delete operator operates on an object, any exception can be thrown that is thrown by the class' destructor.

For a similar operator that returns the value that is removed from the data structure, and does not delete objects, see the remove operator.

delete lvalue_expression

Does not return any value

# delete a single key from a hash
delete $value;

# delete multiple values from a hash
delete $h.("a", "b", "c");

The remove operator removes a value from a data structure, or, in the case the operand of the remove operator is a simple value, the value itself is removed from the variable and returned. The remove operator returns the value removed from the lvalue.

When called on a hash key, the key is removed from the hash entirely, and the value returned is the value of the key removed from the hash; when called on a list element, the element is assigned NOTHING. (i.e. the list size does not change).

The remove operator will remove and return a slice from a hash when called on a hash dereferenced by a list of strings, giving the keys to remove (see example below).

The remove operator does not call destructors when operating on objects, but if removing an object from an lvalue or from a data structure within the lvalue causes the object to go out of scope, it will be destroyed, and then its destructor could throw an exception.

For a similar operator that deletes the value that is removed from the data structure, see the delete operator.

remove lvalue_expression

any

# remove a single value from a hash
my any $var = remove $hash.value;

# remove a slice from a hash
my hash $nh = remove $h.("a", "b", "c");

The cast<>() operator provides a way to tell the parser that the type of object is not actually the declared type but rather a subclass as given between the angle brackets.

cast<class_name_or_path>(expression)

specific class, the class given

cast<SubClass>($obj).method();

Reverses the logical sense of an expression (True becomes False and False becomes True).

!expression

bool

if (!exists $error_code)
    do_something();

The value of each bit in an integer is reversed (0 becomes 1, 1 becomes 0).

~expression

int

$a = ~$b;

Changes the sign of numeric values.

-expression

int or float

$a = -$b;

Removes the first element from a list and returns that element.

shift lvalue

any

$a = shift $ARGV;

Removes the last element from a list and returns that element.

pop lvalue

any

$a = pop $list;

Removes the end-of-line marker(s) ('\n' or '\r\n') from a string, or each string element in a list, or each hash key value in a hash (if the value is a string) and returns the number of characters removed.

To perform this operation on a non-lvalue expression, see the chomp() function.

chomp lvalue

int

chomp $str;

Removes whitespace characters from the beginning and end of a string, or each string element in a list, or each hash key value in a hash (if the value is a string) and returns the value processed (string, list, or hash).

To perform this operation on a non-lvalue expression, see the trim() function.

The following whitespace characters are removed from the beginning and end of strings: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character).

trim lvalue

string, list, or hash

trim $str;

Executes (or maps) an expression on a list and returns the result. An optional select expression can be given to filter elements out from the result list.

If the second argument is not a list, then map_expression is executed on the single value and the result is returned, and any select expression is ignored.

any

map map_expression, list, [select_expression]

# returns (2, 4, 6)
map $1 * 2, (1, 2, 3);

Folds an operation on a list from left to right and returns the result. The result of each individual operation is used as the first argument in the foldl expression for the next element in the list. The first operation of the fold is made by executing the fold expression on the first and second elements of the list, from this point onwards, the result of each successive operation is used as the first argument for the next operation, the second argument being the next element in the list.

If the list expression does not evaluate to a list, then the evaluated argument is returned immediately with no processing by the fold expression.

foldl expression, list

any

# returns 5
foldl $1 - $2, (10, 4, 1);

Folds an operation on a list from right to left and returns the result. The result of each individual operation is used as the first argument in the foldr expression for the next element in the list in reverse order. The first operation of the right fold is made by executing the fold expression on the last and penultimate elements of the list, from this point onwards, the result of each successive operation is used as the first argument for the next operation, the second argument being the next element in the list in reverse order.

If the list expression does not evaluate to a list, then the evaluated argument is returned immediately with no processing by the fold expression.

foldr expression, list

any

# returns -13
foldr $1 - $2, (10, 4, 1);

Selects elements from a list that meet the given criteria and returns the new list.

If the list expression does not evaluate to a list, then the select expression is evaluated using the value of the list expression as an argument, if it evalutes to true, then the value is returned, otherwise, no value is returned.

select list, expression

any

# returns (2, 4, 6)
select (1, 2, 3, 4, 5, 6), !($1 % 2);

Returns the number of elements in a list, the number of keys in a hash, the number of characters (not bytes) in a string, or the number of bytes in a binary object.

elements expression

int

$size = elements $list;

Returns a list representing the keys in a hash.

keys hash_expression

list or NOTHING

foreach my $key in (keys $hash)
    printf("%s = %s\n", $key, $hash.$key);

Multiplies two arguments.

expression1 * expression2

int or float

$value = $x * $y

Divides a number by another.

expression1 / expression2

int or float

$value = $x / $y;

Gives the integer remainder after division of one number by another.

expression1 % expression2

int

$mod = $x % $y;

Numeric addition, list, string, binary, and hash concatenation operator.

expression1 + expression2

int, float, date, list, string, binary, or hash

$a = 1 + 2;

$string = "hello" + "-there";

$list = (1, 2) + ("three", "four", "five");

$hash = ( "key1" : 1, "key2" : 2) + ( "key3" : "three", "key4": "four");

$bin = $bin1 + $bin2;

With float or integer arguments, subtracts one number from another.

With date arguments, subtracts one date from another; if both date arguments are absolute dates, the result is a relative date (duration) giving the time between them; if the first date argument is an absolute date and the second is a relative date (duration), then the result is an absolute date. If both date arguments are relative dates, then the result is a relative date. If the first argument is a relative date and the second date is an absolute date, the result is an absolute date as if the operands were reversed.

However, if the left-hand side is a hash, and the right-hand side is a string, then the hash key represented by the string will be removed from the hash. If the left-hand side is a hash and the right-hand side is a list, then each element in the list will be converted to a string and any hash key with that name will be deleted from the hash.

expression1 - expression2

int, float, date, or hash

$num = $x - $y;

$date = 2010-05-13 - P3MT14H10M;

$hash = $hash - "key";

$hash = $hash - ("key1", "key2", "key3");

Shifts bits in an integer towards zero (divides an integer by a power of 2)

expression1 >> expression2

int

$a = $x >> $y;

Shifts bits in an integer towards infinity (multiplies an integer by a power of 2)

expression1 << expression2

int

$a = $x << $y;

Tests if an expression is an instance of a class or not.

expression instanceof class_specification

bool

if ($obj instanceof Qore::Mutex)
    print("object is Mutex\n");

Tests if an expression represents a value or not.

exists expression

bool

if (exists $a)
    printf("a = $n\n", $a);

Tests if a value is less than another; types are converted if necessary (ex: ("1" < 2) is True).

expression1 < expression2

bool

if ($x < $y)
    printf("%n is less than %n\n", $x, $y);

Tests if a value is greater than another; types are converted if necessary (ex: ("2" > 1) is True).

expression1 > expression2

bool

if ($x > $y)
    printf("%n is less than %n\n", $x, $y);

Tests if a value is equal to another; types are converted if necessary (ex: ("1" == 1) is True). For absolute equals, where types must also be equal to return true, see the Absolute Equals Operator (===).

expression1 == expression2

bool

if ($x == $y)
    printf("%n is equal to %n\n", $x, $y);

Tests if a value is not equal to another; types are converted if necessary (ex: ("1" != 1) is False).

expression1 != expression2

bool

if ($x != $y)
    printf("%n is not equal to %n\n", $x, $y);

Tests if a value is less than or equals to another value; types are converted if necessary (ex: ("1" <= 2) is True).

expression1 <= expression2

bool

if ($x <= $y)
    printf("%n is less than or equal to %n\n", $x, $y);

Tests if a value is greater than or equals to another value; types are converted if necessary (ex: ("2" >= 1) is True).

expression1 >= expression2

bool

if ($x >= $y)
    printf("%n is greater than or equal to %n\n", $x, $y);

Tests if the left-hand value is less than, equal, or greater than the right-hand value; types are converted if necessary (ex: ("1" <=> 2) returns -1).

expression1 <=> expression2

int

switch ($x <=> $y) {
    case -1: 
        print("$x is less than $y\n");
        break;

    case 0: 
        print("$x is equal to $y\n");
        break;

    case 1: 
        print("$x is greater than $y\n");
        break;
}

Checks two values for equality without doing any data type conversions; if the types do not match, then the result is False.

expression1 === expression2

bool

if ($x === $y)
    printf("%n is equal to %n and has the same data type as well\n", $x, $y);