Boost.Hana: boost::hana::string< implementation_defined > Struct Template Reference

| Boost.Hana 1.4.0 Your standard library for metaprogramming |

Synopsis of associated functions | Friends | Public Member Functions | Static Public Member Functions | List of all members
boost::hana::string< implementation_defined > Struct Template Reference
Data types

## Description

### template<typename implementation_defined>
struct boost::hana::string< implementation_defined >

Compile-time string.

Conceptually, a `hana::string` is like a tuple holding `integral_constant`s of underlying type `char`. However, the interface of `hana::string` is not as rich as that of a tuple, because a string can only hold compile-time characters as opposed to any kind of object.

Compile-time strings are used for simple purposes like being keys in a `hana::map` or tagging the members of a `Struct`. However, you might find that `hana::string` does not provide enough functionality to be used as a full-blown compile-time string implementation (e.g. regexp matching or substring finding). Indeed, providing a comprehensive string interface is a lot of job, and it is out of the scope of the library for the time being.

Note
  The representation of `hana::string` is implementation-defined. In particular, one should not take for granted that the template parameters are `char`s. The proper way to access the contents of a `hana::string` as character constants is to use `hana::unpack`, `.c_str()` or `hana::to<char const*>`, as documented below.

## Modeled concepts

For most purposes, a `hana::string` is functionally equivalent to a tuple holding `Constant`s of underlying type `char`.

1. `Comparable`
   Two strings are equal if and only if they have the same number of characters and characters at corresponding indices are equal.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/not_equal.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   int main() {
   BOOST_HANA_CONSTANT_CHECK(
   BOOST_HANA_STRING("abcdef") == BOOST_HANA_STRING("abcdef")
   );
   BOOST_HANA_CONSTANT_CHECK(
   BOOST_HANA_STRING("abcdef") != BOOST_HANA_STRING("abef")
   );
   }
2. `Orderable`
   The total order implemented for `Orderable` is the usual lexicographical comparison of strings.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/greater.hpp>
   #include <boost/hana/less.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   int main() {
   BOOST_HANA_CONSTANT_CHECK(
   BOOST_HANA_STRING("abc") < BOOST_HANA_STRING("bcd")
   );
   BOOST_HANA_CONSTANT_CHECK(
   BOOST_HANA_STRING("abcd") > BOOST_HANA_STRING("abc")
   );
   }
3. `Monoid`
   Strings form a monoid under concatenation, with the neutral element being the empty string.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/plus.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   auto hello_world = BOOST_HANA_STRING("Hello ") + BOOST_HANA_STRING("world!");
   BOOST_HANA_CONSTANT_CHECK(hello_world == BOOST_HANA_STRING("Hello world!"));
   int main() { }
4. `Foldable`
   Folding a string is equivalent to folding the sequence of its characters.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/equal.hpp>
   #include <boost/hana/fold_left.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/plus.hpp>
   #include <boost/hana/string.hpp>
   #include <boost/hana/value.hpp>
   namespace hana = boost::hana;
   int main() {
   auto sum_string = [](auto str) {
   return hana::fold_left(str, hana::int_c<0>, [](auto sum, auto c) {
   constexpr int i = hana::value(c) - 48; // convert character to decimal
   return sum + hana::int_c<i>;
   });
   };
   BOOST_HANA_CONSTANT_CHECK(
   sum_string(BOOST_HANA_STRING("1234")) == hana::int_c<1 + 2 + 3 + 4>
   );
   }
5. `Iterable`
   Iterating over a string is equivalent to iterating over the sequence of its characters. Also note that `operator[]` can be used instead of the `at` function.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/contains.hpp>
   #include <boost/hana/drop_while.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/is_empty.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   int main() {
   BOOST_HANA_CONSTANT_CHECK(!hana::is_empty(BOOST_HANA_STRING("abcd")));
   BOOST_HANA_CONSTANT_CHECK(hana::is_empty(BOOST_HANA_STRING("")));
   BOOST_HANA_CONSTANT_CHECK(BOOST_HANA_STRING("abcd")[hana::size_c<2>] == hana::char_c<'c'>);
   auto is_vowel = [](auto c) {
   return c ^hana::in^ BOOST_HANA_STRING("aeiouy");
   };
   BOOST_HANA_CONSTANT_CHECK(
   hana::drop_while(BOOST_HANA_STRING("aioubcd"), is_vowel) == BOOST_HANA_STRING("bcd")
   );
   }
