Boost.Nowide

Namespaces | Classes | Typedefs | Functions | Variables
boost::nowide Namespace Reference

This namespace includes implementations of the standard library functions and classes such that they accept UTF-8 strings on Windows. On other platforms (i.e. not on Windows) those functions and classes are just aliases of the corresponding ones from the std namespace or behave like them. More...

## Namespaces
namespace | utf
| Namespace that holds basic operations on UTF encoded sequences.

## Classes
class | args
| `args` is a class that temporarily replaces standard main() function arguments with their equal, but UTF-8 encoded values under Microsoft Windows for the lifetime of the instance. More...
class | basic_filebuf
| This forward declaration defines the basic_filebuf type which is used when BOOST_NOWIDE_USE_FILEBUF_REPLACEMENT is set, e.g. on Windows. More...
class | basic_filebuf< char >
| This is the implementation of std::filebuf which is used when BOOST_NOWIDE_USE_FILEBUF_REPLACEMENT is set, e.g. on Windows. More...
class | basic_fstream
| Same as std::basic_fstream<char> but accepts UTF-8 strings under Windows. More...
class | basic_ifstream
| Same as std::basic_ifstream<char> but accepts UTF-8 strings under Windows. More...
class | basic_ofstream
| Same as std::basic_ofstream<char> but accepts UTF-8 strings under Windows. More...
class | basic_stackstring
| A class that allows to create a temporary wide or narrow UTF strings from wide or narrow UTF source. More...
class | utf8_codecvt
class | utf8_codecvt< CharType, 2 >
| Specialization for the UTF-8 <-> UTF-16 variant of the std::codecvt implementation. More...
class | utf8_codecvt< CharType, 4 >
| Specialization for the UTF-8 <-> UTF-32 variant of the std::codecvt implementation. More...

## Typedefs
using | filebuf = basic_filebuf< char >
| Convenience typedef. More...
using | ifstream = basic_ifstream< char >
using | ofstream = basic_ofstream< char >
using | fstream = basic_fstream< char >
using | wstackstring = basic_stackstring< wchar_t, char, 256 >
using | stackstring = basic_stackstring< char, wchar_t, 256 >
using | wshort_stackstring = basic_stackstring< wchar_t, char, 16 >
using | short_stackstring = basic_stackstring< char, wchar_t, 16 >
typedef struct ::__stat64 | stat_t
| Typedef for the file info structure. Able to hold 64 bit file size and timestamps on Windows and usually also on other 64 Bit systems This allows to write portable code with optional LFS support.
typedef struct ::_stat | posix_stat_t
| Typedef for the file info structure used in the POSIX stat call Resolves to `struct _stat` on Windows and `struct stat` otherwise This allows to write portable code using the default stat function.

## Functions
char * | narrow (char *output, size_t output_size, const wchar_t *begin, const wchar_t *end)
char * | narrow (char *output, size_t output_size, const wchar_t *source)
wchar_t * | widen (wchar_t *output, size_t output_size, const char *begin, const char *end)
wchar_t * | widen (wchar_t *output, size_t output_size, const char *source)
template<typename T_Char , typename = detail::requires_wide_char<T_Char>>
std::string | narrow (const T_Char *s, size_t count)
template<typename T_Char , typename = detail::requires_wide_char<T_Char>>
std::string | narrow (const T_Char *s)
template<typename StringOrStringView , typename = detail::requires_wide_string_container<StringOrStringView>>
std::string | narrow (const StringOrStringView &s)
template<typename T_Char , typename = detail::requires_narrow_char<T_Char>>
std::wstring | widen (const T_Char *s, size_t count)
template<typename T_Char , typename = detail::requires_narrow_char<T_Char>>
std::wstring | widen (const T_Char *s)
template<typename StringOrStringView , typename = detail::requires_narrow_string_container<StringOrStringView>>
std::wstring | widen (const StringOrStringView &s)
FILE * | freopen (const char *file_name, const char *mode, FILE *stream)
| Same as freopen but file_name and mode are UTF-8 strings.
FILE * | fopen (const char *file_name, const char *mode)
| Same as fopen but file_name and mode are UTF-8 strings.
int | rename (const char *old_name, const char *new_name)
| Same as rename but old_name and new_name are UTF-8 strings.
int | remove (const char *name)
| Same as rename but name is UTF-8 string.
char * | getenv (const char *key)
| UTF-8 aware getenv. Returns 0 if the variable is not set. More...
int | system (const char *cmd)
int | setenv (const char *key, const char *value, int overwrite)
| Set environment variable key to value. More...
int | unsetenv (const char *key)
| Remove environment variable key. More...
int | putenv (char *string)
| Adds or changes an environment variable, string must be in format KEY=VALUE. More...
template<typename CharType , typename Traits >
void | swap (basic_filebuf< CharType, Traits > &lhs, basic_filebuf< CharType, Traits > &rhs)
| Swap the basic_filebuf instances.
std::locale | nowide_filesystem ()
template<typename CharType , typename Traits >
void | swap (basic_ifstream< CharType, Traits > &lhs, basic_ifstream< CharType, Traits > &rhs)
template<typename CharType , typename Traits >
void | swap (basic_ofstream< CharType, Traits > &lhs, basic_ofstream< CharType, Traits > &rhs)
template<typename CharType , typename Traits >
void | swap (basic_fstream< CharType, Traits > &lhs, basic_fstream< CharType, Traits > &rhs)
int | stat (const char *path, stat_t *buffer)
| UTF-8 aware stat function, returns 0 on success. More...
int | stat (const char *path, posix_stat_t *buffer)
| UTF-8 aware stat function, returns 0 on success. More...
void | dummy_exported_function ()

