# Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world.

This is the documentation for a snapshot of the develop branch, built from commit c73fda95e0.

### boost/vmd/elem.hpp


//  (C) Copyright Edward Diener 2011-2015
//  Use, modification and distribution are subject to the Boost Software License,
//  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at

#if !defined(BOOST_VMD_ELEM_HPP)
#define BOOST_VMD_ELEM_HPP

#include <boost/vmd/detail/setup.hpp>

#include <boost/vmd/detail/modifiers.hpp>
#include <boost/vmd/detail/sequence_elem.hpp>

/*

The succeeding comments in this file are in doxygen format.

*/

/** \file
*/

/** \def BOOST_VMD_ELEM(elem,...)

\brief Accesses an element of a sequence.

elem      = A sequence element number. From 0 to sequence size - 1. <br/>

The first variadic parameter is required and is the sequence to access.
Further variadic parameters are all optional.

With no further variadic parameters the macro returns the particular element
in the sequence. If the element number is outside the bounds of the sequence
macro access fails and the macro turns emptiness.

Optional parameters determine what it means that an element is successfully
accessed as well as what data is returned by the macro.

Filters: specifying a VMD type tells the macro to return the element only
if it is of the VMD type specified, else macro access fails. If more than
one VMD type is specified as an optional parameter the last one
specified is the filter.

Matching Identifiers: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER,
optional parameters which are identifiers specify that the element accessed
must match one of the identifiers else access fails. The identifiers may be specified multiple
times as single optional parameters or once as a tuple of identifier
parameters. If the identifiers are specified as single optional parameters
they cannot be any of the specific BOOST_VMD_ optional parameters in order to be
recognized as matching identifiers. Normally this should never be the case.
The only situation where this could occur is if the VMD types, which are filters,
are used as matching identifiers; in this case the matching identifiers need
to be passed as a tuple of identifier parameters so they are not treated
as filters.

Filters and matching identifiers change what it means that an element is successfully
accessed. They do not change what data is returned by the macro. The remaining optional
parameters do not change what it means that an element is successfully accessed but they
do change what data is returned by the macro.

@code

Splitting: Splitting allows the macro to return the rest of the sequence
after the element accessed.

If BOOST_VMD_RETURN_AFTER is specified the return is a tuple
with the element accessed as the first tuple parameter and the rest of
the sequence as the second tuple parameter. If element access fails
both tuple parameters are empty.

If BOOST_VMD_RETURN_ONLY_AFTER
is specified the return is the rest of the sequence after the element accessed
found. If the element access fails the return is emptiness.

If BOOST_VMD_RETURN_NO_AFTER, the default, is specified no splitting
occurs.

If more than one of the splitting identifiers are specified
the last one specified determines the splitting.

Return Type: The element accessed can be changed to return both the type
of the element as well as the element data with optional return type
parameters. When a type is returned, the element accessed which is returned becomes a
two-element tuple where the type of the element accessed is the first tuple element and the element
data itself is the second tuple element. If the macro fails to access the
element the element access returned is emptiness and not a tuple.

If BOOST_VMD_RETURN_NO_TYPE, the default, is specified no type is returned
as part of the element accessed.

If BOOST_VMD_RETURN_TYPE is specified the specific type of the element
is returned in the tuple.

If BOOST_VMD_RETURN_TYPE_ARRAY is specified
an array type is returned if the element is an array, else a tuple
type is returned if the element is a tuple, else the actual type
is returned for non-tuple data.

If BOOST_VMD_RETURN_TYPE_LIST is specified
a list type is returned if the element is a list, else a tuple
type is returned if the element is a tuple, else the actual type
is returned for non-tuple data.

If BOOST_VMD_RETURN_TYPE_TUPLE is specified
a tuple type is returned for all tuple-like data, else the actual type
is returned for non-tuple data.

If more than one return type optional
parameter is specified the last one specified determines the return type.

If a filter is specified optional return type parameters are ignored and
the default BOOST_VMD_RETURN_NO_TYPE is in effect.

Index:  If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER,
and matching identifiers are specified, an index parameter specifies that the
numeric index, starting with 0, of the matching identifier found, be returned
as part of the result.

If BOOST_VMD_RETURN_INDEX is specified an index is returned
as part of the result.

If BOOST_VMD_RETURN_NO_INDEX, the default, is specified
no index is returned as part of the result.

If both are specified the last one specified determines the index parameter.

When an index is returned as part of the result, the result is a tuple where the
element accessed is the first tuple parameter and the index is the last tuple parameter.
If element access fails the index is empty. If there is no BOOST_VMD_TYPE_IDENTIFIER
filter or if there are no matching identifiers the BOOST_VMD_RETURN_INDEX is ignored
and no index is returned as part of the result.

@endcode

returns   = With no optional parameters the element accessed is returned, or emptiness if
element is outside the bounds of the sequence. Filters and matching identifiers
can change the meaning of whether the element accessed is returned or failure
occurs, but whenever failure occurs emptiness is returned as the element access part
of that failure, else the element accessed is returned. Return type optional parameters,
when filters are not used, return the element accessed as a two-element tuple
where the first tuple element is the type and the second tuple element is the
data; if the element is not accessed then emptiness is returned as the element access
and not a tuple. Splitting with BOOST_VMD_RETURN_AFTER returns a tuple where the element accessed
is the first tuple element and the rest of the sequence is the second tuple element.
Splitting with BOOST_VMD_RETURN_ONLY_AFTER returns the rest of the sequence after
the element accessed or emptiness if the element can not be accessed. Indexing
returns the index as part of the output only if filtering with
BOOST_VMD_TYPE_IDENTIFIER is specified and matching identifiers are specified.
When the index is returned with BOOST_VMD_RETURN_AFTER it is the third element
of the tuple returned, else it is the second element of a tuple where the element
accessed is the first element of the tuple.

*/