6. `Searchable`
   Searching through a string is equivalent to searching through the sequence of its characters.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/contains.hpp>
   #include <boost/hana/find.hpp>
   #include <boost/hana/integral_constant.hpp>
   #include <boost/hana/optional.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   int main() {
   BOOST_HANA_CONSTANT_CHECK(hana::char_c<'c'> ^hana::in^ BOOST_HANA_STRING("abcde"));
   BOOST_HANA_CONSTANT_CHECK(!(hana::char_c<'z'> ^hana::in^ BOOST_HANA_STRING("abcde")));
   BOOST_HANA_CONSTANT_CHECK(
   hana::find(BOOST_HANA_STRING("abcxefg"), hana::char_c<'x'>) == hana::just(hana::char_c<'x'>)
   );
   }
7. `Hashable`
   The hash of a compile-time string is a type uniquely representing that string.
   // Copyright Louis Dionne 2013-2017
   // Distributed under the Boost Software License, Version 1.0.
   // (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   #include <boost/hana/assert.hpp>
   #include <boost/hana/hash.hpp>
   #include <boost/hana/not_equal.hpp>
   #include <boost/hana/string.hpp>
   namespace hana = boost::hana;
   // `hana::hash` returns a type uniquely representing the string. The hash is
   // perfect, meaning no two different strings have the same hash value.
   BOOST_HANA_CONSTANT_CHECK(hana::not_equal(
   hana::hash(BOOST_HANA_STRING("abcdef")),
   hana::hash(BOOST_HANA_STRING("abcdefg"))
   ));
   int main() { }

## Conversion to `char const*`

A `hana::string` can be converted to a `constexpr` null-delimited string of type `char const*` by using the `c_str()` method or `hana::to<char const*>`. This makes it easy to turn a compile-time string into a runtime string. However, note that this conversion is not an embedding, because `char const*` does not model the same concepts as `hana::string` does.

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/to.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
constexpr auto str = hana::string_c<'h', 'i'>;
// using c_str()
constexpr char const* s1 = str.c_str();
static_assert(s1[0] == 'h' && s1[1] == 'i' && s1[2] == '\0', "");
// using hana::to
constexpr char const* s2 = hana::to<char const*>(str);
static_assert(s2[0] == 'h' && s2[1] == 'i' && s2[2] == '\0', "");
int main() { }

## Conversion from any Constant holding a `char const*`

A `hana::string` can be created from any `Constant` whose underlying value is convertible to a `char const*` by using `hana::to`. The contents of the `char const*` are used to build the content of the `hana::string`.

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/to.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
constexpr char const hello[] = "hello";
auto hello_constant = hana::integral_constant<char const*, hello>{};
BOOST_HANA_CONSTANT_CHECK(
hana::to_string(hello_constant) == hana::string_c<'h', 'e', 'l', 'l', 'o'>
);
int main() { }

## Rationale for `hana::string` not being a `Constant` itself

The underlying type held by a `hana::string` could be either `char const*` or some other constexpr-enabled string-like container. In the first case, `hana::string` can not be a `Constant` because the models of several concepts would not be respected by the underlying type, causing `value` not to be structure-preserving. Providing an underlying value of constexpr-enabled string-like container type like `std::string_view` would be great, but that's a bit complicated for the time being.

## Synopsis of associated functions
template<>
constexpr auto | make< string_tag >
| Create a compile-time `hana::string` from a parameter pack of `char` `integral_constant`s. More...
constexpr auto | make_string = make<string_tag>
| Alias to `make<string_tag>`; provided for convenience. More...
constexpr auto | to_string = to<string_tag>
| Equivalent to `to<string_tag>`; provided for convenience. More...
template<char... s>
constexpr string< implementation_defined > | string_c {}
| Create a compile-time string from a parameter pack of characters. More...
#define | BOOST_HANA_STRING(s) see documentation
| Create a compile-time string from a string literal. More...
template<typename CharT , CharT... s>
constexpr auto | operator""_s ()
| Creates a compile-time string from a string literal. More...

## Friends
template<typename X , typename Y >
constexpr auto | operator== (X &&x, Y &&y)
| Equivalent to `hana::equal`
template<typename X , typename Y >
constexpr auto | operator!= (X &&x, Y &&y)
| Equivalent to `hana::not_equal`
template<typename X , typename Y >
constexpr auto | operator< (X &&x, Y &&y)
| Equivalent to `hana::less`
template<typename X , typename Y >
constexpr auto | operator> (X &&x, Y &&y)
| Equivalent to `hana::greater`
template<typename X , typename Y >
constexpr auto | operator<= (X &&x, Y &&y)
| Equivalent to `hana::less_equal`
template<typename X , typename Y >
constexpr auto | operator>= (X &&x, Y &&y)
| Equivalent to `hana::greater_equal`
template<typename X , typename Y >
constexpr auto | operator+ (X &&x, Y &&y)
| Performs concatenation; equivalent to `hana::plus`

