2.12. Operators

The following table lists all Qore operators in order of precedence, starting with the highest precedence. The lower the precedence number, the higher the precedence, therefore the operators with precedence level 1 ("{}", "[]", ".") have the highest precedence of all Qore operators. The precedence levels in Qore are roughly equal to the precedence levels of C language operators (however note the important difference with the , operator as noted below). To explicitly specify the precedence for expression evaluation, use parentheses ().

Table 2.10. Operators

Operator

Prec.

Description

Example

``

1

backquote/backtick operator

`ls -l`

{}

1

hash element or object member expression dereference operator

$hash{"na" + "me"}

.

1

hash element or object member literal dereference operator

$hash.name

$obj.method()

[]

1

list element, string, and binary dereference operator

$list[1]

++

2

pre-increment operator, post-increment operator

++$a, $a++

--

2

pre-decrement operator, post-decrement operator

--$a, $a--

new

3

class instantiation/new object operator

new Socket()

background

3

background/thread creation operator

background mainThread()

!

4

logical negation operator

if (!($a > 10)) ...

~

5

binary not/bit inversion operator

$var = ~$var

- (unary minus)

6

unary minus operator

$var = -$var

shift

7

shift list element operator

shift $list

pop

7

pop list element operator

pop $list

chomp

7

chomp end-of-line character operator

chomp $string

trim

7

trim characters operator

trim $string

map

7

map operator

map $closure($1), $list

foldl

7

fold left to right operator

foldl $closure($1 - $2), $list

foldr

7

fold right to left operator

foldr $closure($1 - $2), $list

select

7

select elements from list operator

select $list, $1 > 1

elements

8

number of elements operator (list, hash, string, binary)

elements $list

keys

8

hash key list operator

keys $hash

*

9

arithmetic multiplication operator

$var = $a * 10

/

9

arithmetic division operator

$var = $a / 10

%

10

arithmetic modula operator

$var = $a % 10

+

11

plus operator: string, binary, list, and hash concatenation, integer and float addition

$a + 10

"hello" + "there"

$list + "new value"

$hash + ( "newkey" : 100 )

-

11

minus operator (arithmetic subtraction, hash key removal)

$a - 10

>>

12

bitwise shift right operator

0xff00 >> 8

<<

12

bitwise shift left operator

0xff00 << 8

exists

13

exists value operator

exists $var

instanceof

13

instanceof class operator

instanceof Qore::Mutex

<

14

Logical less than operator

$a < 10

>

14

Logical greater than operator

$a > 10

==

14

Logical equality operator

$a == 10

!=

14

logical inequality operator

$a != 10

<=

14

Logical less then or equals operator

$a <= 10

>=

14

logical greater than or equals operator

$a >= 10

<=>

14

logical comparison operator

$a <=> $b

===

14

absolute logical equality operator

$a === 10

!==

14

absolute logical inequality operator

$a !== 10

=~ //

14

regular expression match operator

$a =~ /text/

!~ //

14

regular expression no match operator

$a !~ /text/

=~ s///

14

regular expression substitution operator

$a =~ s/text/text/

=~ x//

14

regular expression pattern extraction operator

$a =~ x/(\w+):(\w+)/

=~ tr

14

transliteration operator

$a =~ tr/src_chars/targ_chars/

&

15

bitwise AND operator

$a & 0xff

|

15

bitwise OR operator

$a | 0xff

^

15

bitwise XOR operator

$a ^ 0xff

&&

16

logical AND operator

($a = 1) && ($b < 10)

||

16

logical OR operator

($a = 1) || ($b < 10)

? :

17

conditional operator

$a == 2 ? "yes" : "no"

,

18

comma operator

1, 2, 3, 4, 5

unshift

19

unshift list element operator

unshift $list, $val

push

19

push list element operator

push $list, $val

splice

19

splice list or string operator

splice $list, 2, 2, (1, 2, 3)

=

20

assignment operator

$var = 1

+=

21

plus-equals (add-to) operator

$var += 5

-=

21

minus-equals (subtract-from) operator

$var -= 5

&=

21

and-equals operator

$var &= 0x2000

|=

21

or-equals operator

$var |= 0x2000

%=

21

modula-equals operator

$var %= 100

*=

21

multiply-equals operator

$var *= 10

/=

21

divide-equals operator

$var /= 10

^=

21

xor-equals operator

$var ^= 0x2000

<<=

21

shift-left-equals operator

$var <<= 0x2000

>>=

21

shift-right-equals operator

$var >>= 0x2000

Note

All Qore operators perform thread-atomic actions with respect to the immediate arguments of the operator. If the operators are used in a complex expression, the entire expression is not thread-atomic unless explicit user-level locking is used. For example: $a += 5 is a thread-atomic action, but $a += $b-- is not atomic, but rather made up of two atomic actions.

Note

When an operator taking more than one argument is used with arguments of different data types, Qore automatically converts one or both data types to a data type supported by the operator in order to evaluate the result, according to the precedence lists in the following section. That is; when an operator operates on mixed types, the types listed first in the following sections have precedence over types listed farther down in the lists. The result type will always be equal to the final operation type after any conversions due to type precedence per operator. If no type of either argument matches a supported data type for the operator, both types will be converted to the highest precedence data type for the operator and then the operator will evaluate the result. For explicit type conversion, please see the boolean(), string(), date(), int(), float(), etc functions.