## Variables
detail::winconsole_istream | cin
| Same as std::cin, but uses UTF-8. More...
detail::winconsole_ostream | cout
| Same as std::cout, but uses UTF-8. More...
detail::winconsole_ostream | cerr
| Same as std::cerr, but uses UTF-8. More...
detail::winconsole_ostream | clog
| Same as std::clog, but uses UTF-8. More...

## Detailed Description

This namespace includes implementations of the standard library functions and classes such that they accept UTF-8 strings on Windows. On other platforms (i.e. not on Windows) those functions and classes are just aliases of the corresponding ones from the std namespace or behave like them.

## Typedef Documentation

## ◆ filebuf

typedef basic_filebuf< char > boost::nowide::filebuf

Convenience typedef.

Same as std::filebuf but accepts UTF-8 strings under Windows

## ◆ fstream

using boost::nowide::fstream = typedef basic_fstream<char>

Same as std::fstream but accepts UTF-8 strings under Windows and *::filesystem::path on all systems

## ◆ ifstream

using boost::nowide::ifstream = typedef basic_ifstream<char>

Same as std::ifstream but accepts UTF-8 strings under Windows and *::filesystem::path on all systems

## ◆ ofstream

using boost::nowide::ofstream = typedef basic_ofstream<char>

Same as std::ofstream but accepts UTF-8 strings under Windows and *::filesystem::path on all systems

## ◆ short_stackstring

using boost::nowide::short_stackstring = typedef basic_stackstring<char, wchar_t, 16>

Convenience typedef

## ◆ stackstring

using boost::nowide::stackstring = typedef basic_stackstring<char, wchar_t, 256>

Convenience typedef

## ◆ wshort_stackstring

using boost::nowide::wshort_stackstring = typedef basic_stackstring<wchar_t, char, 16>

Convenience typedef

## ◆ wstackstring

using boost::nowide::wstackstring = typedef basic_stackstring<wchar_t, char, 256>

Convenience typedef

## Function Documentation

## ◆ dummy_exported_function()

void boost::nowide::dummy_exported_function | ( |  | ) |

Avoid empty compilation unit warnings

## ◆ getenv()

char * boost::nowide::getenv | ( | const char * | key | ) |

UTF-8 aware getenv. Returns 0 if the variable is not set.

This function is not thread safe or reenterable as defined by the standard library

## ◆ narrow() [1/5]

char * boost::nowide::narrow | ( | char * | output,
|  | size_t | output_size,
|  | const wchar_t * | begin,
|  | const wchar_t * | end
| ) |  |
| inline

Convert wide string (UTF-16/32) in range [begin,end) to NULL terminated narrow string (UTF-8) stored in output of size output_size (including NULL)

If there is not enough room NULL is returned, else output is returned. Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ narrow() [2/5]

char * boost::nowide::narrow | ( | char * | output,
|  | size_t | output_size,
|  | const wchar_t * | source
| ) |  |
| inline

Convert NULL terminated wide string (UTF-16/32) to NULL terminated narrow string (UTF-8) stored in output of size output_size (including NULL)

If there is not enough room NULL is returned, else output is returned. Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ narrow() [3/5]

template<typename StringOrStringView , typename = detail::requires_wide_string_container<StringOrStringView>>

std::string boost::nowide::narrow | ( | const StringOrStringView & | s | ) |
| inline

Convert wide string (UTF-16/32) to narrow string (UTF-8).

Parameters

  s | Input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ narrow() [4/5]

template<typename T_Char , typename = detail::requires_wide_char<T_Char>>

std::string boost::nowide::narrow | ( | const T_Char * | s | ) |
| inline

Convert wide string (UTF-16/32) to narrow string (UTF-8).

Parameters

  s | NULL terminated input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ narrow() [5/5]

