Jem provides a set of overloaded operators and functions for writing expressions that operate on all elements of one or more tuples. These operators and functions return special tuple objects, called tuple expressions, that can be assigned to regular Tuple objects. Tuple expressions can also be passed to the overloaded operators and functions to create new tuple expressions.

Here is an example:

Tuple<double,3> a ( 0.0, 1.0, 2.0 );
Tuple<double,3> b;
Tuple<double,3> c;
b = 1.0 + sin( a );
c = a * a + pow( b, 2.0 );

This code fragment is equivalent with:

Tuple<double,3> a ( 0.0, 1.0, 2.0 );
Tuple<double,3> b;
Tuple<double,3> c;
int i;
for ( i = 0; i < 3; i++ )
{
  b[i] = 1.0 + sin( a[i] );
}
for ( i = 0; i < 3; i++ )
{
  c[i] = a[i] * a[i] + pow( b[i], 2.0 );
}

Like an array expression, a tuple expression can be viewed as a special type of tuple that comprises a set of operators and functions, and a set of operands. The latter set consists of Tuple objects, scalars and other tuple expression objects. The elements of a tuple expression are obtained by applying the functions and operators element-wise to the elements of the operands. Thus, the i-th element of the tuple expression (1.0 + sin(a)) equals (1.0 + sin(a[i])).

If a scalar, such as 1.0, is one of the operands of an array expression, it is implicitly converted to a tuple-like object that has the same size as the other operands involved in the tuple expression. The elements of this tuple-like object are all equal to the scalar.

Tuple expressions are efficient for two reasons. First, they are based on the `expression template' technique that eliminates the creation of intermediate Tuple objects (see http://oonumerics.org for the details). Second, the for-loop over the elements of a tuple expression is automatically unrolled, provided that the size N is not too large (four in the current implementation).

The following sections provide an overview of the overloaded operators and functions that can be used to create tuple expressions.

Unary operators

#include <jem/base/tuple/operators.h> or
#include <jem/base/Tuple.h>.

Supported unary operators:

- (unary minus)
! (logical not)
~ (bitwise not)

These operators can be called with either a Tuple object or a tuple expression. Each returns an tuple expression that applies the unary operator to the elements of the tuple argument. The elements of the tuple expression are of the same type as the elements of the tuple argument.

The unary operators are defined in the header file <jem/base/tuple/operators.h>. They are also available through the general header file <jem/base/Tuple.h>.

Binary operators

#include <jem/base/tuple/operators.h> or
#include <jem/base/Tuple.h>.

Supported binary arithmetic operators:

+ (addition)
- (substraction)
* (multiplication)
/ (division)
% (modulo division)

Supported binary bitwise operators:

| (bitwise or)
^ (bitwise xor)
& (bitwise and)
<< (left shift)
>> (right shift)

Supported binary logical operators:

|| (logical or)
&& (logical and)

Supported comparison operators:

< (less than)
<= (less equal)
> (greater than)
>= (greater equal)
== (equal)
!= (not equal)

All the operators listed above can be called with two Tuple objects, two tuple expressions, or one Tuple object and one tuple expression. They can also be called with a Tuple object and a scalar, or a tuple expression and a scalar. They return a tuple expression that applies the operator to the elements of the tuple arguments and/or scalar argument. The elements of the tuple arguments and/or the scalar argument must be of the same type; one can not, for instance, add an integer tuple to a floating point tuple.

All operators except the comparison operators return an tuple expression of which the elements are of the same type as the elements of the tuple arguments and/or scalar argument. The comparison operators return an tuple expression of which the elements are of type bool.

The binary operators are defined in the header file <jem/base/tuple/operators.h>. They are also available through the general header file <jem/base/Tuple.h>.

Unary functions

#include <jem/base/tuple/intrinsics.h> or
#include <jem/base/Tuple.h>.

The following unary functions can be called with a Tuple object or a tuple expression:

abs
acos
asin
atan
ceil
cos
cosh
exp
floor
log
log10
sin
sinh
sqrt
tan
tanh

Each function returns a tuple expression that applies the function to the elements of the tuple argument. The elements of the tuple expression are of the same type as the elements of the tuple argument.

The unary functions listed above are defined in the header file <jem/base/tuple/intrinsics.h>. They are also available through the general header file <jem/base/Tuple.h>.

Binary functions

#include <jem/base/tuple/intrinsics.h> or
#include <jem/base/Tuple.h>.

The binary function pow can be called with two Tuple objects, two tuple expressions, or one Tuple object and one tuple expression. It can also be called with an Tuple object and a scalar, or an tuple expression and a scalar. The pow function returns a tuple expression that applies the pow function to all elements of the tuple arguments and/or scalar argument. The elements of the returned tuple expression are of the same type as the elements of the tuple arguments and/or scalar argument.

The pow funtion is defined in the header file <jem/base/tuple/intrinsics.h>. It is also available through the general header file <jem/base/Tuple.h>.

Other functions

#include <jem/base/tuple/intrinsics.h> or
#include <jem/base/Tuple.h>.

Two other functions that create tuple expressions are castTo and where. The first one can be used to convert the elements of a tuple from one type to another type. It is called like this:

castTo<T> ( a )

where T is the target type of the conversion, and a is a Tuple or a tuple expression. The castTo function returns a tuple expression that applies the static_cast<T> operator to all the elements of the tuple argument. The elements of the returned tuple expression are of type T.

Example:

Tuple<float,2> a ( 1.0, 2.5 );
Tuple<int,2>   b;
b = castTo<int> ( a )

which is the same as:

Tuple<float,2> a ( 1.0, 2.5 );
Tuple<int,2>   b;
b[0] = static_cast<int> ( a[0] );
b[1] = static_cast<int> ( a[1] );

The function where mimicks the conditional operator (?:). It is called as follows:

where ( mask, lhs, rhs )

where mask is a Tuple object or a tuple expression with elements of type bool. The arguments lhs and rhs should be Tuple objects, tuple expressions, scalars, or a combination of these. The where function returns a tuple expression that applies the conditional (?:) operator to all the elements of its three arguments. The elements of the tuple expression are of the same type as the elements of the tuple arguments and/or scalar arguments.

Example:

Tuple<float,2> a ( 1.0, 2.5 );
Tuple<float,2> b;
b = where ( a > 1.0, a, 0.0 );

which is equivalent with:

Tuple<float,2> a ( 1.0, 2.5 );
Tuple<float,2> b;
b[0] = ( a[0] > 1.0 ) ? a[0] : 0.0;
b[1] = ( a[1] > 1.0 ) ? a[1] : 0.0;

The funtions castTo and where are defined in the header file <jem/base/tuple/intrinsics.h>. They are also available through the general header file <jem/base/Tuple.h>.