Note

The Qore comma ',' operator has a higher precendece than the '=' operator, meaning that a statement like $a = 1, 2, 3; is possible without parentheses. However, it means that a statment like $a = func(1, 2, $b = 3, 4); will probably not do what you want (it uses $b as the third argument which is assigned to the list (3, 4)); you must write $a = func(1, 2, ($b = 3), 4); to pass 4 arguments to the function func.

2.12.1. Backquote Operator (``)

Synopsis

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.

Syntax
`shell_command`
Example
$dirlisting = `ls -l`

Argument

Processing

shell_command

The shell command will be executed and the stdout is returned as a string.

Table 2.11. Exceptions Thrown by ``

err

desc

BACKQUOTE-ERROR

An error occurred in fork() or creating the output pipe.


2.12.2. Hash Element or Object Member Expression Dereference Operator ({})

Synopsis

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

Syntax
container_expression{expression}
Example
printf("%s\n", $hash{getName()});

Table 2.12. Arguments Processed by {}

Argument

Processing

container_expression

This expression must evaluate to a hash or an object. If not, then the operator returns no value.

expression = list

If the expression evaluates to a list, then a slice of the hash or object is returned as a hash containing keys given in the list that are present in the hash or object. If the key as given in the list (converted to a string if necessary) is not present in the hash or object, then it is also not present in the hash returned.

expression != list

This expression is evaluated and converted to a string if necessary. The value of the hash key corresponding to this string will be returned. If the key or member does not exist, then no value is returned.


Table 2.13. Exceptions Thrown by {}

err

desc

PRIVATE-MEMBER

Attempt to access a private member outside the class.


2.12.3. Hash Element or Object Member Literal Dereference Operator (.)

Synopsis

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

Syntax
container_expression.identifier
container_expression.method_identifier([arguments...])
container_expression.expression
Example
printf("%s\n", $hash.name);
$obj.method("argument");

Table 2.14. Arguments Processed by .

Argument

Processing

container_expression

This expression must evaluate to a hash or an object. If not, then the operator returns no value.

identifier

The value of the hash key or object member corresponding to this identifier will be returned. If no such key exists, then no value is returned. In order to use hash keys that are not valid Qore identifiers, please use the {} operator. If the member is a private member and access is made outside the class, a run-time exception will be thrown.

method_ídentifier

The container expression must evaluate to an object, or a run-time exception is thrown. If the method does not exist in the class a run-time exception is thrown. Otherwise the method is called with any optional arguments given.

expression = list

If the expression evaluates to a list, then a slice of the hash or object is returned as a hash containing keys given in the list that are present in the hash or object. If the key as given in the list (converted to a string if necessary) is not present in the hash or object, then it is also not present in the hash returned.

expression != list

This expression is evaluated and converted to a string if necessary. The value of the hash key corresponding to this string will be returned. If the key or member does not exist, then no value is returned.


Table 2.15. Exceptions Thrown by .

err

desc

PRIVATE-MEMBER

Attempt to access a private member outside the class.

METHOD-DOES-NOT-EXIST

Attempt to access a method not defined for this class.

METHOD-IS-PRIVATE

Attempt to access a private method from outside the class.

BASE-CLASS-IS-PRIVATE

Attempt to access a method of a privately-inherited base class from outside the class.

OBJECT-METHOD-EVAL-ON-NON-OBJECT

Attempt to execute a method on a non-object.


2.12.4. List, String, and Binary Dereference Operator ([])

Synopsis

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.

Syntax
list_expression[expression]
string_expression[expression]
binary_expression[expression]
Example
printf("%s\n", $list[2]);
printf("%s\n", $str[2]);
printf("0x%x\n", $binary[2]);

Table 2.16. Arguments Processed By []

Argument

Processing

list_expression

If the expression evaluates to a list, then the offset_expression will be used to return the given element from the list.

string_expression

If the expression evaluates to a string, then the offset_expression will be used to return the given character from the list; note that multi-byte characters with UTF-8 are properly respected with this operator.

binary_expression

If the expression evaluates to a binary, then the offset_expression will be used to return the integer value of the byte given from the binary object.

expression

The expression is evaluated and converted to an integer if necessary. Then the value of the list element given is returned (elements start at position 0).


This operator does not throw any exceptions; if the first expression does not evaluate to either a list, string, or binary, then no value is returned.

2.12.5. Integer Pre-Increment Operator (++)

Synopsis

increments an lvalue and returns the incremented value.

Syntax
++lvalue
Example
++$i;

Table 2.17. Arguments Processed By Pre-Increment ++

Argument

Processing

Integer

First converts the value of lvalue to an integer if necessary, then increments the value and returns the result.


This operator does not throw any exceptions.

2.12.6. Integer Post-Increment Operator (++)

Synopsis

increments an lvalue and returns the value before the increment.

Syntax
lvalue++
Example
$i++;

Table 2.18. Arguments Processed By Post-Increment ++

Argument

Processing

Integer