template<typename T_Char , typename = detail::requires_wide_char<T_Char>>

std::string boost::nowide::narrow | ( | const T_Char * | s,
|  | size_t | count
| ) |  |
| inline

Convert wide string (UTF-16/32) to narrow string (UTF-8).

Parameters

  s | Input string
  count | Number of characters to convert Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ nowide_filesystem()

std::locale boost::nowide::nowide_filesystem | ( |  | ) |
| inline

Install utf8_codecvt facet into boost::filesystem::path such that all char strings are interpreted as UTF-8 strings

Returns
  The previous imbued path locale.

## ◆ putenv()

int boost::nowide::putenv | ( | char * | string | ) |

Adds or changes an environment variable, string must be in format KEY=VALUE.

string MAY become part of the environment, hence changes to the value MAY change the environment. For portability it is hence recommended NOT to change it. string is UTF-8 on Windows

Returns
  zero on success, else nonzero

## ◆ setenv()

int boost::nowide::setenv | ( | const char * | key,
|  | const char * | value,
|  | int | overwrite
| ) |  |

Set environment variable key to value.

if overwrite is not 0, that the old value is always overwritten, otherwise, if the variable exists it remains unchanged

key and value are UTF-8 on Windows

Returns
  zero on success, else nonzero

## ◆ stat() [1/2]

int boost::nowide::stat | ( | const char * | path,
|  | posix_stat_t * | buffer
| ) |  |
| inline

UTF-8 aware stat function, returns 0 on success.

Return information about a file from an UTF-8 encoded path

## ◆ stat() [2/2]

int boost::nowide::stat | ( | const char * | path,
|  | stat_t * | buffer
| ) |  |
| inline

UTF-8 aware stat function, returns 0 on success.

Return information about a file from an UTF-8 encoded path

## ◆ system()

int boost::nowide::system | ( | const char * | cmd | ) |

Same as std::system but cmd is UTF-8.

## ◆ unsetenv()

int boost::nowide::unsetenv | ( | const char * | key | ) |

Remove environment variable key.

key is UTF-8 on Windows

Returns
  zero on success, else nonzero

## ◆ widen() [1/5]

template<typename StringOrStringView , typename = detail::requires_narrow_string_container<StringOrStringView>>

std::wstring boost::nowide::widen | ( | const StringOrStringView & | s | ) |
| inline

Convert narrow string (UTF-8) to wide string (UTF-16/32).

Parameters

  s | Input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ widen() [2/5]

template<typename T_Char , typename = detail::requires_narrow_char<T_Char>>

std::wstring boost::nowide::widen | ( | const T_Char * | s | ) |
| inline

Convert narrow string (UTF-8) to wide string (UTF-16/32).

Parameters

  s | NULL terminated input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ widen() [3/5]

template<typename T_Char , typename = detail::requires_narrow_char<T_Char>>

std::wstring boost::nowide::widen | ( | const T_Char * | s,
|  | size_t | count
| ) |  |
| inline

Convert narrow string (UTF-8) to wide string (UTF-16/32).

Parameters

  s | Input string
  count | Number of characters to convert Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ widen() [4/5]

wchar_t * boost::nowide::widen | ( | wchar_t * | output,
|  | size_t | output_size,
|  | const char * | begin,
|  | const char * | end
| ) |  |
| inline

Convert narrow string (UTF-8) in range [begin,end) to NULL terminated wide string (UTF-16/32) stored in output of size output_size (including NULL)

If there is not enough room NULL is returned, else output is returned. Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## ◆ widen() [5/5]

wchar_t * boost::nowide::widen | ( | wchar_t * | output,
|  | size_t | output_size,
|  | const char * | source
| ) |  |
| inline

Convert NULL terminated narrow string (UTF-8) to NULL terminated wide string (UTF-16/32) most output_size (including NULL)

If there is not enough room NULL is returned, else output is returned. Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

## Variable Documentation

## ◆ cerr

detail::winconsole_ostream boost::nowide::cerr
| extern

Same as std::cerr, but uses UTF-8.

Note, the stream is not synchronized with stdio and not affected by std::ios::sync_with_stdio

## ◆ cin

detail::winconsole_istream boost::nowide::cin
| extern

Same as std::cin, but uses UTF-8.

Note, the stream is not synchronized with stdio and not affected by std::ios::sync_with_stdio

## ◆ clog

detail::winconsole_ostream boost::nowide::clog
| extern

Same as std::clog, but uses UTF-8.

Note, the stream is not synchronized with stdio and not affected by std::ios::sync_with_stdio

## ◆ cout

detail::winconsole_ostream boost::nowide::cout
| extern

Same as std::cout, but uses UTF-8.

Note, the stream is not synchronized with stdio and not affected by std::ios::sync_with_stdio