/**
\defgroup fcpptstring fcppt.string
\ingroup fcpptmain
\brief String-related functions and types

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref fcpptstring_motivation</li>
	<li>\ref fcpptstring_conversions</li>
	<li>\ref fcpptstring_streams</li>
	<li>\ref fcpptstring_lexical_conversions</li>
	<li>\ref fcpptstring_exception</li>
</ul>

</td>
</tr>
</table>

\section fcpptstring_motivation Motivation

In C++ there are two main character types: <code>char</code> and
<code>wchar_t</code>. <code>char</code> is always 1 byte long, the size of
<code>wchar_t</code> is implementation-defined. In Windows, it's 2, in Linux,
it's often 4.  Consequently, there are two types of character literals: narrow
and wide literals, i.e.
\code
char const chars[] = "foobar";
wchar_t const wchars[] = L"foobar";
\endcode
Depending on the operating system, one of these character types is the "native"
one. System functions like <code>CreateFile</code> in Windows accept
<code>wchar_t</code>. In Linux, calls like <code>open</code> accept
<code>char</code>. Along with the different types go different
<em>encodings</em>. Windows uses UTF-16 for (<code>wchar_t</code>) strings such
as the file name given to <code>CreateFile</code>. Linux uses whatever encoding
the current <em>locale</em> specifies. On most systems, this is UTF-8 for
<code>char</code> strings.

When you're designing a library that frequently calls system functions, it's
most efficient to use a string format that suits the current operating system.
With that in mind, fcppt has a typedef called #fcppt::char_type.
This typedef is <code>wchar_t</code> on Windows systems and <code>char</code>
on POSIX systems. It's configurable, however, so using <code>wchar_t</code> on
POSIX is possible, too (see the <code>ENABLE_NARROW_STRING</code> CMake
option). Based on that, there's #fcppt::string which is a
<code>std::%basic_string</code> of #fcppt::char_type.

Unfortunately, making the character type configurable has some ramifications.
For example, you cannot simply write:

\code
fcppt::string s("foo");
\endcode

This will break if #fcppt::string is a wide string.  To portably
wrap literals, use the #FCPPT_TEXT macro:

\snippet string.cpp text_literal

There are other standard library structures such as <code>cout,clog,cin</code>
which you cannot reliably use together with #fcppt::string. fcppt
provides alternatives for these (see the members of the string module in the
documentation for a list of all related functions and structures).

\section fcpptstring_conversions Conversions

The following functions can be used to convert from and to strings:

<table>
<tr>
<th>Function</th>
<th>Conversion description</th>
</tr>
<tr>
<td>#fcppt::from_std_string</td>
<td><code>std::string → fcppt::string</code></td>
</tr>
<tr>
<td>#fcppt::from_std_wstring</td>
<td><code>std::wstring → fcppt::optional::object<fcppt::string></code></td>
</tr>
<tr>
<td>#fcppt::to_std_string</td>
<td><code>fcppt::string → fcppt::optional::object<std::string></code></td>
</tr>
<tr>
<td>#fcppt::to_std_wstring</td>
<td><code>fcppt::string → std::string</code></td>
</tr>
</table>

Each of the above functions uses #fcppt::string_conv_locale,
which returns <code>std::locale("")</code>.
The semantics of this locale are described, for example, in the
<code>setlocale</code> manpage. Under Linux, this leads to the inspection of
the locale environment variables (<code>LC_ALL, LANG</code> etc.). The default
locale for an application is the (rather unlocalized) "C" locale. We feel that
using the "native" locale as the default makes more sense, since the C locale
has no information about the system's native encoding. Converting <code>std::string</code>
to <code>std::wstring</code> on a typical Linux machine means converting UTF-8 to UTF-32.
The C locale, however, has no information about these encodings.
If you need to use a different locale, you can use the locale-variants:
#fcppt::from_std_string_locale, #fcppt::from_std_wstring_locale,
#fcppt::to_std_string_locale and #fcppt::to_std_wstring_locale.

Finally, here is a small example:

\snippet string_conversion.cpp string_conversion

\section fcpptstring_streams IO streams and other adaptors

To read in or write out files using the system's native character type, you can
use the typedefs in the #fcppt::io namespace, namely #fcppt::filesystem::ifstream, #fcppt::filesystem::ofstream , and so on.

There are also preprocessor macros, currently #FCPPT_PP_STRINGIZE
and #FCPPT_PP_FILE to provide compatibility with #fcppt::string. #FCPPT_PP_STRINGIZE stringizes its
argument to an #fcppt::string literal. In the same fashion, #FCPPT_PP_FILE adapts the standard macro <code>__FILE__</code> to return
an #fcppt::string literal.

\section fcpptstring_lexical_conversions Lexical Conversions

Lexical conversions deal with conversions from and to strings. In C++ this is
done using <code>operator<<</code> and <code>operator>></code>. fcppt wraps
these into the following functions:

<table>
<tr>
<th>Function</th>
<th>Description</th>
</tr>
<tr>
<td>#fcppt::extract_from_string</td>
<td><code>basic_string<CharT> → fcppt::optional::object<T></code></td>
</tr>
<tr>
<td>#fcppt::output_to_std_string</td>
<td><code>T → std::string</code></td>
</tr>
<tr>
<td>#fcppt::output_to_std_wstring</td>
<td><code>T → std::wstring</code></td>
</tr>
<tr>
<td>#fcppt::output_to_fcppt_string</td>
<td><code>T → fcppt::string</code></td>
</tr>
<tr>
<td>#fcppt::output_to_string</td>
<td><code>T → basic_string<CharT></code></td>
</tr>
</table>

\section fcpptstring_exception Exceptions

C++ offers standard exceptions in the <code>\<stdexcept\></code> header. All of
them use <code>std::string</code> which does not go well together with #fcppt::string.
fcppt instead defines its own exception base class: #fcppt::exception. Although it derives from
<code>std::exception</code>, its <code>what()</code> function returns a default
message only. To get the error message of an #fcppt::exception,
use #fcppt::exception::string.

\snippet string.cpp exception
*/
