2.6.0
Freundlich's C++ toolkit
Classes | Macros | Typedefs | Functions
fcppt.string

Description

String-related functions and types.

Motivation

In C++ there are two main character types: char and wchar_t. char is always 1 byte long, the size of wchar_t 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, as such:

char const chars[] = "foobar";
wchar_t const wchars[] = L"foobar";

Depending on the operating system, one of these character types is the "native" one. System functions like CreateFile in Windows accept wchar_t. In Linux, calls like open accept char. Along with the different types go different encodings. Windows uses UTF-16 for (wchar_t) strings such as the file name given to CreateFile. Linux uses whatever encoding the current locale specifies. On most systems, this is UTF-8 for char 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 wchar_t on Windows systems and char on POSIX systems. It's configurable, however, so using wchar_t on POSIX is possible, too (see the ENABLE_NARROW_STRING cmake option). Based on that, there's fcppt::string which is a std::basic_string.

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

fcppt::string s("foo");

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

There are other standard library structures such as cout,clog,cin 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).

Conversions

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

Function Conversion description
fcppt::from_std_string std::string → fcppt::string using fcppt::string_conv_locale
fcppt::from_std_string_locale std::string → fcppt::string using the specified locale
fcppt::from_std_wstring std::wstring → fcppt::string using fcppt::string_conv_locale
fcppt::from_std_wstring_locale std::wstring → fcppt::string using the specified locale
fcppt::to_std_string fcppt::string → std::string using fcppt::string_conv_locale
fcppt::to_std_wstring fcppt::string → std::string using fcppt::string_conv_locale