First converts the value of lvalue to an integer if necessary, then saves this value as the result, then increments the lvalue, then returns the saved original value of lvalue (after conversion to an integer if necessary)


This operator does not throw any exceptions.

2.12.7. Integer Pre-Decrement Operator (--)

Synopsis

decrements an lvalue and returns the decremented value.

Syntax
--lvalue
Example
--$i;

Table 2.19. Arguments Processed By Pre-Decrement --

Argument

Processing

Integer

First converts the value of lvalue to an integer if necessary, then decrements it and returns the result.


This operator does not throw any exceptions.

2.12.8. Integer Post-Decrement Operator (--)

Synopsis

decrements an lvalue and returns the value before the decrement.

Syntax
lvalue--
Example
$i--;

Table 2.20. Arguments Processed By Post-Decrement --

Argument

Processing

Integer

First converts the value of lvalue to an integer if necessary, then saves this value as the result, then decrements the lvalue, then returns the saved original value of lvalue (after conversion to an integer if necessary)


This operator does not throw any exceptions.

2.12.9. New Object Operator (new)

Synopsis

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

Syntax
new class_identifier(constructor_arguments ...)
Example
$obj = new Qore::Mutex();

Table 2.21. Arguments Processed By new

Argument

Processing

class_identifier

The class_identifier must be an existing class name; if so, the operator instantiates an object of this class, executes the constructor for the class (if any exists, along with any base class constructors, if applicable) on the new object, and returns the object (for constructor execution order in an inherited class, see Class Inheritance). If an exception is thrown in the constructor, the object is deleted and NOTHING is returned.


Table 2.22. Exceptions Thrown by new

err

desc

depends on class/constructor

See class documentation for possible exceptions.


2.12.10. Background Operator (background)

Synopsis

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

Syntax
background expression
Example
background startThread();

Table 2.23. Arguments Processed By background

Argument

Processing

expression

The expression given as an argument will be executed in a new thread. The TID of the new thread will be returned as the return value of the operator.


Note

Please note the following when using the background operator:

  • expressions that have no effect cannot be used with the background operator (a parse exception will be thrown)

  • it is illegal to make changes to a local variable anywhere in a background expression (a parse exception will be thrown)

  • local variables and find expressions are evaluated before the new thread is started and the result of the evaluation is used in the expression in the new thread.

  • it is not possible to pass local variables by reference anywhere in a background expression (a parse exception will be thrown)

Table 2.24. Exceptions Thrown by background

err

desc

THREAD-CREATION-FAILURE

If the thread table is full or if the operating system returns an error while starting the thread, this exception is thrown.


2.12.11. Logical Not Operator (!)

Synopsis

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

Syntax
!expression
Example
if (!exists $error_code)
    do_something();

Table 2.25. Arguments Processed By !

Argument

Processing

expression

The expression is evaluated and converted to Boolean, if necessary. Then the value is logically reversed (True becomes False, False becomes True)


This operator does not throw any exceptions.

2.12.12. Binary Not Operator (~)

Synopsis

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

Syntax
~expression
Example
$a = ~$b;

Table 2.26. Arguments Processed By ~

Argument

Processing

expression: Integer

Performs bitwise negation on its argument (ex: 666 & ~27 = 640)


This operator does not throw any exceptions.

2.12.13. Unary Minus Operator (-)

Synopsis

Changes the sign of numeric values.

Syntax
-expression
Example
$a = -$b;

Table 2.27. Arguments Processed By Unary Minus -

Argument

Processing

expression: Float

Gives the negative of its argument (ex: -(-1.1) = 1.1, -(1.1) = -1.1

expression: Integer

Gives the negative of its argument (ex: -(-1) = 1, -(1) = -1


This operator does not throw any exceptions.

2.12.14. Shift Operator (shift)

Synopsis

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

Syntax
shift lvalue
Example
$a = shift $ARGV;

Table 2.28. Arguments Processed By shift

Argument

Processing

lvalue: List

Returns the first element of the list, and the list is modified by having the first element removed from the list.


This operator does not throw any exceptions.

2.12.15. Pop Operator (pop)

Synopsis

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

Syntax
pop lvalue
Example
$a = pop $list;

Table 2.29. Arguments Processed By pop

Argument

Processing

lvalue: List

Returns the last element of the list, and the list is modified, having the last element removed from the list.


This operator does not throw any exceptions.

2.12.16. Chomp Operator (chomp)

Synopsis

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.

Syntax
chomp lvalue
Example
chomp $str;

Table 2.30. Arguments Processed By chomp

Argument

Processing

lvalue: String

Removes any EOL characters from a string and returns the number of characters removed.

lvalue: List

Removes any EOL characters from each string element of the list passed and returns the number of characters removed.

lvalue: Hash

Removes any EOL characters from each hash key's value (where the value is a string) and returns the number of characters removed.


This operator does not throw any exceptions.

2.12.17. Trim Operator (trim)

Synopsis

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

Syntax
trim lvalue
Example
trim $str;

Table 2.31. Arguments Processed By trim

Argument

Processing

lvalue: String

Removes whitespace characters from the beginning and end of a string and returns the value processed.

lvalue: List

Removes whitespace characters from the beginning and end of each string element of the list passed and returns the list.

lvalue: Hash

Removes whitespace characters from the beginning and end of each string value of the hash passed and returns the hash.


This operator does not throw any exceptions.

2.12.18. Map Operator (map)

Synopsis

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.

Syntax
map map_expression, list, [select_expression]
Example
# returns (2, 4, 6)
map $1 * 2, (1, 2, 3);

Table 2.32. Arguments Processed By map

Argument

Processing

map_expression

The expression to map on the list; the implicit argument $1 represents the current element being processed.

list: List

The list to process.

[select_expression]

An optional expression than can be used to filter out elements of the list before the map expression is applied; if this expression evaluates to False on an element, then the element will be skipped and the map expression will not be applied on that element.


This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).

2.12.19. Fold Left Operator (foldl)

Synopsis

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.

Syntax
foldl expression, list
Example
# returns 5
foldl $1 - $2, (10, 4, 1);

Table 2.33. Arguments Processed By foldl

Argument

Processing

expression

The expression to fold on the list; the implicit argument $1 represents the result of the last operation (or the first element in the list when beginning the fold), and $2 represents the next element of the list.

list: List

The list to process.


This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).

