Utility functions for handling multibyte strings. More...

#include "tuklib_common.h"

Macros
#define	tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width)

#define	tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw)

Functions
size_t	tuklib_mbstr_width (const char str, size_t bytes)
	Get the number of columns needed for the multibyte string.

int	tuklib_mbstr_fw (const char *str, int columns_min)
	Get the field width for printf() e.g. to align table columns.

Detailed Description

Utility functions for handling multibyte strings.

If not enough multibyte string support is available in the C library, these functions keep working with the assumption that all strings are in a single-byte character set without combining characters, e.g. US-ASCII or ISO-8859-*.

Macro Definition Documentation

◆ tuklib_mbstr_fw

#define tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw)

◆ tuklib_mbstr_width

#define tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width)

Function Documentation

◆ tuklib_mbstr_fw()

int tuklib_mbstr_fw	(	const char *	str,
		int	columns_min )

extern

Get the field width for printf() e.g. to align table columns.

Printing simple tables to a terminal can be done using the field field feature in the printf() format string, but it works only with single-byte character sets. To do the same with multibyte strings, tuklib_mbstr_fw() can be used to calculate appropriate field width.

The behavior of this function is undefined, if

str is NULL or not terminated with '\0';
columns_min <= 0; or
the calculated field width exceeds INT_MAX.

Returns: If tuklib_mbstr_width(str, NULL) fails, -1 is returned. If str needs more columns than columns_min, zero is returned. Otherwise a positive integer is returned, which can be used as the field width, e.g. printf("%*s", fw, str).

◆ tuklib_mbstr_width()

size_t tuklib_mbstr_width	(	const char *	str,
		size_t *	bytes )

extern

Get the number of columns needed for the multibyte string.

This is somewhat similar to wcswidth() but works on multibyte strings.

Parameters

str	String whose width is to be calculated. If the current locale uses a multibyte character set that has shift states, the string must begin and end in the initial shift state.
bytes	If this is not NULL, *bytes is set to the value returned by strlen(str) (even if an error occurs when calculating the width).

Returns: On success, the number of columns needed to display the string e.g. in a terminal emulator is returned. On error, (size_t)-1 is returned. Possible errors include invalid, partial, or non-printable multibyte character in str, or that str doesn't end in the initial shift state.

Macros