Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 21bd517a43.
Boost.Nowide
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...

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. More...
 
class  basic_filebuf< char >
 This is the implementation of std::filebuf. 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 filesize and timestamps on Windows and usually also on other 64 Bit systems This allows to write portable code with option 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)
 
std::string narrow (const wchar_t *s, size_t count)
 
std::string narrow (const wchar_t *s)
 
std::string narrow (const std::wstring &s)
 
std::wstring widen (const char *s, size_t count)
 
std::wstring widen (const char *s)
 
std::wstring widen (const std::string &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...
 
std::locale nowide_filesystem ()
 
template<typename CharType , typename Traits >
void swap (basic_filebuf< CharType, Traits > &lhs, basic_filebuf< CharType, Traits > &rhs)
 
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

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]

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

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

Parameters
sInput string
countNumber of characters to convert Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

◆ narrow() [4/5]

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

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

Parameters
sNULL terminated input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

◆ narrow() [5/5]

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

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

Parameters
sInput string 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 all char strings are interpreted as utf-8 strings

◆ 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,
stat_t buffer 
)

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,
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

◆ 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]

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() [2/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

◆ widen() [3/5]

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

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

Parameters
sInput string
countNumber of characters to convert Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

◆ widen() [4/5]

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

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

Parameters
sNULL terminated input string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

◆ widen() [5/5]

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

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

Parameters
sInput string Any illegal sequences are replaced with the replacement character, see BOOST_NOWIDE_REPLACEMENT_CHARACTER

Variable Documentation

◆ cerr

detail::winconsole_ostream boost::nowide::cerr

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

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

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

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