2.12.20. Fold Right Operator (foldr)

Synopsis

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.

Syntax
foldr expression, list
Example
# returns -13
foldr $1 - $2, (10, 4, 1);

Table 2.34. Arguments Processed By foldr

Argument

Processing

expression

The expression to fold on the list; the implicit argument $1 represents the result of the last operation (or the last element in the list when beginning the fold), and $2 represents the next element of the list in reverse order.

list: List

The list to process.


This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).

2.12.21. Select From List Operator (select)

Synopsis

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.

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

Table 2.35. Arguments Processed By select

Argument

Processing

list: List

The list to process.

expression

The expression will be evaluated on each element of the list, the implicit argument $1 represents current element of the list; only if the expression evaluates to True will the element appear in the result list.


This operator does not throw any exceptions (however note that exceptions could be thrown by the expression executed by this operator).

2.12.22. Elements Operator (elements)

Synopsis

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.

Syntax
elements expression
Example
$size = elements $list;

Table 2.36. Arguments Processed By keys

Argument

Processing

List

Returns the number of elements in the list.

Hash

Returns the number of keys in the hash.

String

Returns the number of characters in the string.

Binary

Returns the number of bytes in the binary object.


This operator does not throw any exceptions.

2.12.23. Keys Operator (keys)

Synopsis

Returns a list representing the keys in a hash.

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

Table 2.37. Arguments Processed By keys

Argument

Processing

hash_expression

Returns a list of strings giving the keys in hash_expression, which must evaluate to a hash. If not, then no value is returned.


This operator does not throw any exceptions.

2.12.24. Multiply Operator (*)

Synopsis

Multiplies two arguments.

Syntax
expression1 * expression2
Example
$value = $x * $y

Table 2.38. Argument Processing and Conversion Priorities for *

Argument

Processing

Float

Gives the result of multiplying its arguments.

Integer

Gives the result of multiplying its arguments.


This operator does not throw any exceptions.

2.12.25. Divide Operator (/)

Synopsis

Divides a number by another.

Syntax
expression1 / expression2
Example
$value = $x / $y;

Table 2.39. Argument Processing and Conversion Priorities for /

Argument

Processing

Float

Gives the result of dividing its arguments.

Integer

Gives the result of dividing its arguments.


This operator does not throw any exceptions.

2.12.26. Modula Operator (%)

Synopsis

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

Syntax
expression1 % expression2
Example
$mod = $x % $y;

Table 2.40. Arguments Processed By %

Argument

Processing

Integer

Gives expression1 modula expression2 (ex: 12 % 10 = 2). Arguments are converted to integers if necessary.


This operator does not throw any exceptions.

2.12.27. Plus (Addition and Concatentation) Operator (+)

Synopsis

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

Syntax
expression1 + expression2
Example
$a = 1 + 2;
$string = "hello" + "-there";
$list = (1, 2) + ("three", "four", "five");
$hash = ( "key1" : 1, "key2" : 2) + ( "key3" : "three", "key4": "four");
$bin = $bin1 + $bin2;

Table 2.41. Argument Processing and Conversion Priorities for +

Argument

Processing

List

Gives the result of concatenating its arguments, i.e. (1, 2) + (3, 4) = (1, 2, 3, 4)

String

Gives the result of concatenating its arguments.

Date

Gives the result of adding date/time values (see Date/Time Arithmetic)

Float

Gives the result of adding its arguments.

Integer

Gives the result of adding its arguments.

Hash

Gives the result of concatenating/merging its arguments. Any common keys will be overwritten by the values in the second hash (expression2)


This operator does not throw any exceptions.

2.12.28. Minus Operator (-)

Synopsis

With float or integer arguments, subtracts one number from another, 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.

Syntax
expression1 - expression2
Example
$num = $x - $y;
$hash = $hash - "key";

Table 2.42. Argument Processing and Conversion Priorities for -

Argument

Processing

Float

arithmetic subtraction: expression1 - expression2

Integer

arithmetic subtraction: expression1 - expression2

Hash - String

hash key deletion: expression1 - expression2


