Default Arguments

Default arguments allows a C++ function to be called without providing one or more trailing arguments. Shroud can handle default args in several different ways based on the value of option F_default_args.

Generic Default Arguments

Since a default argument can have any C++ value, the C++ compiler must be used to provide the values. Shroud does this by creating a function for each possible way to call the function. These functions are then combined into a generic interface with the C++ function name. This is the default behavior of Shroud but can be made explicit by setting option F_default_args to generic.

For example, the function

void apply(IndexType num_elems, IndexType offset = 0, IndexType stride = 1);

can be called with 1, 2 or 3 arguments. C wrapper functions are created with the prototypes:

void apply(IndexType num_elems);
void apply(IndexType num_elems, IndexType offset);
void apply(IndexType num_elems, IndexType offset, IndexType stride);

The C++ compiler will provided the missing arguments using the default values.

The generated functions will have the same name as the C++ function with a suffix added to create unique names. By default this is a integer sequence number. The suffix can be controlled by adding a default_arg_suffix entry to the YAML file. One suffix is provided for each generated overloaded function.

- decl: void apply(IndexType num_elems, IndexType offset = 0, IndexType stride = 1);
  default_arg_suffix:
  -  _nelems
  -  _nelems_offset
  -  _nelems_offset_stride

Require Default Arguments

Shroud provides the option to require all arguments by setting F_default_args to require. This is intended to help when there are overloaded functions with default arguments. The Fortran type system is not a rich as C++ and some Fortran generic function may be ambiguous. This can happen since C++ enum is converted to an integer.

Optional Default Arguments

When the default values can be represented in Fortran the OPTIONAL attribute can be used with default arguments to allow the Fortran wrapper to supply the value for arguments which are not present in the call to the function. This is generated when the option F_default_args is set to optional. No overloaded functions are generated. The C wrapper will require all arguments to be provided.

This provides the ability to call the function from Fortran in a way not supported by C++. Each argument can be provided individually using keyword arguments. The function can be called as

call apply(100, stride=2)

and offset will be provided the default value of 0.

Since the value is provided by Fortran, this only works with integer and real values.