ceph/src/boost/libs/vmd/doc/vmd_modifiers_splitting.qbk

   1 [/
   2   (C) Copyright Edward Diener 2011-2015
   3   Distributed under the Boost Software License, Version 1.0.
   4   (See accompanying file LICENSE_1_0.txt or copy at
   5   http://www.boost.org/LICENSE_1_0.txt).
   6 ]
   7
   8 [section:vmd_modifiers_splitting Splitting modifiers]
   9
  10 The BOOST_VMD_ELEM macro, which by default just returns an element of
  11 a sequence, has a usage where you can have it return both the
  12 element and the remaining part of the sequence after the element,
  13 or even just the remaining part of the sequence after the element by itself.
  14 This offers a form of splitting the sequence on a particular element. When
  15 used to return the remaining part of a sequence the remaining data may
  16 subsequently be treated as a VMD sequence again.
  17
  18 To do this another set of optional modifiers are used which will
  19 be called 'splitting modifers'. These modifiers are:
  20
  21 * BOOST_VMD_RETURN_AFTER, which returns both the element information and the
  22 rest of the sequence after the element as a two-element tuple
  23 * BOOST_VMD_RETURN_ONLY_AFTER, which returns only the rest of the sequence
  24 after the element specified
  25 * BOOST_VMD_RETURN_NO_AFTER, this is the internal default which only returns
  26 the element itself. It need never be specified but may be used to override
  27 a previous splitting modifier specified as an optional parameter.
  28
  29 If more than one of the splitting modifiers are specified as optional parameters
  30 to BOOST_VMD_ELEM the last one specified is in effect.
  31
  32 The splitting modifiers BOOST_VMD_RETURN_NO_AFTER and BOOST_VMD_RETURN_AFTER
  33 work with either return type modifiers or filtering modifiers if they are
  34 used. The splitting modifier BOOST_VMD_RETURN_ONLY_AFTER works with
  35 filtering modifiers if it is used and any return type modifiers will be ignored.
  36 Optional modifiers may occur in any order after the required parameters
  37 to BOOST_VMD_ELEM.
  38
  39 If BOOST_VMD_RETURN_AFTER is in effect and an element is not found, either
  40 because the element number is out of range for the sequence or because
  41 filtering does not match the element type, a tuple will still be returned
  42 but both its elements will be empty.
  43
  44  #include <boost/vmd/elem.hpp>
  45
  46  #define BOOST_VMD_REGISTER_ANAME (ANAME) // an identifier must always be registered to be found by VMD
  47  #define A_SEQUENCE (1,2,3) 46 (list_data1,BOOST_PP_NIL) BOOST_VMD_TYPE_SEQ ANAME
  48
  49  BOOST_VMD_ELEM(2,A_SEQUENCE) will return '(list_data1,BOOST_PP_NIL)'
  50  BOOST_VMD_ELEM(2,A_SEQUENCE,BOOST_VMD_RETURN_NO_AFTER) will return '(list_data1,BOOST_PP_NIL)'
  51  BOOST_VMD_ELEM(2,A_SEQUENCE,BOOST_VMD_RETURN_AFTER) will return '((list_data1,BOOST_PP_NIL),BOOST_VMD_TYPE_SEQ ANAME)'
  52  BOOST_VMD_ELEM(2,A_SEQUENCE,BOOST_VMD_RETURN_ONLY_AFTER) will return 'BOOST_VMD_TYPE_SEQ ANAME'
  53
  54  BOOST_VMD_ELEM(5,A_SEQUENCE) will return emptiness
  55  BOOST_VMD_ELEM(5,A_SEQUENCE,BOOST_VMD_RETURN_NO_AFTER) will return emptiness
  56  BOOST_VMD_ELEM(5,A_SEQUENCE,BOOST_VMD_RETURN_AFTER) will return '(,)'
  57  BOOST_VMD_ELEM(5,A_SEQUENCE,BOOST_VMD_RETURN_ONLY_AFTER) will return emptiness
  58
  59 Combining splitting modifiers with return type modifiers:
  60
  61  BOOST_VMD_ELEM(2,A_SEQUENCE,BOOST_VMD_RETURN_AFTER,BOOST_VMD_RETURN_TYPE) will return '((BOOST_VMD_TYPE_LIST,(list_data1,BOOST_PP_NIL)),BOOST_VMD_TYPE_SEQ ANAME)'
  62
  63 Combining splitting modifiers with filtering modifiers:
  64
  65  BOOST_VMD_ELEM(2,A_SEQUENCE,BOOST_VMD_RETURN_AFTER,BOOST_VMD_TYPE_LIST) will return '((list_data1,BOOST_PP_NIL),BOOST_VMD_TYPE_SEQ ANAME)'
  66
  67 [endsect]