This operator does not throw any exceptions.

2.12.29. Shift Right Operator (>>)

Synopsis

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

Syntax
expression1 >> expression2
Example
$a = $x >> $y;

Table 2.43. Arguments Processed By >>

Argument

Processing

Integer

Gives the result of shifting expression1 right by expression2 bits. Arguments are converted to integers if necesssary.


This operator does not throw any exceptions.

2.12.30. Shift Left Operator (<<)

Synopsis

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

Syntax
expression1 << expression2
Example
$a = $x << $y;

Table 2.44. Arguments Processed By <<

Argument

Processing

Integer

Gives the result of shifting expression1 left by expression2 bits. Arguments are converted to integers if necessary.


This operator does not throw any exceptions.

2.12.31. Class Instance Operator (instanceof)

Synopsis

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

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

Table 2.45. Arguments Processed By instanceof

Argument

Processing

expression

If expression is an instance of the named class, then the operator returns True, otherwise returns False. The operator will return True if the class is a base class, also even if it is privately inherited.


This operator does not throw any exceptions.

2.12.32. Exists Operator (exists)

Synopsis

Tests if an expression represents a value or not.

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

Table 2.46. Arguments Processed By exists

Argument

Processing

expression

If expression evaluates to a value, then the operator returns True, otherwise returns False.


This operator does not throw any exceptions.

2.12.33. Less Than Operator (<)

Synopsis

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

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

Table 2.47. Argument Processing and Conversion Priorities for <

Argument

Processing

Float

If expression1 is numerically less than expression2, returns True, otherwise returns False

Integer

If expression1 is numerically less than expression2, returns True, otherwise returns False

String

If expression1 comes before expression2 in string sort order, returns True, otherwise returns False

Date

If expression1 is before expression2, returns True, otherwise returns False


This operator does not throw any exceptions.

2.12.34. Greater Than Operator (>)

Synopsis

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

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

Table 2.48. Argument Processing and Conversion Priorities for >

Argument

Processing

Float

If expression1 is numerically greater than expression2, returns True, otherwise returns False

Integer

If expression1 is numerically greater than expression2, returns True, otherwise returns False

String

If expression1 comes after expression2 in string sort order, returns True, otherwise returns False

Date

If expression1 is after expression2, returns True, otherwise returns False


This operator does not throw any exceptions.

2.12.35. Equals Operator (==)

Synopsis

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 (===).

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

Table 2.49. Argument Processing and Conversion Priorities for ==

Argument

Processing

String

If expression1 is equal to expression2, returns True, otherwise False

Float

If expression1 is equal to expression2, returns True, otherwise False

Integer

If expression1 is equal to expression2, returns True, otherwise False

Date

If expression1 is equal to expression2, returns True, otherwise False

List

If each element in the each list where order is relevant satisfies this operator, the operator returns True, otherwise it returns False

Hash

If each hash has the same keys and the value of each equal key in each hash satisfies this operator, the operator returns True, otherwise it returns False

Binary

If expression1's memory contents and size are equal to expression2's, then returns True, otherwise False

Object

If expression1 is a reference to the same object as expression2, then returns True, otherwise False

NULL

If both expressions are NULL, returns True, otherwise returns False

NOTHING

If neither expression has a value, returns True, otherwise returns False


This operator does not throw any exceptions.

2.12.36. Not Equals Operator (!=)

Synopsis

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

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

Table 2.50. Argument Processing and Conversion Priorities for !=

Argument

Processing

String

If expression1 is not equal to expression2, returns True, otherwise returns False

Float

If expression1 is not equal to expression2, returns True, otherwise returns False

Integer

If expression1 is not equal to expression2, returns True, otherwise returns False

Date

If expression1 is not equal to expression2, returns True, otherwise returns False

List

If any element in the each list compared where order is relevant satisfies this operator, the operator returns True, otherwise it returns False

Hash

If the hashes have different key sets, or the values of any equal key in each hash satisfies this operator, the operator returns True, otherwise it returns False

Binary

If either expression1's memory contents and size are not equal to expression2's, returns True, otherwise False.

Object

If expression1 is not a reference to the same object as expression2, then returns True, otherwise False.

NULL

If one expression is NULL and the other not, returns True, otherwise False.

NOTHING

If one of the expressions has a value, returns True, otherwise False.


This operator does not throw any exceptions.

2.12.37. Less Than Or Equals Operator (<=)

Synopsis

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

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

Table 2.51. Argument Processing and Conversion Priorities for <=

Argument

Processing

Float

If expression1 is numerically less than or equal to expression2, returns True, otherwise returns False

Integer

If expression1 is numerically less than or equal to expression2, returns True, otherwise returns False

String

If expression1 comes before in string sort order or is the same as expression2, returns True, otherwise returns False

Date

If expression1 is before or is the same exact date and time as expression2, returns True, otherwise returns False


This operator does not throw any exceptions.

2.12.38. Greater Than Or Equals Operator (>=)

Synopsis

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

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

Table 2.52. Argument Processing and Conversion Priorities for >=

Argument

Processing

Float

If expression1 is numerically greater than or equal to expression2, returns True, otherwise returns False

Integer

