Get a C-style String from a String Type

| Home | Libraries | People | FAQ | More

##### Get a C-style String from a String Type

###### extract_c_string

`extract_c_string` returns a pointer to an array of elements of a const character type. It is invoked through a static method `call`. This customization point is responsible for handling it's own garbage collecting; the lifetime of the returned C-string must be no shorter than the lifetime of the string instance passed to the `call` method.

###### Module Headers

    #include <boost/spirit/home/support/string_traits.hpp>

Also, see Include Structure.

| Note
This header file does not need to be included directly by any user program as it is normally included by other Spirit header files relying on its content.

###### Namespace

Name
`boost::spirit::traits`

###### Synopsis

    template <typename String>
    struct extract_c_string
    {
        typedef <unspecified> char_type;

        static char_type const* call (String const&);
    };

###### Template parameters

Parameter | Description | Default
--- | --- | ---
`String` | A string type. | none

Notation

`T`

  An arbitrary type.

`Char`

  A character type.

`Traits`

  A character traits type.

`Allocator`

  A standard allocator type.

`str`

  A string instance.

###### Expression Semantics

Expression | Semantics
--- | ---
`extract_c_string<T>::char_type` | The return type of `call`.
`extract_c_string<T>::call(str)` | Extract a c-string of type `char_type` from `str`.

###### Predefined Specializations

Type | Semantics
--- | ---
`T` | `call` takes a parameter of type `T const*`, and returns it without modification. An overload of `call` takes a parameter of type `T*` and casts it to `T const*`, returning the result. `char_type` is `char_type_of<T>::type`.
`T const` | `call` takes a parameter `str` of type `T const` and returns `extract_c_string<T>::call(str)`. `char_type` is `char_type_of<T>::type`.
`T&` | `call` takes a parameter `str` of type `T&` and returns `extract_c_string<T>::call(str)`. `char_type` is `char_type_of<T>::type`.
`T const&` | `call` takes a parameter `str` of type `T const&` and returns `extract_c_string<T>::call(str)`. `char_type` is `char_type_of<T>::type`.
`std::basic_string<Char, Traits, Allocator>` | `call` takes a parameter `str` and returns `str.c_str()`. `char_type` is `Char`.

###### When to implement

This customization point needs to be implemented whenever `traits::is_string` is implemented.

###### Related Attribute Customization Points

If this customization point is implemented, the following other customization points need to be implemented as well.

Name | When to implement
--- | ---
`traits::is_char` | For string types whose underlying character type is not `char` or `wchar_t`, `is_char` must be implemented.
`traits::is_string` | Whenever `extract_c_string` is implemented.
`traits::char_type_of` | Whenever `extract_c_string` is implemented.