| Home | Libraries | People | FAQ | More

## Struct template placeholder

boost::xpressive::placeholder — For defining a placeholder to stand in for a variable a semantic action.

## Synopsis

    // In header: <boost/xpressive/regex_actions.hpp>

    template<typename T, int I = 0>
    struct placeholder {
      // construct/copy/destruct
      placeholder& operator=(T &) const;
      placeholder& operator=(T const &) const;
    };

## Description

Use `placeholder<>` to define a placeholder for use in semantic actions to stand in for real objects. The use of placeholders allows regular expressions with actions to be defined once and reused in many contexts to read and write from objects which were not available when the regex was defined.

You can use `placeholder<>` by creating an object of type `placeholder<T>` and using that object in a semantic action exactly as you intend an object of type `T` to be used.

    placeholder<int> _i;
    placeholder<double> _d;

    sregex rex = ( some >> regex >> here )
        [ ++_i, _d *= _d ];

Then, when doing a pattern match with either `regex_search()`, `regex_match()` or `regex_replace()`, pass a `match_results<>` object that contains bindings for the placeholders used in the regex object's semantic actions. You can create the bindings by calling `match_results::let` as follows:

    int i = 0;
    double d = 3.14;

    smatch what;
    what.let(_i = i)
        .let(_d = d);

    if(regex_match("some string", rex, what))
       // i and d mutated here

If a semantic action executes that contains an unbound placeholder, a exception of type `regex_error` is thrown.

See the discussion for `xpressive::let()` and the "Referring to Non-Local Variables" section in the Users' Guide for more information.

Example:

    // Define a placeholder for a map object:
    placeholder<std::map<std::string, int> > _map;

    // Match a word and an integer, separated by =>,
    // and then stuff the result into a std::map<>
    sregex pair = ( (s1= +_w) >> "=>" >> (s2= +_d) )
        [ _map[s1] = as<int>(s2) ];

    // Match one or more word/integer pairs, separated
    // by whitespace.
    sregex rx = pair >> *(+_s >> pair);

    // The string to parse
    std::string str("aaa=>1 bbb=>23 ccc=>456");

    // Here is the actual map to fill in:
    std::map<std::string, int> result;

    // Bind the _map placeholder to the actual map
    smatch what;
    what.let( _map = result );

    // Execute the match and fill in result map
    if(regex_match(str, what, rx))
    {
        std::cout << result["aaa"] << '\n';
        std::cout << result["bbb"] << '\n';
        std::cout << result["ccc"] << '\n';
    }

### Template Parameters

1.     typename T

   The type of the object for which this placeholder stands in.

2.     int I = 0

   An optional identifier that can be used to distinguish this placeholder from others that may be used in the same semantic action that happen to have the same type.

### `placeholder` public construct/copy/destruct

1.     placeholder& operator=(T & t) const;

   Parameters: |
   `t` | The object to associate with this placeholder
   Returns: | An object of unspecified type that records the association of `t` with `*this`.

2.     placeholder& operator=(T const & t) const;

   This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.