If expression1 is numerically greater than or equal to expression2, returns True, otherwise returns False

String

If expression1 comes after in string sort order or is the same as expression2, returns True, otherwise returns False

Date

If expression1 is after or is the same exact date and time as expression2, returns True, otherwise returns False


This operator does not throw any exceptions.

2.12.39. Comparison (<=>) Operator

Synopsis

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

Syntax
expression1 <=> expression2
Example
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;
}

Table 2.53. Argument Processing and Conversion Priorities for <=>

Argument

Processing

String

If expression1 comes after in string sort order as expression2, returns 1, otherwise if they are equal, returns 0, otherwise if expression1 comes before expression2, returns -1

Float

If expression1 is numerically greater than expression2, returns 1, otherwise if they are equal returns 0, otherwise returns -1

Integer

If expression1 is numerically greater than expression2, returns 1, otherwise if they are equal returns 0, otherwise returns -1

Date

If expression1 is after expression2, returns 1, otherwise if they are equal returns 0, otherwise returns -1


This operator does not throw any exceptions.

2.12.40. Absolute Equals Operator (===)

Synopsis

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

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

Table 2.54. Arguments Processed By ===

Argument

Processing

All

This operator returns True only if the types and values of both sides of the operator are exactly equal, otherwise returns False. No type conversions are done.


This operator does not throw any exceptions.

2.12.41. Absolute Not Equals Operator (!==)

Synopsis

Checks two values for inequality without doing any data type conversions. If the data types do not match, then returns True.

Syntax

expression1 !== expression2

Example
if ($x !== $y)
    printf("%n is not equal to %n and may not have the data type as well\n", $x, $y);

Table 2.55. Arguments Processed By !==

Argument

Processing

All

This operator returns True if either the types or the values of the arguments are different, otherwise it retuns False. No type conversions are done.


This operator does not throw any exceptions.

2.12.42. Regular Expression Match Operator (=~)

Synopsis

Checks for a regular expression match; returns True if the expression matches the string, False if not. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.

Syntax
expression =~ [m]/regex/[isxm]
Example
if ($str =~ /hello/)
    printf("%s contains 'hello'\n", $str);

Table 2.56. Arguments Processed By =~

Argument

Processing

String

This operator returns True if the regular expression in regex matches the string in expression.


This operator does not throw any exceptions.

2.12.43. Regular Expression No Match Operator (!~)

Synopsis

Checks for a regular expression non match; returns True if the expression does not match the string, False if it does. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.

Syntax
expression !~ [m]/regex/[isxm]
Example
if ($str !~ /hello/)
    printf("%s does not contain 'hello'\n", $str);

Table 2.57. Arguments Processed By !~

Argument

Processing

String

This operator returns True if the regular expression in regex does not match the string in expression.


This operator does not throw any exceptions.

2.12.44. Regular Expression Substitution Operator

Synopsis

Looks for a regular expression match in a string, and, if found, substitutes the matched string with a new string. Subpattern backreferences are supported in the target string, $1=first subpattern, $2=second subpattern, etc... See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.

Syntax
lvalue =~ s/regex_pattern/target_string/[isxmg]
Example
$str =~ s/hello/goodbye/i;
$str =~ s/(\w+) +(\w+)/$2, $1/;

Table 2.58. Arguments Processed By =~ s///

Argument

Processing

String

This operator substitutes text in the lvalue string if the regular expression matches. Subpattern backreferences are supported in the target string, $1=first subpattern, $2=second subpattern, etc..


This operator does not throw any exceptions.

2.12.45. Regular Expression Pattern Extraction Operator

Synopsis

Matches regular expression patterns (enclosed in parentheses) in a string and returns a list giving the text matched for each pattern. If the regular expression does not match, then no value (NOTHING) is returned. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.

Syntax
string =~ x/regex_with_patterns/[isxm]
Example
$list =~ x/(\w+):(\w+)/;
$list =~ x/(.*)\.(.*)/;

Table 2.59. Arguments Processed By =~ x//

Argument

Processing

String

This operator extracts strings from the string based on patterns enclosed in parentheses in the regular expression.


This operator does not throw any exceptions.

2.12.46. Transliteration Operator

Synopsis

Makes character substitutions in an lvalue; character ranges can also be used.

Syntax
lvalue =~ tr/source_chars/target_chars/
Example
$str =~ tr/a-z/A-Z/;

Table 2.60. Arguments Processed By =~ tr//

Argument

Processing

String

This operator substitutes characters in the lvalue string. Note that if there are more characters in the source string than in the target string, then the last character in the target string will be used for any source matches where the source character position is greater than the target string.


This operator does not throw any exceptions.

2.12.47. Binary And Operator (&)

Synopsis

Performs a bitwise (binary) AND operation on two integers.

Syntax
expression1 & expression2
Example
$a = $x & $y;

Table 2.61. Arguments Processed By &

Argument

Processing

Integer

Gives the result of the binary (bitwise) AND operation between expression1 and expression2 (ex: 0xffb2 & 0xa1 = 0xa1)


This operator does not throw any exceptions.

2.12.48. Binary Or Operator (|)

Synopsis

Performs a bitwise (binary) OR operation on two integers.

