Boost.Hana  1.7.1
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")
    );
    }
    Defines macros to perform different kinds of assertions.
    Defines boost::hana::equal.
    #define BOOST_HANA_CONSTANT_CHECK(...)
    Equivalent to BOOST_HANA_CONSTANT_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERTI...
    Definition: assert.hpp:239
    Namespace containing everything in the library.
    Definition: accessors.hpp:20
    Defines boost::hana::not_equal.
    Defines boost::hana::string.
    #define BOOST_HANA_STRING(s)
    Create a compile-time string from a string literal.
    Definition: string.hpp:225
  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() {
    );
    );
    }
    Defines boost::hana::greater.
    Defines boost::hana::less.
  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() { }
    Defines boost::hana::plus.
  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>
    );
    }
    Defines boost::hana::fold_left.
    constexpr auto value
    Return the compile-time value associated to a constant.
    Definition: value.hpp:54
    constexpr auto sum
    Compute the sum of the numbers of a structure.
    Definition: sum.hpp:66
    Defines boost::hana::integral_constant.
    Defines boost::hana::value.
  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")
    );
    }
    Defines boost::hana::contains and boost::hana::in.
    Defines boost::hana::drop_while.
    constexpr auto is_empty
    Returns whether the iterable is empty.
    Definition: is_empty.hpp:33
    constexpr auto drop_while
    Drop elements from an iterable up to, but excluding, the first element for which the predicate is not...
    Definition: drop_while.hpp:44
    constexpr auto in
    Return whether the key occurs in the structure.
    Definition: contains.hpp:70
    Defines boost::hana::is_empty.
  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'>)
    );
    }
    Defines boost::hana::find.
    constexpr auto find
    Finds the value associated to the given key in a structure.
    Definition: find.hpp:44
    Defines boost::hana::optional.
  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.
    hana::hash(BOOST_HANA_STRING("abcdef")),
    hana::hash(BOOST_HANA_STRING("abcdefg"))
    ));
    int main() { }
    constexpr auto not_equal
    Returns a Logical representing whether x is not equal to y.
    Definition: not_equal.hpp:54
    Defines boost::hana::hash.

Conversion to <tt>char const*</tt>

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() { }
Defines boost::hana::to and related utilities.

Conversion from any Constant holding a <tt>char const*</tt>

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 <tt>hana::string</tt> not being a <tt>Constant</tt> 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.
 
constexpr auto to_string = to<string_tag>
 Equivalent to to<string_tag>; provided for convenience.
 
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 friend auto operator== (X &&x, Y &&y)
 Equivalent to hana::equal
 
template<typename X , typename Y >
constexpr friend auto operator!= (X &&x, Y &&y)
 Equivalent to hana::not_equal
 
template<typename X , typename Y >
constexpr friend auto operator< (X &&x, Y &&y)
 Equivalent to hana::less
 
template<typename X , typename Y >
constexpr friend auto operator> (X &&x, Y &&y)
 Equivalent to hana::greater
 
template<typename X , typename Y >
constexpr friend auto operator<= (X &&x, Y &&y)
 Equivalent to hana::less_equal
 
template<typename X , typename Y >
constexpr friend auto operator>= (X &&x, Y &&y)
 Equivalent to hana::greater_equal
 
template<typename X , typename Y >
constexpr friend auto operator+ (X &&x, Y &&y)
 Performs concatenation; equivalent to hana::plus
 

Public Member Functions

template<typename N >
constexpr decltype(auto) 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

◆ make< string_tag >

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() { }
constexpr auto unpack
Invoke a function with the elements of a Foldable as arguments.
Definition: unpack.hpp:79
Defines boost::hana::tuple.
Defines boost::hana::unpack.

◆ string_c

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() { }
Defines boost::hana::is_a and boost::hana::is_an.

◆ BOOST_HANA_STRING

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));
}
Defines configuration macros used throughout the library.

◆ operator""_s()

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() { }
constexpr auto length
Return the number of elements in a foldable structure.
Definition: length.hpp:34
Defines boost::hana::length.

References boost::hana::value.