Description

String-related functions and types.

Motivation

In C++, there are two 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 on Windows, because "foo" is a narrow-string literal and fcppt::string will be a wide string. To portably wrap literals, use the FCPPT_TEXT macro:

fcppt::string s = FCPPT_TEXT("foo");

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

Of course, you would like to "pack" and "unpack" fcppt::string to std::string and std::wstring, respectively. The following functions do just that (see below for the description of fcppt::string_conv_locale):

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 will, of course not work! Use the string for internal stuff, only.

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::io::ifstream, fcppt::io::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 *. A filesystem path can be converted to a fcppt::string, so you don't have to worry about conversions here.

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 a fcppt::string literal (so either wide or narrow). In the same fashion, FCPPT_PP_FILE adapts the standard macro __FILE__ to return a fcppt::string literal.

Lexical casts

Often, you want to convert something (a number, for example) to a string. Or, you want to extract a number from a string. This is what's called "lexical casting". boost provides boost.lexical_cast, which can symmetrically cast in ways:

#include <boost/lexical_cast.hpp>
int main()
{
        std::string s = "1.0";
        double d = boost::lexical_cast<double>(s);
        s = boost::lexical_cast<std::string>(d);
}

It uses operator<< and operator>> to do the conversions, which is convenient.

Casting both ways is also not a real problem per se. However, lexical_cast allows too many conversions. For example,

boost::lexical_cast<float>(3)

is valid, so you can misuse lexical_cast as a numeric cast. Also, the following

std::cout << boost::lexical_cast<char *>(std::string("foobar"));

compiles, but at runtime fails with an exception. So there's much room for errors with lexical cast. Also, throwing an exception on a bad conversion really should be optional. Maybe you've proven that a conversion is definitely safe, so you don't want any overhead because of exception throwing and handling. That's not possible with lexical_cast.

For these reasons, we felt the need to create something that's both unidirectional (meaning you have "from string" and "to string" functions separately), safer and a little bit more flexible. This resulted in the following functions (where T is a type with an operator<< or operator>>, respectively, and CharT is char or wchar_t):