Syntax
expression1 | expression2
Example
$a = $x | $y;

Table 2.62. Arguments Processed By |

Argument

Processing

Integer

Gives the result of the binary (bitwise) OR operation between expression1 and expression2 (ex: 0xb001 | 0xfea = 0xbfeb)


This operator does not throw any exceptions.

2.12.49. Binary Xor Operator (^)

Synopsis

Performs a bitwise (binary) XOR operation on two integers.

Syntax
expression1 ^ expression2
Example
$a = $x ^ $y;

Table 2.63. Arguments Processed By ^

Argument

Processing

Integer

Gives the result of the binary (bitwise) EXCLUSIVE OR operation between expression1 and expression2 (ex: 0xaef1 & 0xfb32 = 0x55c3)


This operator does not throw any exceptions.

2.12.50. Logical And Operator (&&)

Synopsis

Checks to see if two expressions are True.

Syntax
expression1 && expression2
Example
if ($x && $y)
    printf("%n and %n are both True\n", $x, $y);

Table 2.64. Arguments Processed By &&

Argument

Processing

Integer

Returns True if both expressions are True, False if otherwise. Logical short-circuiting is implemented; if expression1 is False, then expression2 is not evaluated, and the operator returns False.


This operator does not throw any exceptions.

2.12.51. Logical Or Operator (||)

Synopsis

Returns True if either of the arguments are True.

Syntax
expression1 || expression2
Example
if ($x || $y)
    printf("either %n or %n or both are True\n", $x, $y);

Table 2.65. Arguments Processed By ||

Argument

Processing

Integer

Returns True if either or both expressions evaluate to True, False if otherwise. Logical short-circuiting is implemented; if expression1 is True, then expression2 is not evaluated, and the operator returns True.


This operator does not throw any exceptions.

2.12.52. Conditional Operator (? :)

Synopsis

Evaluates and returns the value of one of two expressions depending on the value of a conditional expression.

Syntax
expression ? if_true_expression : if_false_expression
Example
$a = ($z > 100 ? "Big" : "Small");

Table 2.66. Arguments Processed By ? :

Argument

Processing

All

If expression is evaluated to be True, then the if_true_expression is evaluated and returned. Otherwise the if_false_expression is evaluated and returned.


This operator does not throw any exceptions.

2.12.53. Comma Operator (,)

Synopsis

Makes a list from more than one element.

Syntax
expression1, expression2
Example
$a = 1, 2, "three";

Table 2.67. Arguments Processed By ,

Argument

Processing

All

The comma operator builds lists of arguments.


This operator does not throw any exceptions.

2.12.54. Unshift Operator (unshift)

Synopsis

Inserts an element into the first position of a list and moves all other elements up one position.

Syntax
unshift lvalue, expression
Example
unshift $list, "one";

Table 2.68. Arguments Processed By unshift

Argument

Processing

All

Inserts the value of expression as the first element in the list given by lvalue. All other elements in the list are moved forward.


2.12.55. Push Operator (push)

Synopsis

Adds one element to the end of a list.

Syntax
push lvalue, expression
Example
push $list, "last";

Table 2.69. Arguments Processed By push

Argument

Processing

All

Appends the value of the expression as the last element in the list given by lvalue. If expression evaluates to a list, this list will be appended as the last element of lvalue. To concatenate lists, use the Plus Operator.


2.12.56. Splice Operator (splice)

Synopsis

Removes and optionally inserts elements in lists and strings.

Syntax
splice lvalue, offset_expression, [length_expression, [substitution_expression]]
Example
splice $list, 2, 2;
splice $string, 2, 2, "-text-";

Works on either strings or lists in a similar way; removes elements from a list or characters from a string and optionally inserts new ones. If no length_expression is given, splice removes all elements/characters from the list or string starting at offset_expression) (list and string offsets begin at 0). Otherwise, a number of elements/characters equal to length_expression is removed (or up to the end of the list/string if applicable). If substitution_expression is present, then the removed elements/characters are substituted with the elements/string given by this expression.

Note that string splice takes character offsets, which may not be the same as byte offsets for multi-byte character encodings, such as UTF-8

Table 2.70. Arguments Processed By splice

Argument

Processing

lvalue

If the lvalue is a list, list elements are processed, otherwise, if it is a string, characters in the string are processed. For any other data type, no action is taken.

offset_expression

The start element/character position for removing elements/characters from the list or string.

length_expression

The number of elements/characters to remove. If this expression is not present, then all elements/characters from the offset to the end of the list/string are removed. If this expression is present and evaluates to 0, no characters/elements are removed.

substitution_expression

