3 Forward declares `boost::hana::string`.
5 @copyright Louis Dionne 2013-2017
6 Distributed under the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
10 #ifndef BOOST_HANA_FWD_STRING_HPP
11 #define BOOST_HANA_FWD_STRING_HPP
13 #include <boost/hana/config.hpp>
14 #include <boost/hana/fwd/core/make.hpp>
17 BOOST_HANA_NAMESPACE_BEGIN
18 #ifdef BOOST_HANA_DOXYGEN_INVOKED
19 //! @ingroup group-datatypes
20 //! Compile-time string.
22 //! Conceptually, a `hana::string` is like a tuple holding
23 //! `integral_constant`s of underlying type `char`. However, the
24 //! interface of `hana::string` is not as rich as that of a tuple,
25 //! because a string can only hold compile-time characters as opposed
26 //! to any kind of object.
28 //! Compile-time strings are used for simple purposes like being keys in a
29 //! `hana::map` or tagging the members of a `Struct`. However, you might
30 //! find that `hana::string` does not provide enough functionality to be
31 //! used as a full-blown compile-time string implementation (e.g. regexp
32 //! matching or substring finding). Indeed, providing a comprehensive
33 //! string interface is a lot of job, and it is out of the scope of the
34 //! library for the time being.
38 //! The representation of `hana::string` is implementation-defined.
39 //! In particular, one should not take for granted that the template
40 //! parameters are `char`s. The proper way to access the contents of
41 //! a `hana::string` as character constants is to use `hana::unpack`,
42 //! `.c_str()` or `hana::to<char const*>`, as documented below.
47 //! For most purposes, a `hana::string` is functionally equivalent to a
48 //! tuple holding `Constant`s of underlying type `char`.
51 //! Two strings are equal if and only if they have the same number of
52 //! characters and characters at corresponding indices are equal.
53 //! @include example/string/comparable.cpp
56 //! The total order implemented for `Orderable` is the usual
57 //! lexicographical comparison of strings.
58 //! @include example/string/orderable.cpp
61 //! Strings form a monoid under concatenation, with the neutral element
62 //! being the empty string.
63 //! @include example/string/monoid.cpp
66 //! Folding a string is equivalent to folding the sequence of its
68 //! @include example/string/foldable.cpp
71 //! Iterating over a string is equivalent to iterating over the sequence
72 //! of its characters. Also note that `operator[]` can be used instead of
73 //! the `at` function.
74 //! @include example/string/iterable.cpp
77 //! Searching through a string is equivalent to searching through the
78 //! sequence of its characters.
79 //! @include example/string/searchable.cpp
82 //! The hash of a compile-time string is a type uniquely representing
84 //! @include example/string/hashable.cpp
87 //! Conversion to `char const*`
88 //! ---------------------------
89 //! A `hana::string` can be converted to a `constexpr` null-delimited
90 //! string of type `char const*` by using the `c_str()` method or
91 //! `hana::to<char const*>`. This makes it easy to turn a compile-time
92 //! string into a runtime string. However, note that this conversion is
93 //! not an embedding, because `char const*` does not model the same
94 //! concepts as `hana::string` does.
95 //! @include example/string/to.cpp
98 //! > #### Rationale for `hana::string` not being a `Constant`
99 //! > The underlying type held by a `hana::string` could be either
100 //! > `char const*` or some other constexpr-enabled string-like container.
101 //! > In the first case, `hana::string` can not be a `Constant` because
102 //! > the models of several concepts would not be respected by the
103 //! > underlying type, causing `value` not to be structure-preserving.
104 //! > Providing an underlying value of constexpr-enabled string-like
105 //! > container type like `std::string_view` would be great, but that's
106 //! > a bit complicated for the time being.
107 template <typename implementation_defined>
109 // Default-construct a `hana::string`; no-op since `hana::string` is stateless.
110 constexpr string() = default;
112 // Copy-construct a `hana::string`; no-op since `hana::string` is stateless.
113 constexpr string(string const&) = default;
115 //! Equivalent to `hana::equal`
116 template <typename X, typename Y>
117 friend constexpr auto operator==(X&& x, Y&& y);
119 //! Equivalent to `hana::not_equal`
120 template <typename X, typename Y>
121 friend constexpr auto operator!=(X&& x, Y&& y);
123 //! Equivalent to `hana::less`
124 template <typename X, typename Y>
125 friend constexpr auto operator<(X&& x, Y&& y);
127 //! Equivalent to `hana::greater`
128 template <typename X, typename Y>
129 friend constexpr auto operator>(X&& x, Y&& y);
131 //! Equivalent to `hana::less_equal`
132 template <typename X, typename Y>
133 friend constexpr auto operator<=(X&& x, Y&& y);
135 //! Equivalent to `hana::greater_equal`
136 template <typename X, typename Y>
137 friend constexpr auto operator>=(X&& x, Y&& y);
139 //! Performs concatenation; equivalent to `hana::plus`
140 template <typename X, typename Y>
141 friend constexpr auto operator+(X&& x, Y&& y);
143 //! Equivalent to `hana::at`
144 template <typename N>
145 constexpr decltype(auto) operator[](N&& n);
147 //! Returns a null-delimited C-style string.
148 static constexpr char const* c_str();
155 //! Tag representing a compile-time string.
156 //! @relates hana::string
157 struct string_tag { };
159 #ifdef BOOST_HANA_DOXYGEN_INVOKED
160 //! Create a compile-time `hana::string` from a parameter pack of `char`
161 //! `integral_constant`s.
162 //! @relates hana::string
164 //! Given zero or more `integral_constant`s of underlying type `char`,
165 //! `make<string_tag>` creates a `hana::string` containing those characters.
166 //! This is provided mostly for consistency with the rest of the library,
167 //! as `hana::string_c` is more convenient to use in most cases.
172 //! @include example/string/make.cpp
174 constexpr auto make<string_tag> = [](auto&& ...chars) {
175 return string<implementation_defined>{};
179 //! Alias to `make<string_tag>`; provided for convenience.
180 //! @relates hana::string
181 constexpr auto make_string = make<string_tag>;
183 //! Create a compile-time string from a parameter pack of characters.
184 //! @relates hana::string
189 //! @include example/string/string_c.cpp
190 #ifdef BOOST_HANA_DOXYGEN_INVOKED
192 constexpr string<implementation_defined> string_c{};
195 constexpr string<s...> string_c{};
198 //! Create a compile-time string from a string literal.
199 //! @relates hana::string
201 //! This macro is a more convenient alternative to `string_c` for creating
202 //! compile-time strings. However, since this macro uses a lambda
203 //! internally, it can't be used in an unevaluated context.
208 //! @include example/string/macro.cpp
209 #ifdef BOOST_HANA_DOXYGEN_INVOKED
210 auto BOOST_HANA_STRING(s) = see documentation;
211 #define BOOST_HANA_STRING(s) see documentation
214 // The trick above seems to exploit a bug in Doxygen, which makes the
215 // BOOST_HANA_STRING macro appear in the related objects of hana::string
216 // (as we want it to).
218 // defined in <boost/hana/string.hpp>
221 #ifdef BOOST_HANA_CONFIG_ENABLE_STRING_UDL
223 //! Creates a compile-time string from a string literal.
224 //! @relatesalso boost::hana::string
226 //! The string literal is parsed at compile-time and the result is
227 //! returned as a `hana::string`. This feature is an extension that
228 //! is disabled by default; see below for details.
231 //! Only narrow string literals are supported right now; support for
232 //! fancier types of string literals like wide or UTF-XX might be
233 //! added in the future if there is a demand for it. See [this issue]
234 //! [Hana.issue80] if you need this.
237 //! This user-defined literal is an extension which requires a special
238 //! string literal operator that is not part of the standard yet.
239 //! That operator is supported by both Clang and GCC, and several
240 //! proposals were made for it to enter C++17. However, since it is
241 //! not standard, it is disabled by default and defining the
242 //! `BOOST_HANA_CONFIG_ENABLE_STRING_UDL` config macro is required
243 //! to get this operator. Hence, if you want to stay safe, just use
244 //! the `BOOST_HANA_STRING` macro instead. If you want to be fast and
245 //! furious (I do), define `BOOST_HANA_CONFIG_ENABLE_STRING_UDL`.
250 //! @include example/string/literal.cpp
252 //! [Hana.issue80]: https://github.com/boostorg/hana/issues/80
253 template <typename CharT, CharT ...s>
254 constexpr auto operator"" _s();
257 BOOST_HANA_NAMESPACE_END
259 #endif // !BOOST_HANA_FWD_STRING_HPP