#define BOOST_VMD_ELEM(elem,...) \
BOOST_VMD_DETAIL_SEQUENCE_ELEM(BOOST_VMD_ALLOW_ALL,elem,__VA_ARGS__) \
/**/

/** \def BOOST_VMD_ELEM_D(d,elem,...)

\brief Accesses an element of a sequence. Re-entrant version.

d         = The next available BOOST_PP_WHILE iteration. <br/>
elem      = A sequence element number. From 0 to sequence size - 1. <br/>

The first variadic parameter is required and is the sequence to access.
Further variadic parameters are all optional.

With no further variadic parameters the macro returns the particular element
in the sequence. If the element number is outside the bounds of the sequence
macro access fails and the macro turns emptiness.

Optional parameters determine what it means that an element is successfully
accessed as well as what data is returned by the macro.

Filters: specifying a VMD type tells the macro to return the element only
if it is of the VMD type specified, else macro access fails. If more than
one VMD type is specified as an optional parameter the last one
specified is the filter.

Matching Identifiers: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER,
optional parameters which are identifiers specify that the element accessed
must match one of the identifiers else access fails. The identifiers may be specified multiple
times as single optional parameters or once as a tuple of identifier
parameters. If the identifiers are specified as single optional parameters
they cannot be any of the specific BOOST_VMD_ optional parameters in order to be
recognized as matching identifiers. Normally this should never be the case.
The only situation where this could occur is if the VMD types, which are filters,
are used as matching identifiers; in this case the matching identifiers need
to be passed as a tuple of identifier parameters so they are not treated
as filters.

Filters and matching identifiers change what it means that an element is successfully
accessed. They do not change what data is returned by the macro. The remaining optional
parameters do not change what it means that an element is successfully accessed but they
do change what data is returned by the macro.

@code

Splitting: Splitting allows the macro to return the rest of the sequence
after the element accessed.

If BOOST_VMD_RETURN_AFTER is specified the return is a tuple
with the element accessed as the first tuple parameter and the rest of
the sequence as the second tuple parameter. If element access fails
both tuple parameters are empty.

If BOOST_VMD_RETURN_ONLY_AFTER
is specified the return is the rest of the sequence after the element accessed
found. If the element access fails the return is emptiness.

If BOOST_VMD_RETURN_NO_AFTER, the default, is specified no splitting
occurs.

If more than one of the splitting identifiers are specified
the last one specified determines the splitting.

Return Type: The element accessed can be changed to return both the type
of the element as well as the element data with optional return type
parameters. When a type is returned, the element accessed which is returned becomes a
two-element tuple where the type of the element accessed is the first tuple element and the element
data itself is the second tuple element. If the macro fails to access the
element the element access returned is emptiness and not a tuple.

If BOOST_VMD_RETURN_NO_TYPE, the default, is specified no type is returned
as part of the element accessed.

If BOOST_VMD_RETURN_TYPE is specified the specific type of the element
is returned in the tuple.

If BOOST_VMD_RETURN_TYPE_ARRAY is specified
an array type is returned if the element is an array, else a tuple
type is returned if the element is a tuple, else the actual type
is returned for non-tuple data.

If BOOST_VMD_RETURN_TYPE_LIST is specified
a list type is returned if the element is a list, else a tuple
type is returned if the element is a tuple, else the actual type
is returned for non-tuple data.

If BOOST_VMD_RETURN_TYPE_TUPLE is specified
a tuple type is returned for all tuple-like data, else the actual type
is returned for non-tuple data. If more than one return type optional
parameter is specified the last one specified determines the return type.

If a filter is specified optional return type parameters are ignored and
the default BOOST_VMD_RETURN_NO_TYPE is in effect.

Index:  If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER,
and matching identifiers are specified, an index parameter specifies that the
numeric index, starting with 0, of the matching identifier found, be returned
as part of the result.

If BOOST_VMD_RETURN_INDEX is specified an index is returned
as part of the result.

If BOOST_VMD_RETURN_NO_INDEX, the default, is specified
no index is returned as part of the result.

If both are specified the last one specified determines the index parameter.

When an index is returned as part of the result, the result is a tuple where the
element accessed is the first tuple parameter and the index is the last tuple parameter.
If element access fails the index is empty. If there is no BOOST_VMD_TYPE_IDENTIFIER
filter or if there are no matching identifiers the BOOST_VMD_RETURN_INDEX is ignored
and no index is returned as part of the result.

@endcode

returns   = With no optional parameters the element accessed is returned, or emptiness if
element is outside the bounds of the sequence. Filters and matching identifiers
can change the meaning of whether the element accessed is returned or failure
occurs, but whenever failure occurs emptiness is returned as the element access part
of that failure, else the element accessed is returned. Return type optional parameters,
when filters are not used, return the element accessed as a two-element tuple
where the first tuple element is the type and the second tuple element is the
data; if the element is not accessed then emptiness is returned as the element access
and not a tuple. Splitting with BOOST_VMD_RETURN_AFTER returns a tuple where the element accessed
is the first tuple element and the rest of the sequence is the second tuple element.
Splitting with BOOST_VMD_RETURN_ONLY_AFTER returns the rest of the sequence after
the element accessed or emptiness if the element can not be accessed. Indexing
returns the index as part of the output only if filtering with
BOOST_VMD_TYPE_IDENTIFIER is specified and matching identifiers are specified.
When the index is returned with BOOST_VMD_RETURN_AFTER it is the third element
of the tuple returned, else it is the second element of a tuple where the element
accessed is the first element of the tuple.

*/

#define BOOST_VMD_ELEM_D(d,elem,...) \
BOOST_VMD_DETAIL_SEQUENCE_ELEM_D(d,BOOST_VMD_ALLOW_ALL,elem,__VA_ARGS__) \
/**/