Description

elem = A sequence element number. From 0 to sequence size - 1.
... = Variadic parameters.

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.

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.

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.