Boost.Hana  1.5.0
Your standard library for metaprogramming
boost::hana::string< implementation_defined > Struct Template Reference

Description

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

Compile-time string.

Conceptually, a hana::string is like a tuple holding integral_constants 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 chars. 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. More details in the tutorial.

Modeled concepts

For most purposes, a hana::string is functionally equivalent to a tuple holding Constants 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)
    namespace hana = boost::hana;
    int main() {
    BOOST_HANA_STRING("abcdef") == BOOST_HANA_STRING("abcdef")
    );
    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)
    namespace hana = boost::hana;
    int main() {
    );
    );
    }
  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)
    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)
    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>;
    });
    };
    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)
    namespace hana = boost::hana;
    int main() {
    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");
    };
    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)
    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")));
    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)
    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.
    ));
    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)
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)
namespace hana = boost::hana;
constexpr char const hello[] = "hello";
auto hello_constant = hana::integral_constant<char const*, hello>{};
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_constants. 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_constants.

Given zero or more integral_constants 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)
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>);
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)
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, or where a constant expression is expected before C++17.

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)
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)
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() { }