Function	Description
fcppt::extract_from_string	`basic_string<CharT>` → `fcppt::optional<T>`
fcppt::extract_from_string_exn	`basic_string<CharT>` → `T`, failure results in a fcppt::extract_from_string_error exception
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>`

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

class	fcppt::extract_from_string_error
	Exception thrown by fcppt::extract_from_string_exn. More...

Typedefs
typedef fcppt::detail::char_type	fcppt::char_type
	The char_type used for text.See the string module description for more information.

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.

typedef boost::filesystem::basic_fstream < fcppt::char_type >	fcppt::io::fstream
	Typedef to either boost::filesystem::fstream or boost::filesystem::wfstream, depending on fcppt::char_type.

typedef boost::filesystem::basic_ifstream < fcppt::char_type >	fcppt::io::ifstream
	Typedef to either boost::filesystem::ifstream or boost::filesystem::wifstream, depending on fcppt::char_type.

typedef std::basic_istream < fcppt::char_type >	fcppt::io::istream
	Typedef to either std::istream or std::wistream, depending on fcppt::char_type.

typedef std::basic_istringstream < fcppt::char_type >	fcppt::io::istringstream
	Typedef to either std::istringstream or std::wistringstream, depending on fcppt::char_type.

typedef boost::filesystem::basic_ofstream < fcppt::char_type >	fcppt::io::ofstream
	Typedef to either boost::filesystem::ofstream or boost::filesystem::wofstream, depending on fcppt::char_type.

typedef std::basic_ostream < fcppt::char_type >	fcppt::io::ostream
	Typedef to either std::ostream or std::wostream, depending on fcppt::char_type.

typedef std::basic_ostringstream < fcppt::char_type >	fcppt::io::ostringstream
	Typedef to either std::ostringstream or std::wostringstream, depending on fcppt::char_type.

typedef std::basic_stringstream < fcppt::char_type >	fcppt::io::stringstream
	Typedef to either std::stringstream or std::wstringstream, depending on fcppt::char_type.

typedef std::basic_string < char_type >	fcppt::string
	The string type used for text.

Functions
fcppt::string const	fcppt::error::strerrno ()
	A wrapper around `std::strerror(strerrno)`

fcppt::string const	fcppt::error::strerror (int errnum)
	A wrapper around `std::strerror`

fcppt::string const	fcppt::from_std_string (std::string const &)
	Convert from std::string to fcppt::string using fcppt::string_conv_locale.

fcppt::string const	fcppt::from_std_string_locale (std::string const &, std::locale const &)
	Convert from std::string to fcppt::string using a custom locale.

fcppt::string const	fcppt::from_std_wstring (std::wstring const &)
	Convert from std::wstring to fcppt::string using fcppt::string_conv_locale.

fcppt::string const	fcppt::from_std_wstring_locale (std::wstring const &, std::locale const &)
	Convert from std::wstring to fcppt::string using a custom locale.

template<typename Source >
fcppt::string const	fcppt::insert_to_fcppt_string (Source const &_source, std::locale const &_locale=std::locale())
	Convert an arbitrary type to a fcppt::string.

template<typename Source >
std::string const	fcppt::insert_to_std_string (Source const &_source, std::locale const &_locale=std::locale())
	Convert an arbitrary type to a std::string.

template<typename Source >
std::wstring const	fcppt::insert_to_std_wstring (Source const &_source, std::locale const &_locale=std::locale())
	Convert an arbitrary type to a std::wstring.

template<typename Dest , typename Source >
boost::enable_if < fcppt::type_traits::is_string < Dest >, Dest >::type const	fcppt::insert_to_string (Source const &_source, std::locale const &_locale=std::locale())
	Convert an arbitrary type to a string.

io::ostream &	fcppt::io::cerr ()
	Returns either std::cerr or std::wcerr, depending on fcppt::char_type.

io::istream &	fcppt::io::cin ()
	Returns either std::cin or std::wcin, depending on fcppt::char_type.

io::ostream &	fcppt::io::clog ()
	Returns either std::clog or std::wclog, depending on fcppt::char_type.

io::ostream &	fcppt::io::cout ()
	Returns either std::cout or std::wcout, depending on fcppt::char_type.

template<typename Ch , typename Traits >
std::basic_string< Ch, Traits > const	fcppt::io::stream_to_string (std::basic_istream< Ch, Traits > &_stream)
	Converts the contents of a stream to a string.

std::string const	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.

std::string const	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.

std::wstring const	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.

std::wstring const	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.

Typedef Documentation

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

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

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.

typedef boost::filesystem::basic_fstream< fcppt::char_type> fcppt::io::fstream

Typedef to either boost::filesystem::fstream or boost::filesystem::wfstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

typedef boost::filesystem::basic_ifstream< fcppt::char_type> fcppt::io::ifstream

Typedef to either boost::filesystem::ifstream or boost::filesystem::wifstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

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.

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.

typedef boost::filesystem::basic_ofstream< fcppt::char_type> fcppt::io::ofstream

Typedef to either boost::filesystem::ofstream or boost::filesystem::wofstream, depending on fcppt::char_type.

See the string module documentation for a motivation for this.

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.

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.

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

The string type used for text.

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

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

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.

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.

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.

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.

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

Convert from std::string to fcppt::string using fcppt::string_conv_locale.

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

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

Convert from std::string to fcppt::string using a custom locale.

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

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

Convert from std::wstring to fcppt::string using fcppt::string_conv_locale.

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

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

Convert from std::wstring to fcppt::string using a custom locale.

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

template<typename Source >

fcppt::string const fcppt::insert_to_fcppt_string	(	Source const &	_source,
		std::locale const &	_locale = `std::locale()`
	)

Convert an arbitrary type to a fcppt::string.

Template Parameters

Source The type to make into a string. Has to have an operator<< defined.

Parameters

_source	The object to convert
_locale	The 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

template<typename Source >

std::string const fcppt::insert_to_std_string	(	Source const &	_source,
		std::locale const &	_locale = `std::locale()`
	)

Convert an arbitrary type to a std::string.

Template Parameters

Source The type to make into a string. Has to have an operator<< defined.

Parameters

_source	The object to convert
_locale	The 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

template<typename Source >

std::wstring const fcppt::insert_to_std_wstring	(	Source const &	_source,
		std::locale const &	_locale = `std::locale()`
	)

Convert an arbitrary type to a std::wstring.

Template Parameters

Source The type to make into a string. Has to have an operator<< defined.

Parameters

_source	The object to convert
_locale	The 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

template<typename Dest , typename Source >

boost::enable_if< fcppt::type_traits::is_string< Dest >, Dest>::type const fcppt::insert_to_string	(	Source const &	_source,
		std::locale const &	_locale = `std::locale()`
	)

Convert an arbitrary type to a string.

Template Parameters

Dest	A string type, see fcppt::type_traits::is_string
Source	The type to make into a string. Has to have an `operator<<` defined.

Parameters

_source	The object to convert
_locale	The 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

template<typename Ch , typename Traits >

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

Converts the contents of a stream to a string.

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

A wrapper around std::strerror(strerrno)

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

fcppt::string const 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

std::string const 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.

std::string const 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.

std::wstring const 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.

std::wstring const 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.

	0.12.0
Freundlich's C++ toolkit

Description

Motivation

Conversions

IO streams and other adaptors

Lexical casts

Classes

Typedefs

Functions

Typedef Documentation

Function Documentation