OTS/OTSCPP/Tools/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
//  http://www.boost.org/LICENSE_1_0.txt).

#if !defined(BOOST_VMD_ELEM_HPP)
#define BOOST_VMD_ELEM_HPP

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

#if BOOST_PP_VARIADICS

#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/>
    ...       = 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.
             
  @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/>
    ...       = 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.
             
  @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__) \
/**/

#endif /* BOOST_PP_VARIADICS */
#endif /* BOOST_VMD_ELEM_HPP */