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>
15 #include <boost/hana/fwd/core/to.hpp>
18 namespace boost { namespace hana {
19 #ifdef BOOST_HANA_DOXYGEN_INVOKED
20 //! @ingroup group-datatypes
21 //! Compile-time string.
23 //! Conceptually, a `hana::string` is like a tuple holding
24 //! `integral_constant`s of underlying type `char`. However, the
25 //! interface of `hana::string` is not as rich as that of a tuple,
26 //! because a string can only hold compile-time characters as opposed
27 //! to any kind of object.
29 //! Compile-time strings are used for simple purposes like being keys in a
30 //! `hana::map` or tagging the members of a `Struct`. However, you might
31 //! find that `hana::string` does not provide enough functionality to be
32 //! used as a full-blown compile-time string implementation (e.g. regexp
33 //! matching or substring finding). Indeed, providing a comprehensive
34 //! string interface is a lot of job, and it is out of the scope of the
35 //! library for the time being.
39 //! The representation of `hana::string` is implementation-defined.
40 //! In particular, one should not take for granted that the template
41 //! parameters are `char`s. The proper way to access the contents of
42 //! a `hana::string` as character constants is to use `hana::unpack`,
43 //! `.c_str()` or `hana::to<char const*>`, as documented below. More
44 //! details [in the tutorial](@ref tutorial-containers-types).
49 //! For most purposes, a `hana::string` is functionally equivalent to a
50 //! tuple holding `Constant`s of underlying type `char`.
53 //! Two strings are equal if and only if they have the same number of
54 //! characters and characters at corresponding indices are equal.
55 //! @include example/string/comparable.cpp
58 //! The total order implemented for `Orderable` is the usual
59 //! lexicographical comparison of strings.
60 //! @include example/string/orderable.cpp
63 //! Strings form a monoid under concatenation, with the neutral element
64 //! being the empty string.
65 //! @include example/string/monoid.cpp
68 //! Folding a string is equivalent to folding the sequence of its
70 //! @include example/string/foldable.cpp
73 //! Iterating over a string is equivalent to iterating over the sequence
74 //! of its characters. Also note that `operator[]` can be used instead of
75 //! the `at` function.
76 //! @include example/string/iterable.cpp
79 //! Searching through a string is equivalent to searching through the
80 //! sequence of its characters.
81 //! @include example/string/searchable.cpp
84 //! The hash of a compile-time string is a type uniquely representing
86 //! @include example/string/hashable.cpp
89 //! Conversion to `char const*`
90 //! ---------------------------
91 //! A `hana::string` can be converted to a `constexpr` null-delimited
92 //! string of type `char const*` by using the `c_str()` method or
93 //! `hana::to<char const*>`. This makes it easy to turn a compile-time
94 //! string into a runtime string. However, note that this conversion is
95 //! not an embedding, because `char const*` does not model the same
96 //! concepts as `hana::string` does.
97 //! @include example/string/to.cpp
99 //! Conversion from any Constant holding a `char const*`
100 //! ----------------------------------------------------
101 //! A `hana::string` can be created from any `Constant` whose underlying
102 //! value is convertible to a `char const*` by using `hana::to`. The
103 //! contents of the `char const*` are used to build the content of the
105 //! @include example/string/from_c_str.cpp
107 //! Rationale for `hana::string` not being a `Constant` itself
108 //! ----------------------------------------------------------
109 //! The underlying type held by a `hana::string` could be either `char const*`
110 //! or some other constexpr-enabled string-like container. In the first case,
111 //! `hana::string` can not be a `Constant` because the models of several
112 //! concepts would not be respected by the underlying type, causing `value`
113 //! not to be structure-preserving. Providing an underlying value of
114 //! constexpr-enabled string-like container type like `std::string_view`
115 //! would be great, but that's a bit complicated for the time being.
116 template <typename implementation_defined>
118 // Default-construct a `hana::string`; no-op since `hana::string` is stateless.
119 constexpr string() = default;
121 // Copy-construct a `hana::string`; no-op since `hana::string` is stateless.
122 constexpr string(string const&) = default;
124 //! Equivalent to `hana::equal`
125 template <typename X, typename Y>
126 friend constexpr auto operator==(X&& x, Y&& y);
128 //! Equivalent to `hana::not_equal`
129 template <typename X, typename Y>
130 friend constexpr auto operator!=(X&& x, Y&& y);
132 //! Equivalent to `hana::less`
133 template <typename X, typename Y>
134 friend constexpr auto operator<(X&& x, Y&& y);
136 //! Equivalent to `hana::greater`
137 template <typename X, typename Y>
138 friend constexpr auto operator>(X&& x, Y&& y);
140 //! Equivalent to `hana::less_equal`
141 template <typename X, typename Y>
142 friend constexpr auto operator<=(X&& x, Y&& y);
144 //! Equivalent to `hana::greater_equal`
145 template <typename X, typename Y>
146 friend constexpr auto operator>=(X&& x, Y&& y);
148 //! Performs concatenation; equivalent to `hana::plus`
149 template <typename X, typename Y>
150 friend constexpr auto operator+(X&& x, Y&& y);
152 //! Equivalent to `hana::at`
153 template <typename N>
154 constexpr decltype(auto) operator[](N&& n);
156 //! Returns a null-delimited C-style string.
157 static constexpr char const* c_str();
164 //! Tag representing a compile-time string.
165 //! @relates hana::string
166 struct string_tag { };
168 #ifdef BOOST_HANA_DOXYGEN_INVOKED
169 //! Create a compile-time `hana::string` from a parameter pack of `char`
170 //! `integral_constant`s.
171 //! @relates hana::string
173 //! Given zero or more `integral_constant`s of underlying type `char`,
174 //! `make<string_tag>` creates a `hana::string` containing those characters.
175 //! This is provided mostly for consistency with the rest of the library,
176 //! as `hana::string_c` is more convenient to use in most cases.
181 //! @include example/string/make.cpp
183 constexpr auto make<string_tag> = [](auto&& ...chars) {
184 return string<implementation_defined>{};
188 //! Alias to `make<string_tag>`; provided for convenience.
189 //! @relates hana::string
190 BOOST_HANA_INLINE_VARIABLE constexpr auto make_string = make<string_tag>;
192 //! Equivalent to `to<string_tag>`; provided for convenience.
193 //! @relates hana::string
194 BOOST_HANA_INLINE_VARIABLE constexpr auto to_string = to<string_tag>;
196 //! Create a compile-time string from a parameter pack of characters.
197 //! @relates hana::string
202 //! @include example/string/string_c.cpp
203 #ifdef BOOST_HANA_DOXYGEN_INVOKED
205 constexpr string<implementation_defined> string_c{};
208 BOOST_HANA_INLINE_VARIABLE constexpr string<s...> string_c{};
211 //! Create a compile-time string from a string literal.
212 //! @relates hana::string
214 //! This macro is a more convenient alternative to `string_c` for creating
215 //! compile-time strings. However, since this macro uses a lambda
216 //! internally, it can't be used in an unevaluated context, or where
217 //! a constant expression is expected before C++17.
222 //! @include example/string/macro.cpp
223 #ifdef BOOST_HANA_DOXYGEN_INVOKED
224 auto BOOST_HANA_STRING(s) = see documentation;
225 #define BOOST_HANA_STRING(s) see documentation
228 // The trick above seems to exploit a bug in Doxygen, which makes the
229 // BOOST_HANA_STRING macro appear in the related objects of hana::string
230 // (as we want it to).
232 // defined in <boost/hana/string.hpp>
235 #ifdef BOOST_HANA_CONFIG_ENABLE_STRING_UDL
237 //! Creates a compile-time string from a string literal.
238 //! @relatesalso boost::hana::string
240 //! The string literal is parsed at compile-time and the result is
241 //! returned as a `hana::string`. This feature is an extension that
242 //! is disabled by default; see below for details.
245 //! Only narrow string literals are supported right now; support for
246 //! fancier types of string literals like wide or UTF-XX might be
247 //! added in the future if there is a demand for it. See [this issue]
248 //! [Hana.issue80] if you need this.
251 //! This user-defined literal is an extension which requires a special
252 //! string literal operator that is not part of the standard yet.
253 //! That operator is supported by both Clang and GCC, and several
254 //! proposals were made for it to enter C++17. However, since it is
255 //! not standard, it is disabled by default and defining the
256 //! `BOOST_HANA_CONFIG_ENABLE_STRING_UDL` config macro is required
257 //! to get this operator. Hence, if you want to stay safe, just use
258 //! the `BOOST_HANA_STRING` macro instead. If you want to be fast and
259 //! furious (I do), define `BOOST_HANA_CONFIG_ENABLE_STRING_UDL`.
264 //! @include example/string/literal.cpp
266 //! [Hana.issue80]: https://github.com/boostorg/hana/issues/80
267 template <typename CharT, CharT ...s>
268 constexpr auto operator"" _s();
271 }} // end namespace boost::hana
273 #endif // !BOOST_HANA_FWD_STRING_HPP