Utility functions for passing arrays into argument lists.
[Teuchos Language Support Utilities]

The purpose of this utility is to make passing arrays into argument lists easier. More...

Classes

class  Teuchos::ArrayArg< N, T >
 Utility class that allows arrays to be passed into argument list. More...

Functions

template<class T>
ArrayArg< 1, T > Teuchos::arrayArg (T t1)
 Return an array with 1 member.
template<class T>
ArrayArg< 2, T > Teuchos::arrayArg (T t1, T t2)
 Return an array with 2 members.
template<class T>
ArrayArg< 3, T > Teuchos::arrayArg (T t1, T t2, T t3)
 Return an array with 3 members.
template<class T>
ArrayArg< 4, T > Teuchos::arrayArg (T t1, T t2, T t3, T t4)
 Return an array with 4 members.
template<class T>
ArrayArg< 5, T > Teuchos::arrayArg (T t1, T t2, T t3, T t4, T t5)
 Return an array with 5 members.
template<class T>
ArrayArg< 6, T > Teuchos::arrayArg (T t1, T t2, T t3, T t4, T t5, T t6)
 Return an array with 6 members.

Detailed Description

The purpose of this utility is to make passing arrays into argument lists easier.

Declaring arrays outside of a function just to pass a (small) list of values into a function can be tiresome. The templated function arrayArg() simplifies this process. With this function you can construct (using stack memory not dynamically allocated memory) an array of data to be passed into a function.

For example, consider the following function prototype:

void f( const int x_size, const double x[] );

which takes an array of doubles of length x_size. Generally, to call this function one would have to first declare an array and then call the function as:

void f()
{
  ...
  const double x[] = { 1.0, 2.0, 3.0 };
  f( 3, x );
  ...

Now, however, one can create the array in the call to f() as:

void f()
{
  ...
  f( 3, arrayArg<double>(1.0,2.0,3.0)() );
  ...
}

In the above situation, one may be able to write the call as:

void f()
{
  ...
  f( 3, arrayArg(1.0,2.0,3.0) );
  ...
}

but the former, slightly more verbose, version is to be preferred since it makes explicit what type of array is being created and insures that the compiler will not get confused about the final (implicit) conversion to a raw const double* pointer.

Note that a copy is made of the array arguments before they are passed into the function so care must be taken when using arrayArg() to pass a non-const input-output or output-only array of objects. For example, consider the following function:

void f2( const int y_size, double y[] );

The above function f2() modifies the objects in the array y[]. If this function is attempted to be called as:

void g2()
{
  double a, b, c;
  f2( 3, arrayArg(a,b,c)() );
}

then the objects a, b and c will not be modified as might be expected. Instead, this function must be called as:

void g2()
{
  double y[3];
  f2( 3, y );
  double a=y[0], b=y[1], c=y[2];
}

However, the arrayArg() function can be used to pass an array of pointers to non-const objects. For example, consider the function:

void f3( const int y_size, double* y[] );

which modifies an array of double objects through pointers. We could then call this function as:

void g3()
{
  double a, b, c;
  f2( 3, arrayArg(&a,&b,&c)() );
}

which will result in objects a, b and c being modified correctly.

Warning! Never try to pass an array of references (which should almost never be used anyway) using arrayArg(). This will result in the copy constructor being called which is almost never a desirable situation.

The arrayArg() function is overloaded to accept 1, 2, 3, 4, 5 and 6 arguments. If more elements are needed, then more overrides are easy to add.


Function Documentation

template<class T>
ArrayArg<1,T> Teuchos::arrayArg ( t1  )  [inline]

Return an array with 1 member.

Definition at line 186 of file Teuchos_arrayArg.hpp.

template<class T>
ArrayArg<2,T> Teuchos::arrayArg ( t1,
t2 
) [inline]

Return an array with 2 members.

Definition at line 197 of file Teuchos_arrayArg.hpp.

template<class T>
ArrayArg<3,T> Teuchos::arrayArg ( t1,
t2,
t3 
) [inline]

Return an array with 3 members.

Definition at line 208 of file Teuchos_arrayArg.hpp.

template<class T>
ArrayArg<4,T> Teuchos::arrayArg ( t1,
t2,
t3,
t4 
) [inline]

Return an array with 4 members.

Definition at line 219 of file Teuchos_arrayArg.hpp.

template<class T>
ArrayArg<5,T> Teuchos::arrayArg ( t1,
t2,
t3,
t4,
t5 
) [inline]

Return an array with 5 members.

Definition at line 230 of file Teuchos_arrayArg.hpp.

template<class T>
ArrayArg<6,T> Teuchos::arrayArg ( t1,
t2,
t3,
t4,
t5,
t6 
) [inline]

Return an array with 6 members.

Definition at line 241 of file Teuchos_arrayArg.hpp.


Generated on Tue Oct 20 12:45:26 2009 for Teuchos - Trilinos Tools Package by doxygen 1.4.7