| Home | Libraries | People | FAQ | More

##### Generator Directives Forcing Atomic Extraction (`as<T>, as_string[], as_wstring[]`)

###### Description

The `as<T>` class forces the atomic extraction of a container type `T` from it's consumed attribute. Usually, repetitive generators (such as Kleene (`*`), etc) or sequences exposing a `vector<A>` will extract elements from the container supplied as their consumed attribute by looping through the containers iterators. In some cases, this may be undesirable. The `as<T>` class creates a directive that will pass an unnamed temporary object of type `T` to it's subject, if extracting `T` from it's consumed attribute determined at generation-time to be valid. `traits::valid_as<T>()` is called by `as<T>` to determine validity; if it returns false, the generator fails. Subsequent extraction is performed by calling `traits::as<T>()`.

| Note
`T` is required to be a container type. If `traits::is_container` does not return true for `T`, a compile-time error will occur.

###### Header

    // forwards to <boost/spirit/home/karma/directive/as.hpp>
    #include <boost/spirit/include/karma_as.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::as_string // alias: boost::spirit::karma::as_string`
`boost::spirit::as_wstring // alias: boost::spirit::karma::as_wstring`

###### Synopsis

    template <typename T>
    struct as;

###### Template parameters

Parameter | Description | Default
--- | --- | ---
`T` | A container type. | none

###### Model of

> `UnaryGenerator`

Notation

`a`

  A `Generator`.

`attr`

  The attribute supplied to the directive.

###### Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in `UnaryGenerator`.

Expression | Semantics
--- | ---
`as<T>()[a]` | Extract an instance of `T` from `attr`, and invoke the subject generator `a`, supplying the unnamed temporary as it's attribute.
`as_string[a]` | Equivalent to `as<std::string>()[a]`
`as_wstring[a]` | Equivalent to `as<std::wstring>()[a]`

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---
`as<T>()[a]` | `a: A --> as<T>()[a]: T`

###### Complexity

> The complexity is defined by the complexity of the subject generator, `a`, and the complexity of the extraction unnamed contianer of type `T` from the attribute `attr`.

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some using declarations:

    using boost::spirit::utree;
    using boost::spirit::utree_type;
    using boost::spirit::utf8_symbol_type;
    using boost::spirit::karma::as;
    using boost::spirit::karma::as_string;
    using boost::spirit::karma::char_;
    using boost::spirit::karma::double_;

Simple usage of `as<T>`, `as_string` and `as_wstring`:

To properly handle string concatenation with `utree`, we make use of `as_string[]`. We also use `as<T>` to explicitly extract a `utree` symbol node.

    typedef as<utf8_symbol_type> as_symbol_type;
    as_symbol_type const as_symbol = as_symbol_type();

    utree ut;
    ut.push_back("xyz");
    ut.push_back(1.23);

    test_generator_attr("xyz1.23", as_string[*char_] << double_, ut);
    test_generator_attr("xyz1.23", as<std::string>()[*char_] << double_, ut);

    ut.clear();

    ut.push_back(utf8_symbol_type("xyz"));
    ut.push_back(1.23);

    test_generator_attr("xyz1.23", as_symbol[*char_] << double_, ut);
    test_generator_attr("xyz1.23", as<utf8_symbol_type>()[*char_] << double_, ut);