Comments on the preprocessor list data structure

From: vesa_karvonen (vesa_karvonen_at_[hidden])
Date: 2002-01-21 06:53:58

I'm almost ready to commit the list data structure support into the 
preprocessor library. Since this is a major extension to the library, 
I'd like to hear comments on naming, documentation and other 
interface related issues.

Armed with the list data structure, it should be possible to simulate 
a (very limited in recursion depth and storage) Turing machine with 
the preprocessor.

The current set of supported list macros includes many higher order 
macros. I plan to add other macros as time permits or on request.

Here are the extracts of the list support macros:

//! List constructor.
/*!
Lists are build using list constructors BOOST_PP_LIST_NIL and
BOOST_PP_LIST_CONS(). For example:

  BOOST_PP_LIST_CONS(1,
  BOOST_PP_LIST_CONS(2,
  BOOST_PP_LIST_CONS(3,
  BOOST_PP_LIST_CONS(4,
  BOOST_PP_LIST_CONS(5,
  BOOST_PP_LIST_NIL)))))

Short lists can also be build from tuples:

  BOOST_PP_TUPLE_TO_LIST(5,(1,2,3,4,5))

Both of the above lists contain 5 elements: 1, 2, 3, 4 and 5.
*/
#define BOOST_PP_LIST_CONS(H,T)

//! List nil constructor.
/*!
See BOOST_PP_LIST_CONS().
*/
#define BOOST_PP_LIST_NIL

//! Expands to 1 if the list is not nil and 0 otherwise.
/*!
See BOOST_PP_LIST_IS_NIL().
*/
#define BOOST_PP_LIST_IS_CONS(L)

//! Expands to 1 if the list is nil and 0 otherwise.
/*!
See BOOST_PP_LIST_IS_CONS().
*/
#define BOOST_PP_LIST_IS_NIL(L)

//! Expands to the head of the list. The list must not be nil.
/*!
For example:

  BOOST_PP_LIST_HEAD(BOOST_PP_TUPLE_TO_LIST(5,(1,2,3,4,5)))

The above expands to 1.
*/
#define BOOST_PP_LIST_HEAD(L)

//! Expands to the tail of the list. The list must not be nil.
/*!
For example:

  BOOST_PP_LIST_TAIL(BOOST_PP_TUPLE_TO_LIST(5,(1,2,3,4,5)))

The above expands to a list containing 2, 3, 4 and 5.
*/
#define BOOST_PP_LIST_TAIL(L)

//! Catenates two lists together.
/*!
For example:

  BOOST_PP_LIST_APPEND
  ( BOOST_PP_TUPLE_TO_LIST(2,(1,2))
  , BOOST_PP_TUPLE_TO_LIST(2,(3,4))
  )

Produces a list containing 1, 2, 3 and 4.
*/
#define BOOST_PP_LIST_APPEND(L,R)

//! Expands to the I:th element of the list L.
/*!
Example:

  BOOST_PP_LIST_AT(BOOST_PP_TUPLE_TO_LIST(3,(A,B,C)),1)

The above expands to B.
*/
#define BOOST_PP_LIST_AT(L,I)

//! Catenates all elements of the list.
/*!
Example:

  BOOST_PP_LIST_CAT(BOOST_PP_TUPLE_TO_LIST(3,(1,2,3)))

The above expands to 123.
*/
#define BOOST_PP_LIST_CAT(L)

//! Drops the first N elements of the list.
/*!
Example:

  BOOST_PP_LIST_DROP(2,BOOST_PP_TUPLE_TO_LIST(4,(+,-,*,/)))

Expands to a list containing * and /.
*/
#define BOOST_PP_LIST_DROP(N,L)

//! Converts the list to a comma separated list.
/*!
Example:

  BOOST_PP_LIST_ENUM(BOOST_PP_TUPLE_TO_LIST(3,(A,B,C)))

The above expands to:

  A, B, C
*/
#define BOOST_PP_LIST_ENUM(L)

