encoding.cpp File Reference

Conversion between narrow and wide character encodings. More...

#include <clocale>
import std;

Classes
struct	cli::detail::scope_guard_t< F >
	Runs a closure when it goes out of scope. More...

Functions
auto	cli::detail::set_unicode_locale () -> void
	Installs the first available UTF-8 locale for every category.
template<typename F>
auto	cli::detail::scope_guard (F &&closure) -> scope_guard_t< F >
	Builds a scope_guard_t deducing the closure type.
auto	cli::detail::narrow_impl (const wchar_t *str, std::size_t str_size) -> std::string
	Converts a null-terminated wide string to a narrow string.
auto	cli::detail::widen_impl (const char *str, std::size_t str_size) -> std::wstring
	Converts a null-terminated narrow string to a wide string.
auto	cli::narrow (const wchar_t *str, std::size_t str_size) -> std::string
	Converts a wide string to a narrow string.
auto	cli::narrow (const std::wstring &str) -> std::string
	Converts a wide string to a narrow string.
auto	cli::narrow (const wchar_t *str) -> std::string
	Converts a null-terminated wide string to a narrow string.
auto	cli::narrow (std::wstring_view str) -> std::string
	Converts a wide string view to a narrow string.
auto	cli::widen (const char *str, std::size_t str_size) -> std::wstring
	Converts a narrow string to a wide string.
auto	cli::widen (const std::string &str) -> std::wstring
	Converts a narrow string to a wide string.
auto	cli::widen (const char *str) -> std::wstring
	Converts a null-terminated narrow string to a wide string.
auto	cli::widen (std::string_view str) -> std::wstring
	Converts a narrow string view to a wide string.
auto	cli::to_path (std::string_view str) -> std::filesystem::path
	Builds a filesystem path from a narrow string.

Detailed Description

Conversion between narrow and wide character encodings.

On Windows the wide forms are UTF-16 and the narrow forms are the active code page; elsewhere the conversion runs under a temporarily installed UTF-8 locale so that results do not depend on whatever locale the host program has set.

Function Documentation

narrow() [1/4]

auto cli::narrow ( const std::wstring & str ) -> std::string

export

Converts a wide string to a narrow string.

Parameters

[in]

str

The string to convert.

Returns

The converted string.

narrow() [2/4]

auto cli::narrow ( const wchar_t * str ) -> std::string

export

Converts a null-terminated wide string to a narrow string.

Parameters

[in]

str

The null-terminated string to convert.

Returns

The converted string.

narrow() [3/4]

auto cli::narrow ( const wchar_t * str, std::size_t str_size ) -> std::string

export

Converts a wide string to a narrow string.

Parameters

[in]	str	The null-terminated string to convert.
[in]	str_size	Unused; the conversion stops at the null terminator.

Returns

The converted string.

narrow() [4/4]

auto cli::narrow ( std::wstring_view str ) -> std::string

export

Converts a wide string view to a narrow string.

Parameters

[in]

str

The string to convert.

Warning

The conversion reads to a null terminator, so str must be null-terminated. See the notes accompanying this refactor.

Returns

The converted string.

narrow_impl()

auto cli::detail::narrow_impl	(	const wchar_t *	str,
		std::size_t	str_size ) -> std::string

Converts a null-terminated wide string to a narrow string.

Parameters

[in]	str	The null-terminated string to convert.
[in]	str_size	Unused; the conversion stops at the null terminator.

Returns

The converted string.

Exceptions

std::runtime_error

If the input is not convertible.

scope_guard()

template<typename F>

auto cli::detail::scope_guard ( F && closure ) -> scope_guard_t< F >

nodiscard

Builds a scope_guard_t deducing the closure type.

Template Parameters

F	Any callable invocable with no arguments.

Parameters

closure

The closure to run when the guard is destroyed.

Returns

A guard owning closure.

set_unicode_locale()

auto cli::detail::set_unicode_locale

(

)

-> void

Installs the first available UTF-8 locale for every category.

Exceptions

std::runtime_error

If no UTF-8 locale is available.

to_path()

auto cli::to_path ( std::string_view str ) -> std::filesystem::path

export

Builds a filesystem path from a narrow string.

On Windows the string is widened first, so that paths outside the active code page survive the round trip.

Parameters

[in]

str

The path, as a narrow string.

Returns

The corresponding path.

widen() [1/4]

auto cli::widen ( const char * str ) -> std::wstring

export

Converts a null-terminated narrow string to a wide string.

Parameters

[in]

str

The null-terminated string to convert.

Returns

The converted string.

widen() [2/4]

auto cli::widen ( const char * str, std::size_t str_size ) -> std::wstring

export

Converts a narrow string to a wide string.

Parameters

[in]	str	The null-terminated string to convert.
[in]	str_size	Unused; the conversion stops at the null terminator.

Returns

The converted string.

widen() [3/4]

auto cli::widen ( const std::string & str ) -> std::wstring

export

Converts a narrow string to a wide string.

Parameters

[in]

str

The string to convert.

Returns

The converted string.

widen() [4/4]

auto cli::widen ( std::string_view str ) -> std::wstring

export

Converts a narrow string view to a wide string.

Parameters

[in]

str

The string to convert.

Warning

The conversion reads to a null terminator, so str must be null-terminated. See the notes accompanying this refactor.

Returns

The converted string.

widen_impl()

auto cli::detail::widen_impl	(	const char *	str,
		std::size_t	str_size ) -> std::wstring

Converts a null-terminated narrow string to a wide string.

Parameters

[in]	str	The null-terminated string to convert.
[in]	str_size	Unused; the conversion stops at the null terminator.

Returns

The converted string.

Exceptions

std::runtime_error

If the input is not convertible.