For list splice, an optional element or list to substitute for the removed elements (to insert a list in a single element's position, make sure that the list to be inserted is the first and only element of another list used as the argument in this position; in other words, pass a list within a single-element list). For string splice, an optional string to substitute for the removed characters.


2.12.57. Assignment Operator (=)

Synopsis

Assigns a value to an lvalue.

Syntax
lvalue = expression
Example
$a = 1;

Table 2.71. Types Processed =

Argument

Processing

All

Assigns the value of expression to lvalue.


2.12.58. Plus Equals Operator (+=)

Synopsis

Increments and concatentates an lvalue with the value of an expression depending on the data type of the lvalue, unless the lvalue is NOTHING, in which case this operator acts like the assignment operator (simply assigns the value of the right hand side to the lvalue).

Syntax
lvalue += expression
Example
$a += 10;

Table 2.72. Arguments Processed By +=

Argument

Processing

lvalue: List

the expression will be evaluated and concatenated to the lvalue. If expression is a list, the lists will be concatenated, to ensure adding a single element to a list, use the push operator (see Push Operator).

lvalue: Hash

the expression will be evaluated, and, if it is a hash or object, then it's members will be added to the lvalue, any duplicate elements in the lvalue will be overridden by elements in the expression.

lvalue: String

the expression will be evaluated and converted to a string if necessary and concatenated to the lvalue.

lvalue: Float

the expression will be evaluated and converted to a float if necessary and added to the lvalue.

lvalue: Binary

the expression will be evaluated and converted to a string if necessary and added to the lvalue.

lvalue: NOTHING

the lvalue will be assigned to the value of expression.

lvalue: all others

the lvalue's type will be converted to an integer, and the expression will be evaluated and converted to an integer if necessary, and then the result will be added to the lvalue.


2.12.59. Minus Equals Operator (-=)

Synopsis

For a float or integer argument, decrements the value of an lvalue by the value of an expression. However if the lvalue is a hash and the expression is a string, removes the key represented by the string from the hash.

Syntax
lvalue -= expression
Example
$a -= 10;

Table 2.73. Arguments Processed By -=

Argument

Processing

lvalue: Float

the expression will be evaluated and converted to a float if necessary and subtracted from the lvalue

lvalue: Hash, expression: String

the hash key represented by expression will be removed from the lvalue

lvalue: NOTHING, expression: Float

the lvalue will be assigned to -expression

lvalue: all others

the lvalue's type will be converted to an integer, and the expression will be evaluated and converted to an integer if necessary, and then the result will be subtracted from the lvalue


2.12.60. And Equals Operator (&=)

Synopsis

Performs a bitwise (binary) AND operation on an lvalue using the value of an expression.

Syntax
lvalue &= expression
Example
$a &= 0xfe;

Table 2.74. Arguments Processed By &=

Argument

Processing

All

the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be binary and'ed to the lvalue


2.12.61. Or Equals Operator (|=)

Synopsis

Performs a bitwise (binary) OR operation on an lvalue using the value of an expression.

Syntax
lvalue |= expression
Example
$a |= 0xba;

Table 2.75. Arguments Processed By |=

Argument

Processing

All

the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be binary or'ed to the lvalue


2.12.62. Modula Equals Operator (%=)

Synopsis

Performs a modula calculation on an lvalue using the value of an expression.

Syntax
lvalue %= expression
Example
$a %= 100;

Table 2.76. Arguments Processed By %=

Argument

Processing

All

the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be used to divide the lvalue's value and the remainder will be saved to the lvalue


2.12.63. Multiply Equals Operator (*=)

Synopsis

Performs a multiplication operation on an lvalue using the value of an expression.

Syntax
lvalue *= expression
Example
$a *= 10;

Table 2.77. Arguments Processed By *=

Argument

Processing

All

If either side of the operator is a float, the result will be a float as well. Otherwise the result is an integer value. The expression will be evaluated and multiplied by the lvalue, and the result will be saved to the lvalue.


2.12.64. Divide Equals Operator (/=)

Synopsis

Performs a division operation on an lvalue using the value of an expression.

Syntax
lvalue /= expression
Example
$a /= 10;

Table 2.78. Arguments Processed By *=

Argument

Processing

All

If either side of the operator is a float, the result will be a float as well. Otherwise the result is an integer value. The expression will be evaluated and used to divide the lvalue, and the result will be saved to the lvalue.


Table 2.79. Exceptions Thrown by /*

err

desc

DIVISION-BY-ZERO

If the divisor expression evaluates to zero, this exception is thrown.


2.12.65. Xor Equals Operator (^=)

Synopsis

Performs an exclusive-or operation on an lvalue using the value of an expression.

Syntax
lvalue ^= expression
Example
$a ^= 0xf9034ba7;

Table 2.80. Arguments Processed By ^=

Argument

Processing

All

Values are converted to integers if necessary. The expression will be evaluated and exclusive-or'ed with the lvalue, and the result will be saved to the lvalue.


2.12.66. Shift Left Equals Operator (<<=)

Synopsis

Performs a shift-left operation on an lvalue using the value of an expression.

Syntax
lvalue <<= expression
Example
$a <<= 3;

Table 2.81. Arguments Processed By <<=

Argument

Processing

All

Values are converted to integers if necessary. The expression will be evaluated and this value will determine how many bits the lvalue will be shifted left. The result will be saved to the lvalue.


2.12.67. Shift Right Equals Operator (>>=)

Synopsis

Performs a shift-right operation on an lvalue using the value of an expression.

Syntax
lvalue >>= expression
Example
$a >>= 3;

Table 2.82. Arguments Processed By >>=

Argument

Processing

All

Values are converted to integers if necessary. The expression will be evaluated and this value will determine how many bits the lvalue will be shifted right. The result will be saved to the lvalue.