#include "safe_config.h"
#include "safe_lib_errno.h"
#include "safe_types.h"
#include "safe_compile.h"
#include "safe_str_lib.h"

Include dependency graph for safe_u8_lib.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	u8cat_s(dest, dmax, src)
	The u8cat_s function appends a copy of the utf-8 string pointed to by src (including the terminating null character) to the end of the utf-8 string pointed to by dest.
#define	u8cpy_s(dest, dmax, src)
	The `u8cpy_s` function copies the string pointed to by `src` (including the terminating null character) into the buffer pointed to by dest.
#define	u8icpy_s(dest, dmax, src)
	The `u8icpy_s` function normalizes and checks the utf-8 string pointed to by `src` and copies it into the buffer pointed to by dest.
#define	u8icat_s(dest, dmax, src)
	The u8icat_s function appends a copy of the utf-8 string src (including the terminating null character) to the end of the utf-8 normalized identifier-like dest.
#define	u8ncat_s(dest, dmax, src, slen)
	The u8ncat_s function appends not more than slen bytes from the utf-8 string pointed to by src to the end of the utf-8 string pointed to by dest.
#define	u8ncpy_s(dest, dmax, src, slen)
	The u8ncpy_s function copies the utf-8 string pointed to by src (including the terminating null character) into the utf-8 string pointed to by dest.
#define	u8len_s(str)
	The u8len_s function computes the byte-length of the null-terminated utf-8 string pointed to by str, not examining more than RSIZE_MAX_STR bytes.
#define	u8nlen_s(str, smax)
	The u8nlen_s function computes the byte-length of the utf-8 string pointed to by str, stopping at smax, providing limited support for non-null terminated strings.
#define	u8width_s(str, smax)
	The u8width_s function computes the number of "graphemes" of the utf-8 string pointed to by str, stopping at smax bytes of str.
#define	u8tok_s(dest, dmaxp, delim, ptr)
	A sequence of calls to the u8tok_s function breaks the utf-8 string pointed to by dest into a sequence of tokens, each of which is delimited by a byte from the utf-8 string pointed to by delim.
#define	u8sprintf_s(dest, dmax, fmt, ...)
	The u8sprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.
#define	vu8sprintf_s(dest, dmax, fmt, ap)
	The vu8sprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.
#define	u8snprintf_s(dest, dmax, ...)
	The truncating u8snprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.
#define	vu8snprintf_s(dest, dmax, fmt, ap)
	The truncating vu8snprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.
#define	u8error_s(dest, dmax, errnum)
	The `u8error_s` function returns a pointer to the textual description of the system error code errnum, identical to the description that would be printed by perror().
#define	u8cmp_s(dest, dmax, src, resultp)
	Compares utf-8 string src to utf-8 string dest, after normalizing both to NFC.
#define	u8icmp_s(dest, dmax, src, resultp)
	Compares two pre-normalized (NFC) utf-8 identifier strings, byte by byte.
#define	u8fccmp_s(dest, dmax, src, resultp)
	Compares utf-8 string src to utf-8 string dest fold-cased, after normalizing both to NFC.
#define	u8natcmp_s(dest, dmax, src, resultp)
#define	u8natfccmp_s(dest, dmax, src, resultp)
	Natural order comparison of utf-8 strings.
#define	u8fcu8_s(dest, dmax, src, slen, substring)
	Locates the first occurrence of the utf-8 substring src in the utf-8 string dest, comparing codepoint by codepoint after full Unicode case-folding (the same `towfc_s()` CaseFolding.txt data used by `u8fccmp_s()` and `u8u8_s()`), so the match is case-insensitive.
#define	u8ifcu8_s(dest, dmax, src, slen, substring)
	Locates the first occurrence of the pre-normalized utf-8 identifier substring src in the pre-normalized utf-8 identifier dest, comparing fold-cased.
#define	u8cspn_s(dest, dmax, src, slen, countp)
	This function computes the byte-length of the prefix of the utf-8 string pointed to by dest which consists entirely of bytes that are excluded from the utf-8 string pointed to by src.
#define	u8pbrk_s(dest, dmax, src, slen, firstp)
	Returns a pointer, firstp, to the first occurrence in the utf-8 string dest of any byte contained in the utf-8 string src.
#define	u8spn_s(dest, dmax, src, slen, countp)
	This function computes the byte-length of the prefix of the utf-8 string pointed to by dest which consists entirely of bytes that are included in the utf-8 string pointed to by src.
#define	u8u8_s(dest, dmax, src, slen, substringp)
	The u8u8_s() function locates the first occurrence of the utf-8 substring pointed to by src in the utf-8 string pointed to by dest.
#define	u8iu8i_s(dest, dmax, src, slen, substringp)
	Locates the first occurrence of the pre-normalized utf-8 identifier substring src in the pre-normalized utf-8 identifier dest.
#define	u8chr_s(dest, dmax, ch, resultp)
	Finds the first occurrence of the byte ch (after conversion to char8_t as if by (char8_t)ch) in the null-terminated utf-8 string pointed to by dest.
#define	u8rchr_s(dest, dmax, ch, resultp)
	Finds the last occurrence of the byte ch (after conversion to char8_t as if by (char8_t)ch) in the null-terminated utf-8 string pointed to by dest.
#define	u8lwr_s(dest, dmax)
	Scans the utf-8 string converting each codepoint to simple lowercase via `towlower()`, leaving all other codepoints unchanged.
#define	u8upr_s(dest, dmax)
	Scans the utf-8 string converting each codepoint to simple uppercase via `towupper()`, leaving all other codepoints unchanged.
#define	u8zero_s(dest, dmax)
	Nulls maximal dmax bytes of the utf-8 string dest.
#define	u8coll_s(dest, dmax, src, resultp)
	Compares two null-terminated utf-8 strings according to the current locale as defined by the `LC_COLLATE` category.
#define	u8set_s(dest, dmax, value)
	Sets maximal dmax bytes of the utf-8 string dest to a byte value, but not the final NUL character.
#define	u8nset_s(dest, dmax, value, n)
	Sets maximal n bytes of the utf-8 string dest to a byte value, but not the final NUL character.
#define	u8towcs_s(retvalp, dest, dmax, src, len)
	The `u8towcs_s` function decodes a null-terminated UTF-8 string pointed to by `src`, unconditionally as UTF-8 (independent of the current locale), into its wide character representation.
#define	u8rtowcs_s(retvalp, dest, dmax, srcp, len, ps)
	The restartable variant of `u8towcs_s()`.
#define	wcstou8_s(retvalp, dest, dmax, src, len)
	The `wcstou8_s` function encodes a null-terminated wide character string pointed to by `src` into UTF-8, unconditionally (independent of the current locale).
#define	wcsrtou8_s(retvalp, dest, dmax, srcp, len, ps)
	The restartable variant of `wcstou8_s()`.
#define	wcrtou8_s(retvalp, dest, dmax, wc, ps)
	Does not permit the `ps` parameter (the pointer to the conversion state) to be a null pointer.
#define	wctou8_s(retvalp, dest, dmax, wc)
	The `wctou8_s` function encodes a single wide character `wc`, unconditionally as UTF-8 (independent of the current locale), storing 1-4 UTF-8 bytes in `dest`, followed by a terminating NUL.
#define	u8str_s(dest, dmax, src, slen, substringp)
	The u8str_s() function locates the first occurrence of the utf-8 substring pointed to by src in the utf-8 string pointed to by dest.
#define	u8fc_s(dest, dmax, src, lenp)
	Converts the utf-8 string to fully fold-cased lowercase, per the Unicode CaseFolding.txt table (the same data used by u8u8_s() for case-insensitive matching).
#define	u8norm_decompose_s(dest, dmax, src, lenp, iscompat)
	Converts the utf-8 string to the canonical NFD normalization, as defined in the latest Unicode standard,.
#define	u8norm_reorder_s(dest, dmax, src, len)
	Reorder all decomposed sequences in a utf-8 string to NFD, as defined in the latest Unicode standard,.
#define	u8norm_compose_s(dest, dmax, src, lenp, iscontig)
	Combine all decomposed sequences in a utf-8 string to NFC, as defined in the latest Unicode standard,.
#define	u8norm_s(dest, dmax, src, mode, lenp)
	Converts the utf-8 string to the canonical NFC or NFD normalization, as defined in the latest Unicode standard,.

Typedefs
typedef char8_t	char8i_t