## Public Member Functions
template<typename N >
decltype(auto) constexpr | operator[] (N &&n)
| Equivalent to `hana::at`

## Static Public Member Functions
static constexpr char const * | c_str ()
| Returns a null-delimited C-style string.

## Associated functions

template<typename implementation_defined >
template<>

constexpr auto make< string_tag >
| related

Initial value:
= [](auto&& ...chars) {
return string<implementation_defined>{};
}

Create a compile-time `hana::string` from a parameter pack of `char` `integral_constant`s.

Given zero or more `integral_constant`s of underlying type `char`, `make<string_tag>` creates a `hana::string` containing those characters. This is provided mostly for consistency with the rest of the library, as `hana::string_c` is more convenient to use in most cases.

## Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/string.hpp>
#include <boost/hana/tuple.hpp>
#include <boost/hana/unpack.hpp>
namespace hana = boost::hana;
constexpr auto vowels = hana::tuple_c<char, 'a', 'e', 'i', 'o', 'u', 'y'>;
constexpr auto str = hana::unpack(vowels, hana::make<hana::string_tag>);
BOOST_HANA_CONSTANT_CHECK(str == BOOST_HANA_STRING("aeiouy"));
int main() { }
template<typename implementation_defined >

constexpr auto make_string = make<string_tag>
| related

Alias to `make<string_tag>`; provided for convenience.

template<typename implementation_defined >

constexpr auto to_string = to<string_tag>
| related

Equivalent to `to<string_tag>`; provided for convenience.

template<typename implementation_defined >
template<char... s>

constexpr string<implementation_defined> string_c {}
| related

Create a compile-time string from a parameter pack of characters.

## Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
constexpr auto str = hana::string_c<'a', 'b', 'c', 'd', 'e', 'f'>;
BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));
int main() { }
template<typename implementation_defined >

#define BOOST_HANA_STRING | ( |  | s | ) | see documentation
| related

Create a compile-time string from a string literal.

This macro is a more convenient alternative to `string_c` for creating compile-time strings. However, since this macro uses a lambda internally, it can't be used in an unevaluated context.

## Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/config.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
int main() {
BOOST_HANA_CONSTEXPR_LAMBDA auto str = BOOST_HANA_STRING("abcdef");
BOOST_HANA_CONSTANT_CHECK(str == hana::string_c<'a', 'b', 'c', 'd', 'e', 'f'>);
BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));
}
template<typename CharT , CharT... s>

constexpr auto operator""_s | ( |  | ) |
| related

Creates a compile-time string from a string literal.

The string literal is parsed at compile-time and the result is returned as a `hana::string`. This feature is an extension that is disabled by default; see below for details.

Note
  Only narrow string literals are supported right now; support for fancier types of string literals like wide or UTF-XX might be added in the future if there is a demand for it. See this issue if you need this.

Warning
  This user-defined literal is an extension which requires a special string literal operator that is not part of the standard yet. That operator is supported by both Clang and GCC, and several proposals were made for it to enter C++17. However, since it is not standard, it is disabled by default and defining the `BOOST_HANA_CONFIG_ENABLE_STRING_UDL` config macro is required to get this operator. Hence, if you want to stay safe, just use the `BOOST_HANA_STRING` macro instead. If you want to be fast and furious (I do), define `BOOST_HANA_CONFIG_ENABLE_STRING_UDL`.

## Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <boost/hana/assert.hpp>
#include <boost/hana/config.hpp>
#include <boost/hana/core/is_a.hpp>
#include <boost/hana/equal.hpp>
#include <boost/hana/integral_constant.hpp>
#include <boost/hana/length.hpp>
#include <boost/hana/string.hpp>
namespace hana = boost::hana;
using namespace hana::literals;
// By default, this is disabled
#ifdef BOOST_HANA_CONFIG_ENABLE_STRING_UDL
constexpr auto str = "Hello world!"_s;
BOOST_HANA_CONSTANT_CHECK(str == hana::string_c<'H', 'e', 'l', 'l', 'o', ' ',
'w', 'o', 'r', 'l', 'd', '!'>);
BOOST_HANA_CONSTANT_CHECK(hana::is_a<hana::string_tag>(str));
BOOST_HANA_CONSTANT_CHECK(hana::length(str) == hana::size_c<12>);
#endif
int main() { }