The function fcppt::string_conv_locale returns std::locale(""). The semantics of this locale are described, for example, in the setlocale manpage. Under Linux, this leads to the inspection of the locale environment variables (LC_ALL, LANG 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 std::string to std::wstring on a typical Linux machine means converting UTF-8 to UTF-32. The C locale, however, has no information about these encodings, so it cannot work properly.

Note that fcppt::string is not intended to be used "between" platforms. Writing an fcppt::string to a file (see below) on a Linux machine and reading it back in on a Windows machine probably does not work.

Here is a small exmaple:

#include <fcppt/from_std_string.hpp>
#include <fcppt/string.hpp>
#include <fcppt/text.hpp>
#include <fcppt/to_std_string.hpp>
#include <fcppt/to_std_wstring.hpp>
#include <fcppt/io/cout.hpp>
#include <fcppt/config/external_begin.hpp>
#include <iostream>
#include <ostream>
#include <fcppt/config/external_end.hpp>
int
main()
{
fcppt::string const s(
FCPPT_TEXT("test")
);
std::string const converted(
);
std::cout << converted << '\n';
<< fcppt::from_std_string(converted)
<< FCPPT_TEXT('\n');
std::wcout
<< L'\n';
}

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. Note that these are not typedefs to the standard library streams, but to boost::filesystem streams. These streams take a filesystem path object in the constructor instead of a const char *.

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 __FILE__ to return an fcppt::string literal.

Lexical Conversions

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

Function Description
fcppt::extract_from_string basic_string<CharT> → fcppt::optional::object<T>
fcppt::insert_to_std_string T → std::string
fcppt::insert_to_std_wstring T → std::wstring
fcppt::insert_to_fcppt_string T → fcppt::string
fcppt::insert_to_string T → basic_string<CharT>

Exceptions

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

try
{
something();
}
catch(
fcppt::exception const &_error
)
{
fcppt::io::cerr() << _error.string() << FCPPT_TEXT('\n');
}

Classes

class  fcppt::exception
 The base class for all exceptions. More...
 

Macros

#define FCPPT_TEXT(x)   FCPPT_DETAIL_TEXT(x)
 A macro to wrap a narrow character literal so it results in a fcppt::char_type[] array.See the string module description for more information. More...
 

Typedefs

typedef fcppt::detail::char_type fcppt::char_type
 The char_type used for text.See the string module description for more information. More...
 
typedef boost::basic_format< fcppt::char_typefcppt::format
 A fcppt::char_type typedef for boost.formatSee the string module description for more information about fcppt::char_type. More...
 
typedef std::basic_istream< fcppt::char_typefcppt::io::istream
 Typedef to either std::istream or std::wistream, depending on fcppt::char_type. More...
 
typedef std::basic_istringstream< fcppt::char_typefcppt::io::istringstream
 Typedef to either std::istringstream or std::wistringstream, depending on fcppt::char_type. More...
 
typedef std::basic_ostream< fcppt::char_typefcppt::io::ostream
 Typedef to either std::ostream or std::wostream, depending on fcppt::char_type. More...
 
typedef std::basic_ostringstream< fcppt::char_typefcppt::io::ostringstream
 Typedef to either std::ostringstream or std::wostringstream, depending on fcppt::char_type. More...
 
typedef std::basic_stringstream< fcppt::char_typefcppt::io::stringstream
 Typedef to either std::stringstream or std::wstringstream, depending on fcppt::char_type. More...
 
typedef fcppt::optional::object< std::string > fcppt::optional_std_string
 An optional std string. More...
 
typedef fcppt::optional::object< fcppt::stringfcppt::optional_string
 An optional string. More...
 
typedef std::basic_string< fcppt::char_typefcppt::string
 The string type used for text. More...
 
typedef std::basic_fstream< fcppt::char_typefcppt::filesystem::fstream
 Typedef to basic_fstream, depending on fcppt::char_type. More...
 
typedef std::basic_ifstream< fcppt::char_typefcppt::filesystem::ifstream
 Typedef to basic_ifstream, depending on fcppt::char_type. More...
 
typedef std::basic_ofstream< fcppt::char_typefcppt::filesystem::ofstream
 Typedef to basic_ofstream, depending on fcppt::char_type. More...
 

Functions

fcppt::string fcppt::error::strerrno ()
 A wrapper around std::strerror(strerrno) More...
 
fcppt::string fcppt::error::strerror (int errnum)
 A wrapper around std::strerror More...
 
template<typename Dest , typename Source >
fcppt::optional::object< Dest > fcppt::extract_from_string (Source const &_source, std::locale const &_locale=std::locale())
 Convert a string to a different type using a locale. More...
 
fcppt::string fcppt::from_std_string (std::string const &)
 Convert from std::string to fcppt::string using fcppt::string_conv_localeSee the string module description for more information about this function. More...
 
fcppt::string fcppt::from_std_string_locale (std::string const &, std::locale const &)
 Convert from std::string to fcppt::string using a custom localeSee the string module description for more information about this function. More...
 
fcppt::string fcppt::from_std_wstring (std::wstring const &)
 Convert from std::wstring to fcppt::string using fcppt::string_conv_localeSee the string module description for more information about this function. More...
 
fcppt::string fcppt::from_std_wstring_locale (std::wstring const &, std::locale const &)
 Convert from std::wstring to fcppt::string using a custom localeSee the string module description for more information about this function. More...
 
template<typename Source >
fcppt::string fcppt::insert_to_fcppt_string (Source const &_source, std::locale const &_locale=std::locale())
 Convert an arbitrary type to a fcppt::string. More...
 
template<typename Source >
std::string fcppt::insert_to_std_string (Source const &_source, std::locale const &_locale=std::locale())
 Convert an arbitrary type to a std::string. More...
 
template<typename Source >
std::wstring fcppt::insert_to_std_wstring (Source const &_source, std::locale const &_locale=std::locale())
 Convert an arbitrary type to a std::wstring. More...
 
template<typename Dest , typename Source >
Dest fcppt::insert_to_string (Source const &_source, std::locale const &_locale=std::locale())
 Convert an arbitrary type to a string. More...
 
fcppt::io::ostreamfcppt::io::cerr ()
 Returns either std::cerr or std::wcerr, depending on fcppt::char_type. More...
 
fcppt::io::istreamfcppt::io::cin ()
 Returns either std::cin or std::wcin, depending on fcppt::char_type. More...
 
fcppt::io::ostreamfcppt::io::clog ()
 Returns either std::clog or std::wclog, depending on fcppt::char_type. More...
 
fcppt::io::ostreamfcppt::io::cout ()
 Returns either std::cout or std::wcout, depending on fcppt::char_type. More...
 
template<typename Ch , typename Traits >
std::basic_string< Ch, Traits > fcppt::io::stream_to_string (std::basic_istream< Ch, Traits > &_stream)
 Converts the contents of a stream to a string. More...
 
std::string fcppt::narrow (std::wstring const &_string, std::locale const &_locale=fcppt::string_conv_locale())
 Converts a std::wstring to std::string. More...
 
std::locale fcppt::string_conv_locale ()
 Returns the default locale to use when converting strings. More...
 
std::string fcppt::to_std_string (fcppt::string const &)
 Convert from fcppt::string to std::string using fcppt::string_conv_localeSee the string module description for more information about this function. More...
 
std::string fcppt::to_std_string_locale (fcppt::string const &, std::locale const &)
 Convert from fcppt::string to std::string using a custom localeSee the string module description for more information about this function. More...
 
std::wstring fcppt::to_std_wstring (fcppt::string const &)
 Convert from fcppt::string to std::wstring using fcppt::string_conv_localeSee the string module description for more information about this function. More...
 
std::wstring fcppt::to_std_wstring_locale (fcppt::string const &, std::locale const &)
 Convert from fcppt::string to std::wstring using a custom localeSee the string module description for more information about this function. More...
 
std::wstring fcppt::widen (std::string const &, std::locale const &=fcppt::string_conv_locale())
 Converts a std::string to std::wstring. More...
 

Macro Definition Documentation

◆ FCPPT_TEXT

#define FCPPT_TEXT (   x)    FCPPT_DETAIL_TEXT(x)

A macro to wrap a narrow character literal so it results in a fcppt::char_type[] array.See the string module description for more information.

Typedef Documentation

◆ char_type

typedef fcppt::detail::char_type fcppt::char_type

The char_type used for text.See the string module description for more information.

◆ format

typedef boost::basic_format< fcppt::char_type> fcppt::format

A fcppt::char_type typedef for boost.formatSee the string module description for more information about fcppt::char_type.

◆ fstream

typedef std::basic_fstream< fcppt::char_type> fcppt::filesystem::fstream

Typedef to basic_fstream, depending on fcppt::char_type.

◆ ifstream

typedef std::basic_ifstream< fcppt::char_type> fcppt::filesystem::ifstream

Typedef to basic_ifstream, depending on fcppt::char_type.

◆ istream

typedef std::basic_istream< fcppt::char_type> fcppt::io::istream

Typedef to either std::istream or std::wistream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ istringstream

typedef std::basic_istringstream< fcppt::char_type> fcppt::io::istringstream

Typedef to either std::istringstream or std::wistringstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ ofstream

typedef std::basic_ofstream< fcppt::char_type> fcppt::filesystem::ofstream

Typedef to basic_ofstream, depending on fcppt::char_type.

◆ optional_std_string

An optional std string.

◆ optional_string

An optional string.

◆ ostream

typedef std::basic_ostream< fcppt::char_type> fcppt::io::ostream

Typedef to either std::ostream or std::wostream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ ostringstream

typedef std::basic_ostringstream< fcppt::char_type> fcppt::io::ostringstream

Typedef to either std::ostringstream or std::wostringstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ string

typedef std::basic_string< fcppt::char_type> fcppt::string

The string type used for text.

See the string module description for more information about this type.

◆ stringstream

typedef std::basic_stringstream< fcppt::char_type> fcppt::io::stringstream

Typedef to either std::stringstream or std::wstringstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

Function Documentation

◆ cerr()

fcppt::io::ostream& fcppt::io::cerr ( )

Returns either std::cerr or std::wcerr, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ cin()

fcppt::io::istream& fcppt::io::cin ( )

Returns either std::cin or std::wcin, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ clog()

fcppt::io::ostream& fcppt::io::clog ( )

Returns either std::clog or std::wclog, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ cout()

fcppt::io::ostream& fcppt::io::cout ( )

Returns either std::cout or std::wcout, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

◆ extract_from_string()

template<typename Dest , typename Source >
fcppt::optional::object< Dest> fcppt::extract_from_string ( Source const &  _source,
std::locale const &  _locale = std::locale() 
)

Convert a string to a different type using a locale.

Template Parameters
DestThe destination type, has to have an operator>> defined. Must have either a default constructor or must be constructible from fcppt::no_init.
SourceA string type (see fcppt::type_traits::is_string)
Parameters
_sourceThe string to extract from
_localeThe locale to use (defaults to std::locale())

Note that the string has to be consumed completely.

Also note that the default locale for this function is the C locale. This was chosen deliberately to avoid confusion when converting, for example, "300,100" to int. Using the C locale, this will fail, since the string isn't completely consumed. Using a German locale, however, this will return "300100", since ',' is the thousand separator for this locale.

◆ from_std_string()

fcppt::string fcppt::from_std_string ( std::string const &  )

Convert from std::string to fcppt::string using fcppt::string_conv_localeSee the string module description for more information about this function.

◆ from_std_string_locale()

fcppt::string fcppt::from_std_string_locale ( std::string const &  ,
std::locale const &   
)

Convert from std::string to fcppt::string using a custom localeSee the string module description for more information about this function.

◆ from_std_wstring()

fcppt::string fcppt::from_std_wstring ( std::wstring const &  )

Convert from std::wstring to fcppt::string using fcppt::string_conv_localeSee the string module description for more information about this function.

◆ from_std_wstring_locale()

fcppt::string fcppt::from_std_wstring_locale ( std::wstring const &  ,
std::locale const &   
)

Convert from std::wstring to fcppt::string using a custom localeSee the string module description for more information about this function.

◆ insert_to_fcppt_string()

template<typename Source >
fcppt::string fcppt::insert_to_fcppt_string ( Source const &  _source,
std::locale const &  _locale = std::locale() 
)

Convert an arbitrary type to a fcppt::string.

Template Parameters
SourceThe type to make into a string. Has to have an operator<< defined.
Parameters
_sourceThe object to convert
_localeThe locale (defaults to the C locale)

Note that the default locale for this function is the C locale. This is consistent with the fcppt::extract_from_string function. See this function to see why this locale was chosen.

See also
fcppt::extract_from_string
fcppt::insert_to_string
fcppt::insert_to_std_string
fcppt::insert_to_std_wstring

◆ insert_to_std_string()

template<typename Source >
std::string fcppt::insert_to_std_string ( Source const &  _source,
std::locale const &  _locale = std::locale() 
)

Convert an arbitrary type to a std::string.

Template Parameters
SourceThe type to make into a string. Has to have an operator<< defined.
Parameters
_sourceThe object to convert
_localeThe locale (defaults to the C locale)

Note that the default locale for this function is the C locale. This is consistent with the fcppt::extract_from_string function. See this function to see why this locale was chosen.

See also
fcppt::extract_from_string
fcppt::insert_to_string
fcppt::insert_to_fcppt_string
fcppt::insert_to_std_wstring

◆ insert_to_std_wstring()

template<typename Source >
std::wstring fcppt::insert_to_std_wstring ( Source const &  _source,
std::locale const &  _locale = std::locale() 
)

Convert an arbitrary type to a std::wstring.

Template Parameters
SourceThe type to make into a string. Has to have an operator<< defined.
Parameters
_sourceThe object to convert
_localeThe locale (defaults to the C locale)

Note that the default locale for this function is the C locale. This is consistent with the fcppt::extract_from_string function. See this function to see why this locale was chosen.

See also
fcppt::extract_from_string
fcppt::insert_to_string
fcppt::insert_to_fcppt_string
fcppt::insert_to_std_string

◆ insert_to_string()

template<typename Dest , typename Source >
Dest fcppt::insert_to_string ( Source const &  _source,
std::locale const &  _locale = std::locale() 
)

Convert an arbitrary type to a string.

Template Parameters
DestA string type, see fcppt::type_traits::is_string
SourceThe type to make into a string. Has to have an operator<< defined.
Parameters
_sourceThe object to convert
_localeThe locale (defaults to the C locale)

Note that the default locale for this function is the C locale. This is consistent with the fcppt::extract_from_string function. See this function to see why this locale was chosen.

See also
fcppt::extract_from_string
fcppt::insert_to_std_string
fcppt::insert_to_std_wstring
fcppt::insert_to_fcppt_string

◆ narrow()

std::string fcppt::narrow ( std::wstring const &  _string,
std::locale const &  _locale = fcppt::string_conv_locale() 
)

Converts a std::wstring to std::string.

Converts _string to std::string using _locale.

◆ stream_to_string()

template<typename Ch , typename Traits >
std::basic_string< Ch, Traits> fcppt::io::stream_to_string ( std::basic_istream< Ch, Traits > &  _stream)

Converts the contents of a stream to a string.

◆ strerrno()

fcppt::string fcppt::error::strerrno ( )

A wrapper around std::strerror(strerrno)

A wrapper around std::strerror(strerrno) returning the message for the current global error number.

◆ strerror()

fcppt::string fcppt::error::strerror ( int  errnum)

A wrapper around std::strerror

A wrapper around std::strerror returning the message for the error code given by errnum.

errnum The error code to return the message for

◆ string_conv_locale()

std::locale fcppt::string_conv_locale ( )

Returns the default locale to use when converting strings.

◆ to_std_string()

std::string fcppt::to_std_string ( fcppt::string const &  )

Convert from fcppt::string to std::string using fcppt::string_conv_localeSee the string module description for more information about this function.

◆ to_std_string_locale()

std::string fcppt::to_std_string_locale ( fcppt::string const &  ,
std::locale const &   
)

Convert from fcppt::string to std::string using a custom localeSee the string module description for more information about this function.

◆ to_std_wstring()

std::wstring fcppt::to_std_wstring ( fcppt::string const &  )

Convert from fcppt::string to std::wstring using fcppt::string_conv_localeSee the string module description for more information about this function.

◆ to_std_wstring_locale()

std::wstring fcppt::to_std_wstring_locale ( fcppt::string const &  ,
std::locale const &   
)

Convert from fcppt::string to std::wstring using a custom localeSee the string module description for more information about this function.

◆ widen()

std::wstring fcppt::widen ( std::string const &  ,
std::locale const &  = fcppt::string_conv_locale() 
)

Converts a std::string to std::wstring.

Converts _string to std::wstring using _locale.