//! Expands to a list containing all the elements X of the list for 
which F(D,P,X) is true.
/*!
Example:

  BOOST_PP_LIST_FILTER(BOOST_PP_NOT_EQUAL_D,2,BOOST_PP_TUPLE_TO_LIST
(3,(1,2,3)))

The above expands to a list containing 1 and 3.
*/
#define BOOST_PP_LIST_FILTER(F,P,L)

//! Iterates F(D,P,X) for each element X of the list L (from the left 
or the start of the list).
/*!
In other words,

  BOOST_PP_LIST_FOLD_LEFT(F,P,L)

expands to:

  F
  ( D
  , ... F(D, F(D,P,BOOST_PP_LIST_AT(L,0)), BOOST_PP_LIST_AT(L,1)) ...
  , BOOST_PP_LIST_AT(L,BOOST_PP_DEC(BOOST_PP_LIST_SIZE(L))
  )
*/
#define BOOST_PP_LIST_FOLD_LEFT(F,P,L)

//! Iterates F(D,X,P) for each element X of the list L (from the 
right or the end of the list).
/*!
In other words,

  BOOST_PP_LIST_FOLD_RIGHT(F,L,P)

expands to:

  F
  ( D
  , BOOST_PP_LIST_AT(L,0)
  , ... F
        ( D
        , F
          ( D
          , P
          , BOOST_PP_LIST_AT(L,BOOST_PP_SUB(BOOST_PP_LIST_SIZE(L),1))
          )
        , BOOST_PP_LIST_AT(L,BOOST_PP_SUB(BOOST_PP_LIST_SIZE(L),2))
        ) ...
  )
*/
#define BOOST_PP_LIST_FOLD_RIGHT(F,L,P)

//! Repeats F(R,P,BOOST_PP_LIST_AT(L,I)) for each I = 
[0,BOOST_PP_LIST_SIZE(L)[.
/*!
In other words, expands to the sequence:

  F(R,P,BOOST_PP_LIST_AT(L,0))
  F(R,P,BOOST_PP_LIST_AT(L,1))
  ...
  F(R,P,BOOST_PP_LIST_AT(L,BOOST_PP_DEC(BOOST_PP_LIST_SIZE(L))))

See BOOST_PP_FOR() for an explanation of the R parameter.
*/
#define BOOST_PP_LIST_FOR_EACH(F,P,L)

//! List reversal.
/*!
Example:

  BOOST_PP_LIST_REVERSE(BOOST_PP_TUPLE_TO_LIST(3,(A,B,C)))

The above expands to a list containing C, B and A.
*/
#define BOOST_PP_LIST_REVERSE(L)

//! Expands to the number of elements in the list.
/*!
Example:

  BOOST_PP_LIST_SIZE(BOOST_PP_TUPLE_TO_LIST(3,(A,B,C)))

The above expands to 3.
*/
#define BOOST_PP_LIST_SIZE(L)

//! Takes the first N elements of the list.
/*!
Example:

  BOOST_PP_LIST_TAKE(2,BOOST_PP_TUPLE_TO_LIST(4,(+,-,*,/)))

Expands to a list containing + and -.
*/
#define BOOST_PP_LIST_TAKE(N,L)

//! Converts the list to a tuple.
/*!
Example:

  BOOST_PP_LIST_TO_TUPLE(BOOST_PP_TUPLE_TO_LIST(3,(A,B,C)))

Expands to (A,B,C).

NOTE: The supported size of the list being converted to a tuple is 
limited by
BOOST_PP_LIMIT_MAG rather than BOOST_PP_LIMIT_TUPLE.
*/
#define BOOST_PP_LIST_TO_TUPLE(L)

//! Applies the macro F(D,P,X) to each element X of the list 
producing a new list.
/*!
Example:

  BOOST_PP_LIST_TRANSFORM(BOOST_PP_ADD_D,2,BOOST_PP_TUPLE_TO_LIST(2,
(1,2)))

The above expands to a list containing 3 and 4.
*/
#define BOOST_PP_LIST_TRANSFORM(F,P,L)

//! Converts a tuple to a list
/*!
See BOOST_PP_LIST_CONS() for an example.

See also BOOST_PP_LIMIT_TUPLE.
*/
#define BOOST_PP_TUPLE_TO_LIST(N,T)