Functions
EXTERN errno_t	_u8cat_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8cpy_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8icpy_s_chk (char8i_t restrict dest, rsize_t dmax, const char8_t restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8icat_s_chk (char8i_t restrict dest, rsize_t dmax, const char8_t restrict src, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8ncat_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOS_ATTR((slen\|\|dest\|\|dmax) &&(_BOS_NULL(dest)\|\|_BOS_ZERO(dest
EXTERN errno_t empty dest or dmax	BOS_ATTR ((slen\|\|dest\|\|dmax) &&_BOS_OVR(dest, dmax), "dest overflow") BOS_OVR2_BUTZERO(src
EXTERN errno_t	_u8ncpy_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t slen, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2_BUTZERO(src
EXTERN rsize_t	_u8len_s_chk (const char8_t *str, size_t strbos)
EXTERN rsize_t	_u8nlen_s_chk (const char8_t *str, rsize_t smax, size_t strbos) BOS_CHK2(str
EXTERN rsize_t	_u8nlen_s_uchk (const char8_t *str, rsize_t smax)
EXTERN rsize_t	_u8width_s_chk (const char8_t *str, rsize_t smax, size_t strbos) BOS_CHK2(str
EXTERN rsize_t	_u8width_s_uchk (const char8_t *str, rsize_t smax)
EXTERN char8_t *	_u8tok_s_chk (char8_t restrict dest, rsize_t restrict dmaxp, const char8_t restrict delim, char8_t *restrict ptr, const size_t destbos) BOS_ATTR(dest &&_BOS_NULL(dmaxp)
EXTERN char8_t empty dmax	BOS_NULL (delim) BOS_NULL(ptr)
EXTERN int	_u8sprintf_s_chk (char8_t restrict dest, const rsize_t dmax, const size_t destbos, const char restrict fmt,...) __attribute_format__(printf
EXTERN int	BOS_CHK (dest) BOS_FMT(fmt)
EXTERN int	_vu8sprintf_s_chk (char8_t restrict dest, rsize_t dmax, const size_t destbos, const char restrict fmt, va_list ap) BOS_CHK(dest) BOS_FMT(fmt)
EXTERN int	_u8snprintf_s_chk (char8_t restrict dest, rsize_t dmax, const size_t destbos, const char restrict fmt,...) __attribute_format__(printf
EXTERN int	_vu8snprintf_s_chk (char8_t restrict dest, rsize_t dmax, const size_t destbos, const char restrict fmt, va_list ap) BOS_CHK(dest) BOS_FMT(fmt)
EXTERN int	u8sscanf_s (const char8_t restrict buffer, const char restrict fmt,...) __attribute_format__(scanf
EXTERN int	BOS_NULL (buffer) BOS_FMT(fmt)
EXTERN int	fu8scanf_s (FILE restrict stream, const char restrict fmt,...) __attribute_format__(scanf
EXTERN int	BOS_NULL (stream) BOS_FMT(fmt)
EXTERN int	u8scanf_s (const char *restrict fmt,...) __attribute_format__(scanf
EXTERN int	BOS_FMT (fmt)
EXTERN int	vu8scanf_s (const char *restrict fmt, va_list ap) BOS_FMT(fmt)
	The vu8scanf_s function reads a formatted string from stdin, and writes to a list of arguments.
EXTERN int	vfu8scanf_s (FILE restrict stream, const char restrict fmt, va_list ap) BOS_NULL(stream) BOS_FMT(fmt)
	The vfu8scanf_s function reads a formatted utf-8 string from a buffered FILE stream, and writes to a list of arguments.
EXTERN int	vu8sscanf_s (const char8_t restrict dest, const char restrict fmt, va_list ap) BOS_NULL(dest) BOS_FMT(fmt)
	The vu8sscanf_s function reads a formatted utf-8 string, and writes to a list of arguments.
EXTERN int	u8printf_s (const char *restrict fmt,...) __attribute_format__(printf
EXTERN int	fu8printf_s (FILE restrict stream, const char restrict fmt,...) __attribute_format__(printf
EXTERN int	vu8printf_s (const char *restrict fmt, va_list ap) BOS_FMT(fmt)
	The vu8printf_s function composes a string via the format string and writes it, as utf-8, to the STDOUT file.
EXTERN int	vfu8printf_s (FILE restrict stream, const char restrict fmt, va_list arg) BOS_FMT(fmt)
	The vfu8printf_s function composes a string via the format string and writes it, as utf-8, to a FILE stream.
EXTERN errno_t	_u8error_s_chk (char8_t *dest, rsize_t dmax, errno_t errnum, const size_t destbos) BOS_CHK(dest)
EXTERN size_t	u8errorlen_s (errno_t errnum)
	The `u8errorlen_s` function returns the untruncated byte-length of the textual description of the system error code `errnum`, identical to the description that would be printed by `perror()`.
EXTERN errno_t	_u8cmp_s_chk (const char8_t dest, rsize_t dmax, const char8_t src, int *resultp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)
EXTERN errno_t	_u8icmp_s_chk (const char8i_t dest, rsize_t dmax, const char8i_t src, int *resultp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK(src) BOS_NULL(resultp)
EXTERN errno_t	_u8fccmp_s_chk (const char8_t dest, rsize_t dmax, const char8_t src, int *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)
EXTERN errno_t	_u8natcmp_s_chk (const char8_t dest, rsize_t dmax, const char8_t src, const int fold_case, int *resultp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)
EXTERN errno_t	_u8fcu8_s_chk (char8_t dest, rsize_t dmax, const char8_t src, rsize_t slen, char8_t **substring, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src
EXTERN errno_t slen	BOS_NULL (substring)
EXTERN errno_t	_u8ifcu8_s_chk (char8i_t dest, rsize_t dmax, const char8i_t src, rsize_t slen, char8i_t **substring, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src
EXTERN errno_t	_u8cspn_s_chk (const char8_t dest, rsize_t dmax, const char8_t src, rsize_t slen, rsize_t *countp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t slen	BOS_NULL (countp)
EXTERN errno_t	_u8pbrk_s_chk (char8_t dest, rsize_t dmax, char8_t src, rsize_t slen, char8_t **firstp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t slen	BOS_NULL (firstp)
EXTERN errno_t	_u8spn_s_chk (const char8_t dest, rsize_t dmax, const char8_t src, rsize_t slen, rsize_t *countp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_CHK2(src
EXTERN errno_t	_u8u8_s_chk (char8_t dest, rsize_t dmax, const char8_t src, rsize_t slen, char8_t **substringp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t slen	BOS_NULL (substringp)
EXTERN errno_t	_u8iu8i_s_chk (char8i_t dest, rsize_t dmax, const char8i_t src, rsize_t slen, char8i_t **substringp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t	_u8chr_s_chk (const char8_t restrict dest, rsize_t dmax, const int ch, char8_t *restrict resultp, const size_t destbos) BOS_CHK(dest) VAL_OVR2(ch
EXTERN errno_t	BOS_NULL (resultp)
EXTERN errno_t	_u8chr_s_uchk (const char8_t dest, rsize_t dmax, const int ch, char8_t *resultp)
EXTERN errno_t	_u8rchr_s_chk (const char8_t restrict dest, rsize_t dmax, const int ch, char8_t *restrict resultp, const size_t destbos) BOS_CHK(dest) VAL_OVR2(ch
EXTERN errno_t	_u8rchr_s_uchk (const char8_t dest, rsize_t dmax, const int ch, char8_t *resultp)
EXTERN errno_t	_u8lwr_s_chk (char8_t *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest
EXTERN errno_t	_u8lwr_s_uchk (char8_t *dest, rsize_t dmax)
EXTERN errno_t	_u8upr_s_chk (char8_t *dest, rsize_t dmax, const size_t destbos) BOS_CHK2(dest
EXTERN errno_t	_u8upr_s_uchk (char8_t *dest, rsize_t dmax)
EXTERN errno_t	_u8zero_s_chk (char8_t *dest, rsize_t dmax, const size_t destbos) BOS_CHK(dest)
EXTERN errno_t	_u8zero_s_uchk (char8_t *dest, rsize_t dmax)
EXTERN errno_t	_u8coll_s_chk (const char8_t restrict dest, rsize_t dmax, const char8_t restrict src, int *resultp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(resultp)
EXTERN errno_t	_u8coll_s_uchk (const char8_t dest, const char8_t src, int *resultp)
EXTERN errno_t	_u8set_s_chk (char8_t *restrict dest, rsize_t dmax, int value, const size_t destbos) BOS_CHK(dest) VAL_OVR2(value
EXTERN errno_t EXTERN errno_t	_u8set_s_uchk (char8_t *dest, rsize_t dmax, int value)
EXTERN errno_t	_u8nset_s_chk (char8_t *restrict dest, rsize_t dmax, int value, rsize_t n, const size_t destbos) BOS_CHK(dest) BOS_OVR2_BUTZERO(dest
EXTERN errno_t n	VAL_OVR2 (value, 255) VAL_OVR2_BUTZERO(n
EXTERN errno_t	_u8nset_s_uchk (char8_t *dest, rsize_t dmax, int value, rsize_t n)
EXTERN errno_t	_u8towcs_s_chk (size_t restrict retvalp, wchar_t restrict dest, rsize_t dmax, const char8_t *restrict src, rsize_t len, const size_t destbos) BOS_ATTR(!_BOS_NULL(dest) &&_BOS_ZERO(dest
EXTERN errno_t empty dmax	BOS_ATTR (!_BOS_NULL(dest) &&_BOSW_OVR(dest, dmax), "dest overflow") BOS_ATTR(!_BOS_NULL(dest) &&(void *) dest
EXTERN errno_t empty dmax dest overlap	BOS_CHK2 (src, len)
EXTERN errno_t	_u8rtowcs_s_chk (size_t restrict retvalp, wchar_t restrict dest, rsize_t dmax, const char8_t *restrict srcp, rsize_t len, mbstate_t restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_NULL(srcp) BOS_NULL(ps) BOS_ATTR(!_BOS_NULL(dest) &&_BOS_ZERO(dest
EXTERN errno_t empty dmax dest overlap BOS_CHK2 srcp	BOS_ATTR (dmax &&len > dmax, "len overflow >dmax")
EXTERN errno_t	_wcstou8_s_chk (size_t restrict retvalp, char8_t restrict dest, rsize_t dmax, const wchar_t *restrict src, rsize_t len, const size_t destbos) BOS_NULL(retvalp) BOS_CHK(dest) BOSW_CHK2(src
EXTERN errno_t	_wcsrtou8_s_chk (size_t restrict retvalp, char8_t restrict dest, rsize_t dmax, const wchar_t *restrict srcp, rsize_t len, mbstate_t restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_NULL(ps) BOS_ATTR(!_BOS_NULL(dest) &&!dmax
EXTERN errno_t empty dmax	BOS_ATTR (!_BOS_NULL(dest) &&_BOS_OVR(dest, dmax), "dest overflow") BOS_ATTR(!_BOS_NULL(dest) &&(void *) dest
EXTERN errno_t empty dmax dest overlap	BOS_NULL (srcp) BOSW_CHK2(*srcp
EXTERN errno_t	_wcrtou8_s_chk (size_t restrict retvalp, char8_t restrict dest, rsize_t dmax, wchar_t wc, mbstate_t *restrict ps, const size_t destbos) BOS_NULL(retvalp) BOS_CHK(dest) BOS_NULL(ps) VAL_OVR2(wc
EXTERN errno_t	_wctou8_s_chk (int restrict retvalp, char8_t restrict dest, rsize_t dmax, wchar_t wc, const size_t destbos) BOS_ATTR(!_BOS_NULL(dest) &&(!dmax\|\|dmax > RSIZE_MAX_STR\|\|_BOS_OVR(dest
EXTERN errno_t dest overflow or empty	VAL_OVR2 (wc, 0x10ffff)
EXTERN errno_t	_u8str_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t slen, char8_t **restrict substringp, const size_t destbos, const size_t srcbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t	_u8fc_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t *restrict lenp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8norm_decompose_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t *restrict lenp, const bool iscompat, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)
EXTERN errno_t	_u8norm_reorder_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, const rsize_t len, const size_t destbos) BOS_CHK(dest) BOS_OVR2(src
EXTERN errno_t	_u8norm_compose_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, rsize_t *restrict lenp, bool iscontig, const size_t destbos) BOS_CHK(dest) BOS_NULL(src) BOS_NULL(lenp)
EXTERN errno_t	_u8norm_s_chk (char8_t restrict dest, rsize_t dmax, const char8_t restrict src, const wcsnorm_mode_t mode, rsize_t *restrict lenp, const size_t destbos) BOS_CHK(dest) BOS_NULL(src)

Variables
EXTERN errno_t	dmax
EXTERN errno_t empty dest or dmax	slen
EXTERN rsize_t	smax
EXTERN errno_t empty *	dest
EXTERN errno_t	len

Macro Definition Documentation

◆ u8cat_s

#define u8cat_s	(	dest,
		dmax,
		src )

Value:

_u8cat_s_chk(dest, dmax, src, BOS(dest))

The u8cat_s function appends a copy of the utf-8 string pointed to by src (including the terminating null character) to the end of the utf-8 string pointed to by dest.

The initial utf-8 character from src overwrites the null character at the end of dest.

All elements following the terminating null utf-8 character (if any) written by u8cat_s in the array of dmax characters pointed to by dest take unspeciﬁed values when u8cat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Parameters

[out]	dest	pointer to utf-8 string that will be extended by src if dmax allows. The utf-8 string is null terminated. If the resulting concatenated utf-8 string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum wchar_t length of the resulting dest, including the null
[in]	src	pointer to the utf-8 string that will be concatenaed to string dest

Precondition: Neither dest nor src shall be a null pointer; dmax shall not equal zero; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest; dmax shall be greater than u8nlen_s(src,m).; Copying shall not take place between objects that overlap

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8cat_s nulls dest.

Return values

EOK	when successful operation, all the utf-8 characters from src were appended to dest and the result in dest is null terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated in the first dmax utf-8 characters
ESOVRLP	when src overlaps with dest
EILSEQ	when src contains an illegal or truncated UTF-8 sequence

See also: u8icat_s(), wcscat_s(), strcpy_s(), strncpy_s()

◆ u8cpy_s

#define u8cpy_s	(	dest,
		dmax,
		src )

Value:

_u8cpy_s_chk(dest, dmax, src, BOS(dest))

The u8cpy_s function copies the string pointed to by src (including the terminating null character) into the buffer pointed to by dest.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by u8cpy_s in the array of dmax characters pointed to by dest are nulled when u8cpy_s returns.

Parameters

[out]	dest	pointer to wide string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the wide string that will be copied to dest

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; dmax shall not equal zero.; dmax shall be greater than u8nlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8cpy_s nulls dest.

Return values

EOK	when successful operation, the wide characters in src were copied into dest and the result is null terminated.
-ESNULLP	when dest or src is a NULL pointer
-ESZEROL	when dmax = 0
-ESLEMAX	when dmax > RSIZE_MAX_STR
-ESOVRLP	when buffers overlap
-ESNOSPC	when dest < src
EILSEQ	when src contains an illegal or truncated UTF-8 sequence

See also: u8ncpy(), wmemcpy(), wmemmove(), strncpy_s()

◆ u8icpy_s

#define u8icpy_s	(	dest,
		dmax,
		src )

Value:

_u8icpy_s_chk(dest, dmax, src, BOS(dest))

The u8icpy_s function normalizes and checks the utf-8 string pointed to by src and copies it into the buffer pointed to by dest.

dest disallows mixed scripts. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by u8icpy_s in the array of dmax characters pointed to by dest are nulled when u8icpy_s returns.

Parameters

[out]	dest	pointer to utf-8 string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the utf-8 string that will be copied to dest

Precondition: Neither dest nor src shall be a null pointer.; src must not contain mixed scripts characters nor bidi changes.; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest.; dmax shall not equal zero.; dmax shall be greater than u8inlen_s(src, dmax).; Copying shall not take place between objects that overlap.

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then u8icpy_s nulls dest.

Return values

EOK	when successful operation, the utf-8 characters in src were copied into dest and the result is null terminated.
-ESNULLP	when dest or src is a NULL pointer
-ESZEROL	when dmax = 0
-ESLEMAX	when dmax > RSIZE_MAX_STR
-ESOVRLP	when buffers overlap
-ESNOSPC	when dest < src
-ESU8I	when disallowed mixed scripts or bidi changes were detected.

See also: u8cpy(), strncpy_s()

◆ u8icat_s

#define u8icat_s	(	dest,
		dmax,
		src )

Value:

_u8icat_s_chk(dest, dmax, src, BOS(dest))

The u8icat_s function appends a copy of the utf-8 string src (including the terminating null character) to the end of the utf-8 normalized identifier-like dest.

The initial utf-8 character from src overwrites the null character at the end of dest. Identifier-like strings follow stricter rules for mixed scripts, src will be normalized.

All elements following the terminating null utf-8 character (if any) written by u8icat_s in the array of dmax characters pointed to by dest take unspeciﬁed values when u8icat_s returns. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Parameters

[out]	dest	pointer to a normalized utf-8 string that will be extended by a normalized copy of src if dmax allows. The utf-8 string is normalized, follows the strict security guidelines for identifiers (esp. no bidi changes, no mixed scripts) and will be null terminated. If the resulting concatenated utf-8 string is less than dmax, the remaining slack space is nulled.
[in]	dmax	restricted maximum byte-length of the resulting dest buffer, including the null.
[in]	src	pointer to the utf-8 string that will be normalized and concatenated to identifier dest.

Precondition: Neither dest nor src shall be a null pointer; dest must be already normalized and contain no disallowed mixed scripts characters or bidi changes.; src must not contain mixed scripts characters.; The union of src and dest must not contain mixed scripts characters.; dmax shall not equal zero; dmax shall not be greater than RSIZE_MAX_WSTR and size of dest; dmax shall be greater than u8nlen_s(src,m).; Copying shall not take place between objects that overlap

Note: C11 uses RSIZE_MAX, not RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8icat_s nulls dest.

Return values

EOK	when successful operation, all the normalized utf-8 characters from src were appended to dest and the result in dest is null terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_WSTR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated in the first dmax utf-8 bytes
ESOVRLP	when src overlaps with dest
EILSEQ	when src contains an illegal or truncated UTF-8 sequence
ESU8I	when disallowed mixed scripts or bidi changes were detected.

See also: u8icat_s(), wcscat_s(), strcpy_s(), strncpy_s()

◆ u8ncat_s

#define u8ncat_s	(	dest,
		dmax,
		src,
		slen )

Value:

_u8ncat_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The u8ncat_s function appends not more than slen bytes from the utf-8 string pointed to by src to the end of the utf-8 string pointed to by dest.

The initial utf-8 character from src overwrites the null character at the end of dest. If no null character was found in the first slen bytes of src, a null character is appended to the result. With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Parameters

[out]	dest	pointer to utf-8 string that will be extended by src if dmax allows.
[in]	dmax	restricted maximum byte-length of the resulting dest, including the null
[in]	src	pointer to the utf-8 string that will be concatenated to string dest
[in]	slen	maximum number of bytes to append from src

Precondition: Neither dest nor src shall be a null pointer, unless slen is 0.; dmax shall not equal zero.; dmax and slen shall not be greater than RSIZE_MAX_STR.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8ncat_s nulls dest.

Return values

EOK	when successful operation, when slen == 0 or all the utf-8 characters from src were appended to dest and the result in dest is null terminated.
ESNULLP	when dest or src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESUNTERM	when dest not terminated in the first dmax utf-8 bytes
ESOVRLP	when src overlaps with dest
ESNOSPC	when there is not enough room in dest
EILSEQ	when src contains an illegal or truncated UTF-8 sequence

See also: u8cat_s(), u8ncpy_s(), strncat_s(), wcsncat_s()

◆ u8ncpy_s

#define u8ncpy_s	(	dest,
		dmax,
		src,
		slen )

Value:

_u8ncpy_s_chk(dest, dmax, src, slen, BOS(dest), BOS(src))

The u8ncpy_s function copies the utf-8 string pointed to by src (including the terminating null character) into the utf-8 string pointed to by dest.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating null character (if any) written by u8ncpy_s in the array of dmax characters pointed to by dest are nulled when u8ncpy_s returns.

Parameters

[out]	dest	pointer to utf-8 string that will be replaced by src.
[in]	dmax	restricted maximum length of dest
[in]	src	pointer to the utf-8 string that will be copied to dest
[in]	slen	maximum number of utf-8 characters to copy

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR.; dmax shall not equal zero.; If slen is either greater than or equal to dmax, then dmax should be more than u8nlen_s(src,dmax) to avoid truncation.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest and dmax are valid, then u8ncpy_s nulls dest.

Return values

EOK	successful operation, when slen == 0 or the utf-8 characters in src were copied into dest and the result is null terminated.
ESNULLP	when dest/src is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when buffers overlap
ESNOSPC	when src > dest
EILSEQ	when src contains an illegal or truncated UTF-8 sequence

See also: u8cpy_s(), strncpy_s(), wmemcpy_s(), wmemmove_s()

◆ u8len_s

#define u8len_s ( str )

Value:

_u8len_s_chk(str, BOS(str))

The u8len_s function computes the byte-length of the null-terminated utf-8 string pointed to by str, not examining more than RSIZE_MAX_STR bytes.

Parameters

str	pointer to utf-8 string

Returns: The function returns the utf-8 string length in bytes, excluding the terminating null character. If str is NULL, then u8len_s returns 0. If there is no null character in the first RSIZE_MAX_STR bytes of str then u8len_s returns RSIZE_MAX_STR. At most RSIZE_MAX_STR bytes of str are accessed by u8len_s.

See also: u8nlen_s(), strnlen_s()

◆ u8nlen_s

#define u8nlen_s	(		str,
			smax )

Value:

_BOS_UCHK_STR(u8nlen_s, str, smax)

The u8nlen_s function computes the byte-length of the utf-8 string pointed to by str, stopping at smax, providing limited support for non-null terminated strings.

Parameters

str	pointer to utf-8 string
smax	maximum byte-length of utf-8 string, incl. the final \0.

Precondition: str shall not be a null pointer.; smax shall not equal zero.; smax shall not be greater than RSIZE_MAX_STR and size of str (inc. final null).

Returns

The function returns the utf-8 string length, excluding the terminating null character. If str is NULL, then u8nlen_s returns

Otherwise, the u8nlen_s function returns the number of wide characters that precede the terminating null character. If there is no null character in the first smax characters of str then u8nlen_s returns smax. At most the first smax characters of str are accessed by u8nlen_s.

See also: u8len_s(), strnlen_s(), wcsnlen_s()

◆ u8width_s

#define u8width_s	(		str,
			smax )

Value:

_BOS_UCHK_STR(u8width_s, str, smax)

The u8width_s function computes the number of "graphemes" of the utf-8 string pointed to by str, stopping at smax bytes of str.

This is equivalent to the number of extended grapheme clusters, the visual width of characters of the string. See the Unicode Text Segmentation Annex TR29.

Parameters

str	pointer to utf-8 string
smax	maximum byte-length of the given utf-8 string, incl. the final \0.

Precondition: str shall not be a null pointer.; smax shall not equal zero.; smax shall not be greater than RSIZE_MAX_STR and the size of str (inc. final null).

Remarks

SPECIFIED IN

Unicode Text Segmentation Annex TR29 http://www.unicode.org/reports/tr29/tr29-29.html

Returns

The function returns the visual utf-8 string width, excluding the terminating null character. If str is NULL, then u8width_s returns

Otherwise, the u8width_s function returns the number of extended grapheme clusters that precede the terminating null character. (Not legacy). If there is no null character in the first smax characters of str then u8width_s returns smax. At most the first smax characters of str are accessed by u8width_s.

See also: u8nlen_s()

◆ u8tok_s

#define u8tok_s	(	dest,
		dmaxp,
		delim,
		ptr )

Value:

_u8tok_s_chk(dest, dmaxp, delim, ptr, BOS(dest))

A sequence of calls to the u8tok_s function breaks the utf-8 string pointed to by dest into a sequence of tokens, each of which is delimited by a byte from the utf-8 string pointed to by delim.

The fourth argument points to a caller-provided char8_t pointer into which u8tok_s stores information necessary for it to continue scanning the same string. Delimiters are matched byte-wise, like strtok_s(); multi-byte delimiter characters are not supported.

The first call in a sequence has a non-null first argument and dmaxp points to an object whose value is the number of bytes in the array pointed to by the first argument. The first call stores an initial value in the object pointed to by ptr and updates the value pointed to by dmaxp to reflect the number of bytes that remain in relation to ptr. Subsequent calls in the sequence have a null first argument and the objects pointed to by dmaxp and ptr are required to have the values stored by the previous call in the sequence, which are then updated. The separator string pointed to by delim may be different from call to call.

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Parameters

[in]	dest	pointer to utf-8 string to tokenize
[out]	dmaxp	pointer to restricted maximum byte-length of dest
[in]	delim	pointer to utf-8 delimiter string (len < 255)
[out]	ptr	returned pointer to token

Precondition: delim shall not be a null pointer.; ptr shall not be a null pointer.; dmaxp shall not be a null pointer.; *dmaxp shall not be 0.; If dest is a null pointer, then *ptr shall not be a null pointer.; dest must not be unterminated.; *dmaxp shall not be greater than RSIZE_MAX_STR and size of dest.; delim must not be longer than STRTOK_DELIM_MAX_LEN (default: 16).

Returns: The u8tok_s function returns a pointer to the first byte of a token; or a null pointer if there is no token or there is a runtime-constraint violation. Each call modifies dest by substituting a NUL byte for the first delimiter that occurs after the returned token.

errno is set to: ESNULLP when dest/delim/ptr is NULL pointer ESZEROL when *dmaxp = 0 ESLEMAX when *dmaxp > RSIZE_MAX_STR EOVERFLOW when *dmaxp > size of dest ESLEWRNG when *dmaxp != size of dest and –enable-error-dmax ESUNTERM when unterminated string

See also: strtok_s()

◆ u8sprintf_s

#define u8sprintf_s	(	dest,
		dmax,
		fmt,
		... )

Value:

_u8sprintf_s_chk(dest, dmax, BOS(dest), fmt, __VA_ARGS__)

The u8sprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest.

fmt and the variadic arguments are plain ASCII/byte data (as with all C printf format strings); only dest is utf-8. Since UTF-8 is byte-compatible with the underlying formatter, this is otherwise identical to sprintf_s().

Parameters

[out]	dest	storage location for output buffer.
[in]	dmax	maximum number of bytes to store in buffer.
[in]	fmt	format-control string.
[in]	...	optional arguments

Precondition: fmt shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR or the sizeof(dest).; dmax shall not equal zero if dest is not null.; fmt shall not contain the conversion specifier n.

Returns: If no runtime-constraint violation occurred, the number of bytes written in the array, not counting the terminating NUL. If an error occurred, a negative value.

Return values

-ESNULLP	when `fmt` is NULL pointer, or when `dest` is NULL and dmax > 0
-ESZEROL	when `dmax` = 0 and dest is not NULL
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR` or dmax > size of dest
-EOVERFLOW	when `dmax` > size of dest
-ESNOSPC	when return value exceeds dmax unless dmax is zero and dest is NULL
-EINVAL	when `fmt` contains `n`

See also: vu8sprintf_s(), u8snprintf_s(), sprintf_s()

◆ vu8sprintf_s

#define vu8sprintf_s	(	dest,
		dmax,
		fmt,
		ap )

Value:

_vu8sprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

The vu8sprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest.

Parameters

[out]	dest	pointer to utf-8 string that will be written into.
[in]	dmax	restricted maximum length of dest
[in]	fmt	format-control string.
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR or the size of dest.; dmax shall not equal zero if dest is not null.; fmt shall not contain the conversion specifier n

Returns: On success the total number of bytes without the terminating \0 is returned.; On failure a negative number is returned.

Return values

-ESNULLP	when `fmt` is NULL pointer, or when `dest` is NULL and dmax > 0
-ESZEROL	when `dmax` = 0 and dest is not NULL
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR`
-EOVERFLOW	when `dmax` > size of dest
-ESNOSPC	when return value exceeds dmax unless dmax is zero and dest is NULL
-EINVAL	when `fmt` contains `n`

See also: u8sprintf_s(), vu8snprintf_s()

◆ u8snprintf_s

#define u8snprintf_s	(	dest,
		dmax,
		... )

Value:

_u8snprintf_s_chk(dest, dmax, BOS(dest), __VA_ARGS__)

The truncating u8snprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest. It is guaranteed that dest will be NUL-terminated.

Parameters

[out]	dest	pointer to utf-8 string that will be written into.
[in]	dmax	restricted maximum length of `dest`
[in]	fmt	format-control string.
[in]	...	optional arguments

Precondition: fmt shall not be a null pointer.; dest shall not be a null pointer.; dmax shall not be zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; fmt shall not contain the conversion specifier n.

Returns: If the buffer dest is too small for the formatted text, including the terminating null, then the buffer is truncated and zero terminated.

Return values

Number	of bytes not including the terminating null byte, or a negative error number if a runtime constraints violation or an encoding error occurred.
-ESNULLP	when `dest/fmt` is NULL pointer
-ESZEROL	when `dmax` == 0
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR`
-EOVERFLOW	when `dmax` > size of dest
-EINVAL	when `fmt` contains n

See also: u8sprintf_s(), vu8snprintf_s()

◆ vu8snprintf_s

#define vu8snprintf_s	(	dest,
		dmax,
		fmt,
		ap )

Value:

_vu8snprintf_s_chk(dest, dmax, BOS(dest), fmt, ap)

The truncating vu8snprintf_s function composes a utf-8 string with the same content that would be printed if format was used on printf.

Instead of being printed, the content is stored in dest. It is guaranteed that dest will be NUL-terminated.

Parameters

[out]	dest	pointer to utf-8 string that will be written into.
[in]	dmax	restricted maximum length of `dest`
[in]	fmt	format-control string.
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; dest shall not be a null pointer.; dmax shall not be zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; fmt shall not contain the conversion specifier n.

Returns: If the buffer dest is too small for the formatted text, including the terminating null, then the buffer is truncated and zero terminated.

Return values

Number	of bytes not including the terminating null byte, or a negative error number if a runtime constraints violation or an encoding error occurred.
-ESNULLP	when `dest/fmt` is NULL pointer
-ESZEROL	when `dmax` == 0
-ESLEMAX	when `dmax` > `RSIZE_MAX_STR`
-EOVERFLOW	when `dmax` > size of dest
-EINVAL	when `fmt` contains n

See also: vu8sprintf_s(), u8snprintf_s()

◆ u8error_s

#define u8error_s	(	dest,
		dmax,
		errnum )

Value:

_u8error_s_chk(dest, dmax, errnum, BOS(dest))

The u8error_s function returns a pointer to the textual description of the system error code errnum, identical to the description that would be printed by perror().

Error messages are plain ASCII, which is always well-formed UTF-8. In addition to strerror() it adds the size of the destination array in order to prevent buffer overflow, and it truncates overlong error messages with "...".

Parameters

[out]	dest	pointer to a user-provided utf-8 string buffer
[in]	dmax	restricted maximum byte-length of dest
[in]	errnum	integer value referring to an error code

Precondition: dest shall not be a null pointer.; dmax shall not be greater than RSIZE_MAX_STR and size of dest; dmax shall not equal zero.

Returns: Zero if the entire message was successfully stored in dest, non-zero otherwise.

Return values

EOK	on success
ESNULLP	when dest is a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESLEMIN	when the result would be longer than 4 and dmax < 4

See also: u8errorlen_s(), strerror_s()

◆ u8cmp_s

#define u8cmp_s	(	dest,
		dmax,
		src,
		resultp )

Value:

_u8cmp_s_chk(dest, dmax, src, resultp, BOS(dest), BOS(src))

Compares utf-8 string src to utf-8 string dest, after normalizing both to NFC.

This means two strings that are canonically equivalent but use different Unicode representations (e.g. a precomposed accented codepoint vs. the base letter followed by a combining mark) compare equal.

Parameters

[in]	dest	pointer to utf-8 string to compare against
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to the utf-8 string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively, after NFC normalization.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when comparison is complete and the result is returned in resultp
ESUNTERM	when src is unterminated
ESNULLP	when dest, src or resultp is the NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ENOMEM	when a normalization scratch buffer could not be allocated
*	any error returned by u8norm_s() while normalizing dest or src (e.g. EILSEQ for malformed utf-8)

See also: u8icmp_s(), u8fccmp_s(), u8norm_s()

◆ u8icmp_s

#define u8icmp_s	(	dest,
		dmax,
		src,
		resultp )

Value:

_u8icmp_s_chk(dest, dmax, src, resultp, BOS(dest), BOS(src))

Compares two pre-normalized (NFC) utf-8 identifier strings, byte by byte.

Because both operands are guaranteed to already be in NFC form (char8i_t, cf. u8icpy_s()), a plain byte comparison of the utf-8 sequences gives the correct canonical result without any normalization work at compare time.

Parameters

[in]	dest	pointer to utf-8 identifier string to compare
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to the utf-8 identifier string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when comparison is complete and the result is returned in resultp
ESNULLP	when dest, src or resultp is the NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8cmp_s(), u8icpy_s()

◆ u8fccmp_s

#define u8fccmp_s	(	dest,
		dmax,
		src,
		resultp )

Value:

_u8fccmp_s_chk(dest, dmax, src, resultp, BOS(dest))

Compares utf-8 string src to utf-8 string dest fold-cased, after normalizing both to NFC.

Full Unicode case-folding is applied (via towfc_s(), the same CaseFolding.txt data used by u8u8_s()) codepoint by codepoint, so this also matches canonically equivalent strings that use different, case-varying Unicode representations.

Parameters

[in]	dest	pointer to utf-8 string to compare against
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to the utf-8 string to be compared to dest
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the fold-cased, normalized dest is greater than, equal to or less than the fold-cased, normalized src.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Return values

EOK	when comparison is complete and the result is returned in resultp
ESNULLP	when dest/src/resultp is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
EILSEQ	when dest/src contains illegal utf-8
ENOMEM	when a normalization scratch buffer could not be allocated
*	any error returned by u8norm_s() while normalizing

See also: u8cmp_s(), u8u8_s(), u8norm_s()

◆ u8natcmp_s

#define u8natcmp_s	(	dest,
		dmax,
		src,
		resultp )

Value:

_u8natcmp_s_chk(dest, dmax, src, 0, resultp, BOS(dest), BOS(src))

◆ u8natfccmp_s

#define u8natfccmp_s	(	dest,
		dmax,
		src,
		resultp )

Value:

_u8natcmp_s_chk(dest, dmax, src, 1, resultp, BOS(dest), BOS(src))

Natural order comparison of utf-8 strings.

The longest run of numbers wins over alpha chars. u8natfccmp_s() additionally folds ASCII case before comparing.

Parameters

[in]	dest	pointer to utf-8 string to compare against
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to the utf-8 string to be compared to dest
[in]	fold_case	fold ASCII case before comparing (1/0)
[out]	resultp	pointer to int result, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest nor src shall be a null pointer.; resultp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR or size of dest

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when comparison is complete and the result is returned in resultp
ESNULLP	when dest, src or resultp is the NULL pointer
ESUNTERM	when src is unterminated
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: u8cmp_s(), strnatcmp_s()

◆ u8fcu8_s

#define u8fcu8_s	(	dest,
		dmax,
		src,
		slen,
		substring )

Value:

_u8fcu8_s_chk(dest, dmax, src, slen, substring, BOS(dest), BOS(src))

Locates the first occurrence of the utf-8 substring src in the utf-8 string dest, comparing codepoint by codepoint after full Unicode case-folding (the same towfc_s() CaseFolding.txt data used by u8fccmp_s() and u8u8_s()), so the match is case-insensitive.

This does NOT perform NFC/NFD canonicalization: a substring that is only canonically equivalent to, but not fold-casewise codepoint-identical with, a run of codepoints in dest (e.g. a precomposed accented letter in one operand against the decomposed base-letter-plus-combining-mark form in the other) is not matched. Normalize both operands with u8norm_s() first (WCSNORM_NFC) if that guarantee is required.

Parameters

[in]	dest	pointer to utf-8 string to be searched for the substring
[in]	dmax	restricted maximum byte-length of dest string
[in]	src	pointer to the utf-8 sub string
[in]	slen	the maximum number of bytes to use from src
[out]	substring	the returned substring pointer, into dest

Precondition: Neither dest, src nor substring shall be a null pointer.; dmax shall not be 0.; slen shall not be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
EILSEQ	when dest/src contains illegal utf-8
ESNOTFND	when substring not found

See also: u8u8_s(), u8fccmp_s(), u8ifcu8_s(), u8norm_s()

◆ u8ifcu8_s

#define u8ifcu8_s	(	dest,
		dmax,
		src,
		slen,
		substring )

Value:

_u8ifcu8_s_chk(dest, dmax, src, slen, substring, BOS(dest), BOS(src))

Locates the first occurrence of the pre-normalized utf-8 identifier substring src in the pre-normalized utf-8 identifier dest, comparing fold-cased.

Because both operands are guaranteed to already be in NFC form (char8i_t, cf. u8icpy_s()), no extra normalization work is done before the fold-cased search; see u8fcu8_s() for the exact fold-casing semantics and its NFC-canonicalization caveat.

Parameters

[in]	dest	pointer to utf-8 identifier string to be searched
[in]	dmax	restricted maximum byte-length of dest string
[in]	src	pointer to the utf-8 identifier sub string
[in]	slen	the maximum number of bytes to use from src
[out]	substring	the returned substring pointer, into dest

Precondition: Neither dest, src nor substring shall be a null pointer.; dmax shall not be 0.; slen shall not be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
EILSEQ	when dest/src contains illegal utf-8
ESNOTFND	when substring not found

See also: u8fcu8_s(), u8icmp_s(), u8iu8i_s()

◆ u8cspn_s

#define u8cspn_s	(	dest,
		dmax,
		src,
		slen,
		countp )

Value:

_u8cspn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))

This function computes the byte-length of the prefix of the utf-8 string pointed to by dest which consists entirely of bytes that are excluded from the utf-8 string pointed to by src.

The scanning stops at the first NUL in dest or after dmax bytes. The exclusion string is checked to the NUL or after slen bytes. Bytes are matched individually, like strcspn_s(); this is exact for excluding single-byte (ASCII) delimiters.

Parameters

[in]	dest	pointer to utf-8 string to determine the prefix
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to utf-8 exclusion string
[in]	slen	restricted maximum byte-length of string src
[out]	countp	pointer to a count variable that will be updated with the dest prefix byte-length

Precondition: Neither dest nor src shall be a null pointer.; countp shall not be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Return values

EOK	when operation is successful
ESNULLP	when dest/src/countp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8spn_s(), u8pbrk_s(), u8str_s()

◆ u8pbrk_s

#define u8pbrk_s	(	dest,
		dmax,
		src,
		slen,
		firstp )

Value:

_u8pbrk_s_chk(dest, dmax, src, slen, firstp, BOS(dest), BOS(src))

Returns a pointer, firstp, to the first occurrence in the utf-8 string dest of any byte contained in the utf-8 string src.

Parameters

dest	pointer to utf-8 string to search
dmax	restricted maximum byte-length of string dest
src	pointer to the utf-8 set of bytes
slen	restricted byte-length of string src
firstp	returned pointer to first occurrence

Precondition: Neither dest, src nor firstp shall be a null pointer.; Neither dmax nor slen shall not be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and the size of dest/src

Returns: pointer to the first occurrence of any byte contained in src

Return values

EOK	when successful operation
ESNULLP	when dest/src/firstp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically). when slen > size of src
ESLEWRNG	with –enable-error-dmax, when dmax != sizeof(dest) or slen > size of src

See also: u8cspn_s(), u8spn_s(), u8str_s()

◆ u8spn_s

#define u8spn_s	(	dest,
		dmax,
		src,
		slen,
		countp )

Value:

_u8spn_s_chk(dest, dmax, src, slen, countp, BOS(dest), BOS(src))

This function computes the byte-length of the prefix of the utf-8 string pointed to by dest which consists entirely of bytes that are included in the utf-8 string pointed to by src.

Parameters

[in]	dest	pointer to utf-8 string to determine the prefix
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to utf-8 inclusion string
[in]	slen	restricted maximum byte-length of string src
[out]	countp	pointer to a count variable that will be updated with the dest prefix byte-length

Precondition: Neither dest, src nor countp shall be a null pointer.; Neither dmax nor slen shall be 0.; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/countp is NULL pointer
ESZEROL	when dmax/slen = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8cspn_s(), u8pbrk_s(), u8str_s()

◆ u8u8_s

#define u8u8_s	(	dest,
		dmax,
		src,
		slen,
		substringp )

Value:

_u8u8_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))

The u8u8_s() function locates the first occurrence of the utf-8 substring pointed to by src in the utf-8 string pointed to by dest.

Performs the same literal byte-sequence search as u8str_s(). UTF-8 is self-synchronizing, so a literal match between well-formed UTF-8 strings always lands on codepoint boundaries.

Parameters

[in]	dest	pointer to utf-8 string to be searched for the substring
[in]	dmax	restricted maximum byte-length of dest string
[in]	src	pointer to the utf-8 sub string
[in]	slen	the maximum number of bytes to use from src
[out]	substringp	the returned substring pointer

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be 0.; slen shall not be 0, when *src != 0 and src != dest; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0, unless *src = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when substring not found

See also: u8str_s(), u8norm_s()

◆ u8iu8i_s

#define u8iu8i_s	(	dest,
		dmax,
		src,
		slen,
		substringp )

Value:

_u8iu8i_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))

Locates the first occurrence of the pre-normalized utf-8 identifier substring src in the pre-normalized utf-8 identifier dest.

Because both operands are guaranteed to already be in NFC form (char8i_t, cf. u8icpy_s()), and canonically equivalent NFC strings are byte-identical, a literal byte-sequence search (the same search u8u8_s()/u8str_s() perform) gives the correct canonical result without any normalization work at search time.

Parameters

[in]	dest	pointer to utf-8 identifier string to be searched for the substring
[in]	dmax	restricted maximum byte-length of dest string
[in]	src	pointer to the utf-8 identifier sub string
[in]	slen	the maximum number of bytes to use from src
[out]	substringp	the returned substring pointer

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be 0.; slen shall not be 0, when *src != 0 and src != dest; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0, unless *src = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when substring not found

See also: u8u8_s(), u8str_s(), u8icmp_s()

◆ u8chr_s

#define u8chr_s	(	dest,
		dmax,
		ch,
		resultp )

Value:

    _BOS_UCHK(_BOS_DMAX_OK(dest, dmax, 1) && (int)(ch) <= 255 &&               \
                  _BOS_KNOWN(resultp),                                         \
              _u8chr_s_uchk(dest, dmax, ch, resultp),                          \
              _u8chr_s_chk(dest, dmax, ch, resultp, BOS(dest)))

Finds the first occurrence of the byte ch (after conversion to char8_t as if by (char8_t)ch) in the null-terminated utf-8 string pointed to by dest.

The terminating NUL byte is considered to be a part of the string and can be found when searching for '\0'. ch is a single byte (0-255), not a decoded Unicode codepoint; to search for an ASCII character this is exactly what you want, since ASCII bytes never appear as part of a multi-byte UTF-8 sequence.

Parameters

[in]	dest	pointer to utf-8 string to search
[in]	dmax	restricted maximum byte-length of dest
[in]	ch	byte value to search for (0-255)
[out]	resultp	pointer to char8_t* in dest

Precondition: Neither dest nor resultp shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; ch shall not be greater than 255

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when successfully byte found.
ESNOTFND	when ch not found in dest
ESNULLP	when dest or resultp is the NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR, or ch > 255
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: u8rchr_s(), strchr_s()

◆ u8rchr_s

#define u8rchr_s	(	dest,
		dmax,
		ch,
		resultp )

Value:

    _BOS_UCHK(_BOS_DMAX_OK(dest, dmax, 1) && (int)(ch) <= 255 &&               \
                  _BOS_KNOWN(resultp),                                         \
              _u8rchr_s_uchk(dest, dmax, ch, resultp),                         \
              _u8rchr_s_chk(dest, dmax, ch, resultp, BOS(dest)))

Finds the last occurrence of the byte ch (after conversion to char8_t as if by (char8_t)ch) in the null-terminated utf-8 string pointed to by dest.

The terminating NUL byte is considered to be a part of the string and can be found when searching for '\0'. Unlike strrchr() it honors dmax as maximal byte-length.

Parameters

[in]	dest	pointer to utf-8 string to search
[in]	dmax	restricted maximum byte-length of dest
[in]	ch	byte value to search for (0-255)
[out]	resultp	pointer to char8_t* in dest on EOK

Precondition: Neither dest nor resultp shall be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; ch shall not be greater than 255.

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when successfully byte found. See resultp
ESNOTFND	when ch not found in dest
ESNULLP	when dest or resultp is the NULL pointer
ESZEROL	when dmax = 0 or u8nlen_s = 0
ESLEMAX	when dmax > RSIZE_MAX_STR or ch > 255
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax

See also: u8chr_s(), strrchr_s()

◆ u8lwr_s

#define u8lwr_s	(		dest,
			dmax )

Value:

_BOS_UCHK_DEST(u8lwr_s, dest, dmax)

Scans the utf-8 string converting each codepoint to simple lowercase via towlower(), leaving all other codepoints unchanged.

The scanning stops at the first NUL or after dmax bytes. The conversion is determined by the LC_CTYPE category setting of the locale; with the default "C" locale only ASCII is affected. It only performs simple case folding, not full multi-char folding, and does not obey the special-casing context rules; use u8fc_s() for that. Since a codepoint's lowercase encoding may take a different number of utf-8 bytes than its original encoding, the resulting string may be shorter or longer than the input, but always fits within dmax.

Parameters

[in,out]	dest	utf-8 string
[in]	dmax	maximum byte-length of dest

Precondition: dest shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.

Return values

EOK	on successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOSPC	when the lowercased result needs more space than dmax
EILSEQ	when dest contains an illegal utf-8 sequence

See also: u8upr_s(), u8fc_s()

◆ u8upr_s

#define u8upr_s	(		dest,
			dmax )

Value:

_BOS_UCHK_DEST(u8upr_s, dest, dmax)

Scans the utf-8 string converting each codepoint to simple uppercase via towupper(), leaving all other codepoints unchanged.

The scanning stops at the first NUL or after dmax bytes. The conversion is determined by the LC_CTYPE category setting of the locale; with the default "C" locale only ASCII is affected. It only performs simple case conversion, not full multi-char expansion (e.g. German sharp s stays unchanged), and does not obey special-casing context rules. Since a codepoint's uppercase encoding may take a different number of utf-8 bytes than its original encoding, the resulting string may be shorter or longer than the input, but always fits within dmax.

Parameters

[in,out]	dest	utf-8 string
[in]	dmax	maximum byte-length of dest

Precondition: dest shall not be a null pointer.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.

Return values

EOK	on successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOSPC	when the uppercased result needs more space than dmax
EILSEQ	when dest contains an illegal utf-8 sequence

See also: u8lwr_s(), u8fc_s()

◆ u8zero_s

#define u8zero_s	(		dest,
			dmax )

Value:

_BOS_UCHK_DEST(u8zero_s, dest, dmax)

Nulls maximal dmax bytes of the utf-8 string dest.

This function can be used to clear strings that contained sensitive data, until the terminating NUL character. With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Parameters

[out]	dest	pointer to utf-8 string that will be nulled.
[in]	dmax	restricted maximum byte-length of dest

Return values

EOK	when successful operation
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8set_s(), u8nset_s()

◆ u8coll_s

#define u8coll_s	(	dest,
		dmax,
		src,
		resultp )

Value:

    _BOS_UCHK(_BOS_DMAX_OK(dest, dmax, 1) && _BOS_KNOWN(src) &&                \
                  _BOS_KNOWN(resultp),                                         \
              _u8coll_s_uchk(dest, src, resultp),                              \
              _u8coll_s_chk(dest, dmax, src, resultp, BOS(dest)))

Compares two null-terminated utf-8 strings according to the current locale as defined by the LC_COLLATE category.

The strings are passed byte-wise to strcoll() as locale collation of utf-8 is byte-order preserving. This is the utf-8 analogue of strcoll_s().

Parameters

[in]	dest	pointer to utf-8 string to compare against
[in]	dmax	restricted maximum byte-length of string dest
[in]	src	pointer to the utf-8 string to be compared to dest
[out]	resultp	pointer to result indicator, greater than 0, equal to 0 or less than 0, if the string pointed to by dest is greater than, equal to or less than the string pointed to by src respectively.

Precondition: Neither dest, src nor resultp shall be a null pointer.; dmax shall not be 0; dmax shall not be greater than RSIZE_MAX_STR and size of dest

Returns: The error code of the result. On EOK, see resultp.

Return values

EOK	when comparison is complete and the result is returned in resultp
ESNULLP	when dest, src, or resultp is the NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8cmp_s(), u8natcmp_s()

◆ u8set_s

#define u8set_s	(	dest,
		dmax,
		value )

Value:

    _BOS_UCHK(_BOS_DMAX_OK(dest, dmax, 1) && (unsigned)(value) <= 255,         \
              _u8set_s_uchk(dest, dmax, value),                                \
              _u8set_s_chk(dest, dmax, value, BOS(dest)))

Sets maximal dmax bytes of the utf-8 string dest to a byte value, but not the final NUL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Parameters

[out]	dest	utf-8 string that will be set.
[in]	dmax	restricted maximum byte-length of dest
[in]	value	byte value to write

Precondition: dest shall not be a null pointer, and shall be null-terminated.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; dmax shall not equal zero.; value shall not be greater than 255

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when value > 255 or dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax

See also: u8zero_s(), u8nset_s()

◆ u8nset_s

#define u8nset_s	(	dest,
		dmax,
		value,
		n )

Value:

    _BOS_UCHK(_BOS_DMAX_OK(dest, dmax, 1) && (unsigned)(value) <= 255 &&       \
                  (size_t)(n) <= (size_t)(dmax),                               \
              _u8nset_s_uchk(dest, dmax, value, n),                            \
              _u8nset_s_chk(dest, dmax, value, n, BOS(dest)))

Sets maximal n bytes of the utf-8 string dest to a byte value, but not the final NUL character.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Parameters

[out]	dest	utf-8 string that will be set.
[in]	dmax	restricted maximum byte-length of dest
[in]	value	byte value to write
[in]	n	number of bytes to be written

Precondition: dest shall not be a null pointer, and shall be null-terminated.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; dmax shall not equal zero.; n shall not be greater than dmax; value shall not be greater than 255

Return values

EOK	when successful
ESNULLP	when dest is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when value > 255 or dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOSPC	when n > dmax

See also: u8zero_s(), u8set_s()

◆ u8towcs_s

#define u8towcs_s	(	retvalp,
		dest,
		dmax,
		src,
		len )

Value:

_u8towcs_s_chk(retvalp, dest, dmax, src, len, BOS(dest))

The u8towcs_s function decodes a null-terminated UTF-8 string pointed to by src, unconditionally as UTF-8 (independent of the current locale), into its wide character representation.

If dest is not null, at most len wide characters are stored in the successive elements of the wchar_t array pointed to by dest. On platforms with a 2-byte wchar_t (Windows, cygwin) codepoints above U+FFFF are stored as UTF-16 surrogate pairs.

The conversion stops if:

The UTF-8 NUL character was converted and stored.
An illegal or truncated UTF-8 sequence was encountered.
the next wide character to be stored would exceed len. This condition is not checked if dest==NULL.

With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Parameters

[out]	retvalp	pointer to a `size_t` object where the number of wide characters written (excluding the final L'\0') is stored
[out]	dest	NULL or pointer to wide character array for the result
[in]	dmax	restricted maximum length of `dest`
[in]	src	null-terminated UTF-8 string that will be converted to `dest`
[in]	len	maximal number of wide characters to be written to `dest` (exclusive the final L'\0')

Precondition: retvalp and src shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_WSTR, unless dest is null.; dmax shall not equal zero, unless dest is null.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then u8towcs_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp or src are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_WSTR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax and dest != NULL
ESOVRLP	when src and dest overlap
ESNOSPC	when the entire src does not fit within len wide characters (unless dest is null)
EILSEQ	when src contains an illegal or truncated UTF-8 sequence

See also: wcstou8_s(), mbstowcs_s()

◆ u8rtowcs_s

#define u8rtowcs_s	(	retvalp,
		dest,
		dmax,
		srcp,
		len,
		ps )

Value:

_u8rtowcs_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))

The restartable variant of u8towcs_s().

Converts a UTF-8 string, unconditionally as UTF-8 (independent of the current locale), pointed to by *srcp into wide characters stored in dest. At most len wide characters are converted, and *srcp is updated to point one past the last UTF-8 byte converted, so that a subsequent call can resume the conversion. ps is accepted for API compatibility but unused, as UTF-8 decoding needs no shift state.

Parameters

[out]	retvalp	pointer to a `size_t` object where the number of wide characters written is stored
[out]	dest	NULL or pointer to wide character array for the result
[in]	dmax	restricted maximum length of `dest`
[in,out]	srcp	pointer to the UTF-8 string pointer that will be converted to `dest`, and advanced
[in]	len	maximal number of wide characters to be written to `dest`
[in,out]	ps	unused conversion state, accepted for API compatibility

Precondition: retvalp, srcp, *srcp and ps shall not be a null pointer.; dmax and len shall not be greater than RSIZE_MAX_WSTR, unless dest is null.; dmax shall not equal zero, unless dest is null.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_WSTR, then u8rtowcs_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp, srcp, *srcp or ps are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_WSTR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESOVRLP	when *srcp and dest overlap
EILSEQ	when *srcp contains an illegal or truncated UTF-8 sequence

See also: u8towcs_s(), wcstou8_s()

◆ wcstou8_s

#define wcstou8_s	(	retvalp,
		dest,
		dmax,
		src,
		len )

Value:

_wcstou8_s_chk(retvalp, dest, dmax, src, len, BOS(dest))

The wcstou8_s function encodes a null-terminated wide character string pointed to by src into UTF-8, unconditionally (independent of the current locale).

On platforms with a 2-byte wchar_t (Windows, cygwin) UTF-16 surrogate pairs in src are combined into a single codepoint before encoding. If dest is not null, at most len UTF-8 bytes are written to the successive elements of dest.

The conversion stops if:

The wide NUL character L'\0' was converted and stored.
A wchar_t was found that does not represent a valid Unicode codepoint (encoded surrogate half or beyond U+10FFFF).
the next UTF-8 sequence to be stored would exceed len. This condition is not checked if dest==NULL.

With SAFECLIB_STR_NULL_SLACK defined the rest is cleared with 0.

Parameters

[out]	retvalp	pointer to a `size_t` object where the number of UTF-8 bytes written (excluding the final NUL) is stored
[out]	dest	NULL or pointer to UTF-8 byte array for the result
[in]	dmax	restricted maximum length of `dest`
[in]	src	null-terminated wide character string that will be converted to `dest`
[in]	len	maximal number of UTF-8 bytes to be written to `dest` (exclusive the final NUL)

Precondition: retvalp and src shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcstou8_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp or src are a NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when src and dest overlap
ESNOSPC	when the entire src does not fit within len bytes
EILSEQ	when src contains an illegal wide character (encoded surrogate half or beyond U+10FFFF)

See also: u8towcs_s(), wcstombs_s()

◆ wcsrtou8_s

#define wcsrtou8_s	(	retvalp,
		dest,
		dmax,
		srcp,
		len,
		ps )

Value:

_wcsrtou8_s_chk(retvalp, dest, dmax, srcp, len, ps, BOS(dest))

The restartable variant of wcstou8_s().

Encodes a wide character string, unconditionally as UTF-8 (independent of the current locale), pointed to by *srcp into UTF-8 bytes stored in dest. At most len bytes are written, and *srcp is updated to point one past the last wide character converted, so that a subsequent call can resume the conversion. ps is accepted for API compatibility but unused.

Parameters

[out]	retvalp	pointer to a `size_t` object where the number of UTF-8 bytes written is stored
[out]	dest	NULL or pointer to UTF-8 byte array for the result
[in]	dmax	restricted maximum length of `dest`
[in,out]	srcp	pointer to the wide string pointer that will be converted to `dest`, and advanced
[in]	len	maximal number of UTF-8 bytes to be written to `dest`
[in,out]	ps	unused conversion state, accepted for API compatibility

Precondition: retvalp, srcp, *srcp and ps shall not be a null pointer.; dmax shall not equal zero, unless dest is null.; dmax shall not be greater than RSIZE_MAX_STR, unless dest is null.; Copying shall not take place between objects that overlap.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then wcsrtou8_s nulls dest.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp, srcp, *srcp or ps are a NULL pointer
ESZEROL	when dmax = 0, unless dest is NULL
ESLEMAX	when dmax > RSIZE_MAX_STR, unless dest is NULL
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESOVRLP	when *srcp and dest overlap
EILSEQ	when *srcp contains an illegal wide character (encoded surrogate half or beyond U+10FFFF)

See also: wcstou8_s(), u8rtowcs_s()

◆ wcrtou8_s

#define wcrtou8_s	(	retvalp,
		dest,
		dmax,
		wc,
		ps )

Value:

_wcrtou8_s_chk(retvalp, dest, dmax, wc, ps, BOS(dest))

Does not permit the ps parameter (the pointer to the conversion state) to be a null pointer.

The restartable wcrtou8_s function encodes a single wide character wc, unconditionally as UTF-8 (independent of the current locale), storing 1-4 UTF-8 bytes in dest, followed by a terminating NUL. ps is accepted for API compatibility but unused, as UTF-8 encoding needs no shift state.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Parameters

[out]	retvalp	pointer to a `size_t` object where the number of UTF-8 bytes written (excluding the NUL) is stored
[out]	dest	pointer to bytes where the result will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	wc	the wide character (Unicode codepoint) to convert
[in]	ps	unused conversion state, accepted for API compatibility

Precondition: retvalp and ps shall not be a null pointer.; dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; wc shall not exceed 0x10ffff.

Returns: Returns zero on success and non-zero on failure, in which case dest[0] is set to '\0' and *retvalp is set to (size_t)-1.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp or ps are a NULL pointer
ESZEROL	when dmax = 0
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEMAX	when dmax > RSIZE_MAX_STR
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when dmax is smaller than the required bytes + NUL
EILSEQ	when wc is an encoded surrogate half or exceeds U+10FFFF

See also: wctou8_s(), wcrtomb_s()

◆ wctou8_s

#define wctou8_s	(	retvalp,
		dest,
		dmax,
		wc )

Value:

_wctou8_s_chk(retvalp, dest, dmax, wc, BOS(dest))

The wctou8_s function encodes a single wide character wc, unconditionally as UTF-8 (independent of the current locale), storing 1-4 UTF-8 bytes in dest, followed by a terminating NUL.

With SAFECLIB_STR_NULL_SLACK defined all elements following the terminating NUL character (if any) written in the array of dmax characters pointed to by dest are nulled.

Parameters

[out]	retvalp	pointer to an `int` object where the number of UTF-8 bytes written (excluding the NUL) is stored
[out]	dest	pointer to bytes where the result will be stored
[in]	dmax	restricted maximum length of `dest`
[in]	wc	the wide character (Unicode codepoint) to convert

Precondition: retvalp shall not be a null pointer.; dest shall not be a null pointer.; dmax shall not equal zero.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.; wc shall not exceed 0x10ffff.

Returns: Returns zero on success and non-zero on failure, in which case dest[0] is set to '\0' and *retvalp is set to -1.

Return values

EOK	on successful conversion.
ESNULLP	when retvalp is a NULL pointer
ESZEROL	when dmax = 0
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEMAX	when dmax > RSIZE_MAX_STR
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when dmax is smaller than the required bytes + NUL
EILSEQ	when wc is an encoded surrogate half or exceeds U+10FFFF

See also: wcrtou8_s(), wctomb_s()

◆ u8str_s

#define u8str_s	(	dest,
		dmax,
		src,
		slen,
		substringp )

Value:

_u8str_s_chk(dest, dmax, src, slen, substringp, BOS(dest), BOS(src))

The u8str_s() function locates the first occurrence of the utf-8 substring pointed to by src in the utf-8 string pointed to by dest.

The search is a literal byte-sequence match, not normalizing; since UTF-8 is self-synchronizing (no encoded codepoint is a byte-suffix of another codepoint's encoding), a byte-sequence match between two well-formed UTF-8 strings always lands on codepoint boundaries.

Parameters

[in]	dest	pointer to utf-8 string to be searched for the substring
[in]	dmax	restricted maximum byte-length of dest string
[in]	src	pointer to the utf-8 sub string
[in]	slen	the maximum number of bytes to use from src
[out]	substringp	the returned substring pointer

Precondition: Neither dest nor src shall be a null pointer.; dmax shall not be 0.; slen shall not be 0, when *src != 0 and src != dest; Neither dmax nor slen shall be greater than RSIZE_MAX_STR and size of dest/src.

Return values

EOK	when successful operation, substring found.
ESNULLP	when dest/src/substring is NULL pointer
ESZEROL	when dmax/slen = 0, unless *src = 0
ESLEMAX	when dmax/slen > RSIZE_MAX_STR
EOVERFLOW	when dmax/slen > size of dest/src (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != sizeof(dest) and –enable-error-dmax
ESNOTFND	when substring not found

See also: u8u8_s(), u8spn_s(), u8cspn_s(), u8pbrk_s()

◆ u8fc_s

#define u8fc_s	(	dest,
		dmax,
		src,
		lenp )

Value:

_u8fc_s_chk(dest, dmax, src, lenp, BOS(dest))

Converts the utf-8 string to fully fold-cased lowercase, per the Unicode CaseFolding.txt table (the same data used by u8u8_s() for case-insensitive matching).

Full case-folding performs the 105 multi-codepoint expansions specified by CaseFolding.txt (e.g. U+00DF LATIN SMALL LETTER SHARP S folds to "ss"). All other codepoints are simple-folded like towlower(). Because a folded codepoint may encode to a different number of utf-8 bytes than the original, and multi-codepoint expansions grow the string, dest should be sized generously (dmax >= 3x the byte-length of src is always sufficient).

Unlike wcsfc_s(), this implementation does not additionally NFD-decompose composed base+accent codepoints, and does not apply the locale-conditional special-casing rules (Lithuanian dotted I/J, Turkish/Azeri dotless i, Greek final sigma). Use u8norm_s() first if NFD decomposition is also required.

Parameters

[out]	dest	utf-8 string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	utf-8 string
[out]	lenp	pointer to byte-length of the result, may be NULL

Precondition: dest and src shall not be null pointers.; dmax shall not be 0.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.

Return values

EOK	on successful operation
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESNOSPC	when dmax is too small for the result. *lenp is still written, to know how much space is needed.
EILSEQ	when src contains an illegal utf-8 sequence

See also: u8u8_s(), u8lwr_s(), u8upr_s(), wcsfc_s(), u8norm_s()

◆ u8norm_decompose_s

#define u8norm_decompose_s	(	dest,
		dmax,
		src,
		lenp,
		iscompat )

Value:

_u8norm_decompose_s_chk(dest, dmax, src, lenp, iscompat, BOS(dest))

Converts the utf-8 string to the canonical NFD normalization, as defined in the latest Unicode standard,.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Composed characters are checked for the left-hand-size of the Decomposition_Mapping Unicode property, which means the codepoint will be normalized if the sequence is composed. This is equivalent to all 1963 combining mark characters, plus some remaining 869 non-mark and non-hangul normalizables. Hangul has some special normalization logic.

This function is used by u8norm_s() to do the argument checking, overlap checking and to do the first of three passes for NFC.

Parameters

[out]	dest	utf-8 string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	utf-8 string
[out]	lenp	pointer to length of the result, may be NULL
[in]	iscompat	do NFKD, and not NFD (with `--enable-norm-compat`)

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_STR and size of dest.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8norm_s nulls dest.

Return values

EOK	on success
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMIN	when dmax < 5 or 19 with a compat mode
ESLEMAX	when dmax > RSIZE_MAX_STR
EOVERFLOW	when dmax > size of dest (optionally, when the compiler knows the object_size statically)
ESLEWRNG	when dmax != size of dest and –enable-error-dmax
ESOVRLP	when buffers overlap
ESNOSPC	when dmax too small for the result buffer
EOF	on some normalization error

See also: u8fc_s(), u8norm_s(), u8norm_compose_s(), u8norm_reorder_s(), ICU, gnulib/libunistring, utf8proc

◆ u8norm_reorder_s

#define u8norm_reorder_s	(	dest,
		dmax,
		src,
		len )

Value:

_u8norm_reorder_s_chk(dest, dmax, src, len, BOS(dest))

Reorder all decomposed sequences in a utf-8 string to NFD, as defined in the latest Unicode standard,.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Parameters

[out]	dest	utf-8 string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	utf-8 string to be converted
[in]	len	length of src

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8norm_reorder_s nulls dest.

Return values

EOK	on success
ESNOSPC	when dmax too small for the result buffer
EOF	on some normalization error

See also: u8norm_s(), u8norm_decompose_s(), ICU, gnulib/libunistring, utf8proc

◆ u8norm_compose_s

#define u8norm_compose_s	(	dest,
		dmax,
		src,
		lenp,
		iscontig )

Value:

_u8norm_compose_s_chk(dest, dmax, src, lenp, iscontig, BOS(dest))

Combine all decomposed sequences in a utf-8 string to NFC, as defined in the latest Unicode standard,.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

Parameters

[out]	dest	utf-8 string to hold the result
[in]	dmax	maximum result buffer size
[in]	src	utf-8 string to be converted
[out]	lenp	pointer to length of p and the result length.
[in]	iscontig	if true, the result will only be a fast FCC

Precondition: dest, src and lenp shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8norm_reorder_s nulls dest.

Return values

EOK	on success
ESNOSPC	when dmax too small for the result buffer
EOF	on some normalization error

See also: u8norm_s(), u8norm_decompose_s(), ICU, gnulib/libunistring, utf8proc

◆ u8norm_s

#define u8norm_s	(	dest,
		dmax,
		src,
		mode,
		lenp )

Value:

_u8norm_s_chk(dest, dmax, src, mode, lenp, BOS(dest))

Converts the utf-8 string to the canonical NFC or NFD normalization, as defined in the latest Unicode standard,.

See also: SAFECLIB_UNICODE_VERSION. The conversion stops at the first null or after dmax characters.

The default mode should always be NFD. Decomposed characters are checked for the left-hand-size and then right-hand-side of the Decomposition_Mapping Unicode property, which means the codepoint will be normalized if the sequence is composed or decomposed (NFD or NFKD). This is equivalent to all 1963 combining mark characters, plus some remaining 869 non-mark and non-hangul normalizables. Hangul has some special normalization logic.

The compat tables for NFKC or NFKD are too large for a libc, and mostly unused. As default we only provide the smaller canonical conversions, but it can be enabled with --enable-norm-compat. The compat modes also don't roundtrip.

Parameters

[out]	dest	utf-8 string to hold the result
[in]	dmax	maximum length of string
[in]	src	utf-8 string
[in]	mode	convert to nfc or just nfd. experimentally to fast modes FCD or FCC. optionally to compat modes NFKD, NFKC with `–enable-norm-compat`

See also: enum u8norm_mode.

Parameters

[out] lenp pointer to length of the result, may be NULL

Precondition: dest and src shall not be null pointers.; dmax shall not equal zero and big enough for dest.; dmax shall not be greater than RSIZE_MAX_STR.

Returns: If there is a runtime-constraint violation, then if dest is not a null pointer and dmax is greater than zero and not greater than RSIZE_MAX_STR, then u8norm_s nulls dest.

Return values

EOK	on success
ESNULLP	when dest or src is NULL pointer
ESZEROL	when dmax = 0
ESLEMIN	when dmax < 5
ESLEMAX	when dmax > RSIZE_MAX_STR
ESOVRLP	when buffers overlap
ESNOSPC	when dmax too small for the result buffer
EOF	any other normalization error

See also: u8fc_s(), ICU, gnulib/libunistring, utf8proc

Typedef Documentation

◆ char8i_t

typedef char8_t char8i_t

Function Documentation

◆ _u8cat_s_chk()

EXTERN errno_t _u8cat_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const size_t	destbos )

◆ _u8cpy_s_chk()

EXTERN errno_t _u8cpy_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const size_t	destbos )

◆ _u8icpy_s_chk()

EXTERN errno_t _u8icpy_s_chk	(	char8i_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const size_t	destbos )

◆ _u8icat_s_chk()

EXTERN errno_t _u8icat_s_chk	(	char8i_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const size_t	destbos )

◆ _u8ncat_s_chk()

EXTERN errno_t _u8ncat_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos ) &&

◆ BOS_ATTR() [1/4]

EXTERN errno_t empty dest or dmax BOS_ATTR	(	(slen\|\|dest\|\|dmax) &&_BOS_OVR(dest, dmax)	,
		"dest overflow"	)

◆ _u8ncpy_s_chk()

EXTERN errno_t _u8ncpy_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t	slen,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8len_s_chk()

EXTERN rsize_t _u8len_s_chk	(	const char8_t *	str,
		size_t	strbos )

◆ _u8nlen_s_chk()

EXTERN rsize_t _u8nlen_s_chk	(	const char8_t *	str,
		rsize_t	smax,
		size_t	strbos )

◆ _u8nlen_s_uchk()

EXTERN rsize_t _u8nlen_s_uchk	(	const char8_t *	str,
		rsize_t	smax )

◆ _u8width_s_chk()

EXTERN rsize_t _u8width_s_chk	(	const char8_t *	str,
		rsize_t	smax,
		size_t	strbos )

◆ _u8width_s_uchk()

EXTERN rsize_t _u8width_s_uchk	(	const char8_t *	str,
		rsize_t	smax )

◆ _u8tok_s_chk()

EXTERN char8_t * _u8tok_s_chk	(	char8_t *restrict	dest,
		rsize_t *restrict	dmaxp,
		const char8_t *restrict	delim,
		char8_t **restrict	ptr,
		const size_t	destbos ) &&

◆ BOS_NULL() [1/9]

EXTERN char8_t empty dmax BOS_NULL ( delim )

◆ _u8sprintf_s_chk()

EXTERN int _u8sprintf_s_chk	(	char8_t *restrict	dest,
		const rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
			... )

◆ BOS_CHK()

EXTERN int BOS_CHK ( dest )

◆ _vu8sprintf_s_chk()

EXTERN int _vu8sprintf_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
		va_list	ap )

◆ _u8snprintf_s_chk()

EXTERN int _u8snprintf_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
			... )

◆ _vu8snprintf_s_chk()

EXTERN int _vu8snprintf_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const size_t	destbos,
		const char *restrict	fmt,
		va_list	ap )

◆ u8sscanf_s()

EXTERN int u8sscanf_s	(	const char8_t *restrict	buffer,
		const char *restrict	fmt,
			... )

◆ BOS_NULL() [2/9]

EXTERN int BOS_NULL ( buffer )

◆ fu8scanf_s()

EXTERN int fu8scanf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
			... )

◆ BOS_NULL() [3/9]

EXTERN int BOS_NULL ( stream )

◆ u8scanf_s()

EXTERN int u8scanf_s	(	const char *restrict	fmt,
			... )

◆ BOS_FMT()

EXTERN int BOS_FMT ( fmt )

◆ vu8scanf_s()

EXTERN int vu8scanf_s	(	const char *restrict	fmt,
		va_list	ap )

The vu8scanf_s function reads a formatted string from stdin, and writes to a list of arguments.

Parameters

[in]	fmt	format-control string.
[out]	ap	arguments to write to

Precondition: fmt shall not be a null pointer.; fmt shall not contain the conversion specifier n

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: u8scanf_s(), vscanf_s()

◆ vfu8scanf_s()

EXTERN int vfu8scanf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
		va_list	ap )

The vfu8scanf_s function reads a formatted utf-8 string from a buffered FILE stream, and writes to a list of arguments.

Parameters

[in]	stream	pointer to a FILE stream to read from
[in]	fmt	format-control string.
[out]	ap	arguments to write to

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error

See also: fu8scanf_s(), vfscanf_s()

◆ vu8sscanf_s()

EXTERN int vu8sscanf_s	(	const char8_t *restrict	dest,
		const char *restrict	fmt,
		va_list	ap )

The vu8sscanf_s function reads a formatted utf-8 string, and writes to a list of arguments.

Like u8sscanf_s(), the c, s, and %[ conversion specifiers here require their Annex K companion rsize_t destination-size argument: it is always consumed and enforced.

Parameters

[in]	dest	pointer to a NUL-terminated utf-8 string to read from
[in]	fmt	format-control string.
[out]	ap	arguments to write to; every `c`, `s`, and `%`[ is followed by an `rsize_t` giving the size of its destination array

Precondition: Neither dest nor fmt shall be a null pointer.; dest shall not contain an illegal or truncated UTF-8 sequence.; c, s, and %[ conversion specifiers each expect two arguments (the usual pointer and a value of type rsize_t indicating the size of the receiving array, which may be 1 when reading with a c into a single character).

Returns: Number of receiving arguments successfully assigned, or EOF if read failure occurs before the first receiving argument was assigned or if there is a runtime constraint violation.

Return values

>	0 on success, the number of arguments assigned
EOF	on error, or when `dest` contains illegal UTF-8 or a `c/s/%[ destination` is too small (errno set to `EILSEQ` resp. `ESNOSPC`)

See also: u8sscanf_s(), vsscanf_s()

◆ u8printf_s()

EXTERN int u8printf_s	(	const char *restrict	fmt,
			... )

◆ fu8printf_s()

EXTERN int fu8printf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
			... )

◆ vu8printf_s()

EXTERN int vu8printf_s	(	const char *restrict	fmt,
		va_list	ap )

The vu8printf_s function composes a string via the format string and writes it, as utf-8, to the STDOUT file.

Parameters

[in]	fmt	format-control string
[in]	ap	optional arguments

Precondition: fmt shall not be a null pointer.; fmt shall not contain the conversion specifier n.

Returns: On success the total number of bytes written is returned.; On failure a negative number is returned.

Return values

-ESNULLP	when fmt is NULL pointer
-EINVAL	when fmt contains n
-1	on some other error. errno is set then.

See also: u8printf_s(), vprintf_s()

◆ vfu8printf_s()

EXTERN int vfu8printf_s	(	FILE *restrict	stream,
		const char *restrict	fmt,
		va_list	arg )

The vfu8printf_s function composes a string via the format string and writes it, as utf-8, to a FILE stream.

Parameters

[out]	stream	output file stream to write to
[in]	fmt	format-control string.
[in]	arg	optional arguments

Precondition: Neither stream nor fmt shall be a null pointer.; fmt shall not contain the conversion specifier n.

Returns: On success the total number of bytes written is returned.; On failure a negative number is returned.

Return values

-ESNULLP	when stream or fmt is NULL pointer
-EINVAL	when fmt contains n
-1	on some other error. errno is set then.

See also: fu8printf_s(), vfprintf_s()

◆ _u8error_s_chk()

EXTERN errno_t _u8error_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		errno_t	errnum,
		const size_t	destbos )

◆ u8errorlen_s()

EXTERN size_t u8errorlen_s ( errno_t errnum )

The u8errorlen_s function returns the untruncated byte-length of the textual description of the system error code errnum, identical to the description that would be printed by perror().

Error messages are plain ASCII, so their byte-length equals their utf-8 character length.

Parameters

[in] errnum integer value referring to an error code

Returns: The length of the error message or 0

See also: u8error_s(), strerrorlen_s()

◆ _u8cmp_s_chk()

EXTERN errno_t _u8cmp_s_chk	(	const char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8icmp_s_chk()

EXTERN errno_t _u8icmp_s_chk	(	const char8i_t *	dest,
		rsize_t	dmax,
		const char8i_t *	src,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8fccmp_s_chk()

EXTERN errno_t _u8fccmp_s_chk	(	const char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		int *	resultp,
		const size_t	destbos )

◆ _u8natcmp_s_chk()

EXTERN errno_t _u8natcmp_s_chk	(	const char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		const int	fold_case,
		int *	resultp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8fcu8_s_chk()

EXTERN errno_t _u8fcu8_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		rsize_t	slen,
		char8_t **	substring,
		const size_t	destbos,
		const size_t	srcbos )

◆ BOS_NULL() [4/9]

EXTERN errno_t slen BOS_NULL ( substring )

◆ _u8ifcu8_s_chk()

EXTERN errno_t _u8ifcu8_s_chk	(	char8i_t *	dest,
		rsize_t	dmax,
		const char8i_t *	src,
		rsize_t	slen,
		char8i_t **	substring,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8cspn_s_chk()

EXTERN errno_t _u8cspn_s_chk	(	const char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		rsize_t	slen,
		rsize_t *	countp,
		const size_t	destbos,
		const size_t	srcbos )

◆ BOS_NULL() [5/9]

EXTERN errno_t slen BOS_NULL ( countp )

◆ _u8pbrk_s_chk()

EXTERN errno_t _u8pbrk_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		char8_t *	src,
		rsize_t	slen,
		char8_t **	firstp,
		const size_t	destbos,
		const size_t	srcbos )

◆ BOS_NULL() [6/9]

EXTERN errno_t slen BOS_NULL ( firstp )

◆ _u8spn_s_chk()

EXTERN errno_t _u8spn_s_chk	(	const char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		rsize_t	slen,
		rsize_t *	countp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8u8_s_chk()

EXTERN errno_t _u8u8_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		const char8_t *	src,
		rsize_t	slen,
		char8_t **	substringp,
		const size_t	destbos,
		const size_t	srcbos )

◆ BOS_NULL() [7/9]

EXTERN errno_t slen BOS_NULL ( substringp )

◆ _u8iu8i_s_chk()

EXTERN errno_t _u8iu8i_s_chk	(	char8i_t *	dest,
		rsize_t	dmax,
		const char8i_t *	src,
		rsize_t	slen,
		char8i_t **	substringp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8chr_s_chk()

EXTERN errno_t _u8chr_s_chk	(	const char8_t *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char8_t **restrict	resultp,
		const size_t	destbos )

◆ BOS_NULL() [8/9]

EXTERN errno_t BOS_NULL ( resultp )

◆ _u8chr_s_uchk()

EXTERN errno_t _u8chr_s_uchk	(	const char8_t *	dest,
		rsize_t	dmax,
		const int	ch,
		char8_t **	resultp )

◆ _u8rchr_s_chk()

EXTERN errno_t _u8rchr_s_chk	(	const char8_t *restrict	dest,
		rsize_t	dmax,
		const int	ch,
		char8_t **restrict	resultp,
		const size_t	destbos )

◆ _u8rchr_s_uchk()

EXTERN errno_t _u8rchr_s_uchk	(	const char8_t *	dest,
		rsize_t	dmax,
		const int	ch,
		char8_t **	resultp )

◆ _u8lwr_s_chk()

EXTERN errno_t _u8lwr_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		const size_t	destbos )

◆ _u8lwr_s_uchk()

EXTERN errno_t _u8lwr_s_uchk	(	char8_t *	dest,
		rsize_t	dmax )

◆ _u8upr_s_chk()

EXTERN errno_t _u8upr_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		const size_t	destbos )

◆ _u8upr_s_uchk()

EXTERN errno_t _u8upr_s_uchk	(	char8_t *	dest,
		rsize_t	dmax )

◆ _u8zero_s_chk()

EXTERN errno_t _u8zero_s_chk	(	char8_t *	dest,
		rsize_t	dmax,
		const size_t	destbos )

◆ _u8zero_s_uchk()

EXTERN errno_t _u8zero_s_uchk	(	char8_t *	dest,
		rsize_t	dmax )

◆ _u8coll_s_chk()

EXTERN errno_t _u8coll_s_chk	(	const char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		int *	resultp,
		const size_t	destbos )

◆ _u8coll_s_uchk()

EXTERN errno_t _u8coll_s_uchk	(	const char8_t *	dest,
		const char8_t *	src,
		int *	resultp )

◆ _u8set_s_chk()

EXTERN errno_t _u8set_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		int	value,
		const size_t	destbos )

◆ _u8set_s_uchk()

EXTERN errno_t EXTERN errno_t _u8set_s_uchk	(	char8_t *	dest,
		rsize_t	dmax,
		int	value )

◆ _u8nset_s_chk()

EXTERN errno_t _u8nset_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		int	value,
		rsize_t	n,
		const size_t	destbos )

◆ VAL_OVR2() [1/2]

EXTERN errno_t n VAL_OVR2	(	value	,
		255	)

◆ _u8nset_s_uchk()

EXTERN errno_t _u8nset_s_uchk	(	char8_t *	dest,
		rsize_t	dmax,
		int	value,
		rsize_t	n )

◆ _u8towcs_s_chk()

EXTERN errno_t _u8towcs_s_chk	(	size_t *restrict	retvalp,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t	len,
		const size_t	destbos ) &&

◆ BOS_ATTR() [2/4]

EXTERN errno_t empty dmax BOS_ATTR	(	!	_BOS_NULLdest) &&_BOSW_OVR(dest, dmax,
		"dest overflow"	) &&

◆ BOS_CHK2()

EXTERN errno_t empty dmax dest overlap BOS_CHK2	(	src	,
		len	)

◆ _u8rtowcs_s_chk()

EXTERN errno_t _u8rtowcs_s_chk	(	size_t *restrict	retvalp,
		wchar_t *restrict	dest,
		rsize_t	dmax,
		const char8_t **restrict	srcp,
		rsize_t	len,
		mbstate_t *restrict	ps,
		const size_t	destbos ) &&

◆ BOS_ATTR() [3/4]

EXTERN errno_t empty dmax dest overlap BOS_CHK2 srcp BOS_ATTR	(	dmax &&	len,
		dmax	,
		"len	overflow,
		dmax"	)

◆ _wcstou8_s_chk()

EXTERN errno_t _wcstou8_s_chk	(	size_t *restrict	retvalp,
		char8_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t *restrict	src,
		rsize_t	len,
		const size_t	destbos )

◆ _wcsrtou8_s_chk()

EXTERN errno_t _wcsrtou8_s_chk	(	size_t *restrict	retvalp,
		char8_t *restrict	dest,
		rsize_t	dmax,
		const wchar_t **restrict	srcp,
		rsize_t	len,
		mbstate_t *restrict	ps,
		const size_t	destbos ) &&

◆ BOS_ATTR() [4/4]

EXTERN errno_t empty dmax BOS_ATTR	(	!	_BOS_NULLdest) &&_BOS_OVR(dest, dmax,
		"dest overflow"	) &&

◆ BOS_NULL() [9/9]

EXTERN errno_t empty dmax dest overlap BOS_NULL ( srcp )

◆ _wcrtou8_s_chk()

EXTERN errno_t _wcrtou8_s_chk	(	size_t *restrict	retvalp,
		char8_t *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc,
		mbstate_t *restrict	ps,
		const size_t	destbos )

◆ _wctou8_s_chk()

EXTERN errno_t _wctou8_s_chk	(	int *restrict	retvalp,
		char8_t *restrict	dest,
		rsize_t	dmax,
		wchar_t	wc,
		const size_t	destbos ) &&

◆ VAL_OVR2() [2/2]

EXTERN errno_t dest overflow or empty VAL_OVR2	(	wc	,
		0x10ffff	)

◆ _u8str_s_chk()

EXTERN errno_t _u8str_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t	slen,
		char8_t **restrict	substringp,
		const size_t	destbos,
		const size_t	srcbos )

◆ _u8fc_s_chk()

EXTERN errno_t _u8fc_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t *restrict	lenp,
		const size_t	destbos )

◆ _u8norm_decompose_s_chk()

EXTERN errno_t _u8norm_decompose_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t *restrict	lenp,
		const bool	iscompat,
		const size_t	destbos )

◆ _u8norm_reorder_s_chk()

EXTERN errno_t _u8norm_reorder_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const rsize_t	len,
		const size_t	destbos )

◆ _u8norm_compose_s_chk()

EXTERN errno_t _u8norm_compose_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		rsize_t *restrict	lenp,
		bool	iscontig,
		const size_t	destbos )

◆ _u8norm_s_chk()

EXTERN errno_t _u8norm_s_chk	(	char8_t *restrict	dest,
		rsize_t	dmax,
		const char8_t *restrict	src,
		const wcsnorm_mode_t	mode,
		rsize_t *restrict	lenp,
		const size_t	destbos )

Variable Documentation

◆ dmax

EXTERN errno_t dmax

◆ slen

EXTERN errno_t slen

◆ smax

EXTERN rsize_t smax

◆ dest

EXTERN errno_t empty* dest

◆ len

EXTERN errno_t len

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

◆ u8cat_s

◆ u8cpy_s

◆ u8icpy_s

◆ u8icat_s

◆ u8ncat_s

◆ u8ncpy_s

◆ u8len_s

◆ u8nlen_s

◆ u8width_s

◆ u8tok_s

◆ u8sprintf_s

◆ vu8sprintf_s

◆ u8snprintf_s

◆ vu8snprintf_s

◆ u8error_s

◆ u8cmp_s

◆ u8icmp_s

◆ u8fccmp_s

◆ u8natcmp_s

◆ u8natfccmp_s

◆ u8fcu8_s

◆ u8ifcu8_s

◆ u8cspn_s

◆ u8pbrk_s

◆ u8spn_s

◆ u8u8_s

◆ u8iu8i_s

◆ u8chr_s

◆ u8rchr_s

◆ u8lwr_s

◆ u8upr_s

◆ u8zero_s

◆ u8coll_s

◆ u8set_s

◆ u8nset_s

◆ u8towcs_s

◆ u8rtowcs_s

◆ wcstou8_s

◆ wcsrtou8_s

◆ wcrtou8_s

◆ wctou8_s

◆ u8str_s

◆ u8fc_s

◆ u8norm_decompose_s

◆ u8norm_reorder_s

◆ u8norm_compose_s

◆ u8norm_s

Typedef Documentation

◆ char8i_t

Function Documentation

◆ _u8cat_s_chk()

◆ _u8cpy_s_chk()

◆ _u8icpy_s_chk()

◆ _u8icat_s_chk()

◆ _u8ncat_s_chk()

◆ BOS_ATTR() [1/4]

◆ _u8ncpy_s_chk()

◆ _u8len_s_chk()

◆ _u8nlen_s_chk()

◆ _u8nlen_s_uchk()

◆ _u8width_s_chk()

◆ _u8width_s_uchk()

◆ _u8tok_s_chk()

◆ BOS_NULL() [1/9]

◆ _u8sprintf_s_chk()

◆ BOS_CHK()

◆ _vu8sprintf_s_chk()

◆ _u8snprintf_s_chk()

◆ _vu8snprintf_s_chk()

◆ u8sscanf_s()

◆ BOS_NULL() [2/9]

◆ fu8scanf_s()

◆ BOS_NULL() [3/9]

◆ u8scanf_s()

◆ BOS_FMT()