#include <wireshark.h>
#include <wsutil/wmem/wmem.h>

Macros
#define	FORMAT_SIZE_PREFIX_SI (1 << 0)

#define	FORMAT_SIZE_PREFIX_IEC (1 << 1)

#define	format_size(size, unit, flags) format_size_wmem(NULL, size, unit, flags)
	Convenience macro for formatting a size value using the NULL allocator.

#define	HEXDUMP_ASCII_MASK (0x0003U)
	Bitmask for extracting ASCII display options from a hexdump configuration.

#define	HEXDUMP_ASCII_OPTION(option) ((option) & HEXDUMP_ASCII_MASK)
	Extract the ASCII display option from a hexdump flags value.

#define	HEXDUMP_ASCII_INCLUDE (0x0000U)
	Include ASCII section in hexdump output without delimiters.

#define	HEXDUMP_ASCII_DELIMIT (0x0001U)
	Include ASCII section with delimiters for reliable parsing.

#define	HEXDUMP_ASCII_EXCLUDE (0x0002U)
	Exclude ASCII section from hexdump output entirely.

#define	plurality(d, s, p) ((d) == 1 ? (s) : (p))
	Selects a singular or plural string based on a count.

#define	true_or_false(val) ((val) ? "TRUE" : "FALSE")
	Converts a boolean value to a string literal.

#define	string_or_null(val) ((val) ? (val) : "[NULL]")
	Returns a string or a placeholder if NULL.

Enumerations
enum	format_size_units_e { FORMAT_SIZE_UNIT_NONE , FORMAT_SIZE_UNIT_BYTES , FORMAT_SIZE_UNIT_BITS , FORMAT_SIZE_UNIT_BITS_S , FORMAT_SIZE_UNIT_BYTES_S , FORMAT_SIZE_UNIT_PACKETS , FORMAT_SIZE_UNIT_PACKETS_S , FORMAT_SIZE_UNIT_EVENTS , FORMAT_SIZE_UNIT_EVENTS_S , FORMAT_SIZE_UNIT_FIELDS , FORMAT_SIZE_UNIT_SECONDS , FORMAT_SIZE_UNIT_ERLANGS }
	Unit types used by `format_size_wmem()` for formatting size values. More...

enum	hex_dump_enc { HEXDUMP_ENC_ASCII = 0 , HEXDUMP_ENC_EBCDIC = 1 }
	Character encoding types supported by hex dump formatting. More...

Functions
WS_DLL_PUBLIC char *	wmem_strconcat (wmem_allocator_t allocator, const char first,...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED
	Concatenate multiple strings into a single newly allocated string.

WS_DLL_PUBLIC char *	wmem_strjoin (wmem_allocator_t allocator, const char separator, const char *first,...) G_GNUC_MALLOC G_GNUC_NULL_TERMINATED
	Join multiple strings using a separator into a single newly allocated string.

WS_DLL_PUBLIC char *	wmem_strjoinv (wmem_allocator_t allocator, const char separator, char **str_array) G_GNUC_MALLOC
	Joins a number of strings together to form one long string, with the optional separator inserted between each of them.

WS_DLL_PUBLIC char **	wmem_strsplit (wmem_allocator_t allocator, const char src, const char *delimiter, int max_tokens)
	Splits a string into a maximum of max_tokens pieces, using the given delimiter.

WS_DLL_PUBLIC char *	wmem_ascii_strdown (wmem_allocator_t allocator, const char str, ssize_t len)
	Converts all upper case ASCII letters to lower case ASCII letters.

WS_DLL_PUBLIC char *	ascii_strdown_inplace (char *str)
	In-place converstion of upper-case ASCII letters to lower-case.

WS_DLL_PUBLIC char *	ascii_strup_inplace (char *str)
	In-place converstion of lower-case ASCII letters to upper-case.

WS_DLL_PUBLIC bool	isprint_string (const char *str)
	Check if an entire string consists of printable characters.

WS_DLL_PUBLIC bool	isprint_utf8_string (const char *str, const unsigned length)

WS_DLL_PUBLIC bool	isdigit_string (const char *str)
	Check if an entire string consists of digits.

WS_DLL_PUBLIC const char *	ws_ascii_strcasestr (const char haystack, const char needle)

WS_DLL_PUBLIC const uint8_t *	ws_memrchr (const void *haystack, int ch, size_t n)

WS_DLL_PUBLIC char *	ws_escape_string (wmem_allocator_t alloc, const char string, bool add_quotes)
	Escape a null-terminated string for safe display or output.

WS_DLL_PUBLIC char *	ws_escape_string_len (wmem_allocator_t alloc, const char string, ssize_t len, bool add_quotes)
	Escape a string of specified length for safe display or output.

WS_DLL_PUBLIC char *	ws_escape_null (wmem_allocator_t alloc, const char string, size_t len, bool add_quotes)
	Escape null bytes in a string for safe display or logging.

WS_DLL_PUBLIC char *	ws_escape_csv (wmem_allocator_t alloc, const char string, bool add_quotes, char quote_char, bool double_quote, bool escape_whitespace)
	Escape as in a number of CSV dialects.

WS_DLL_PUBLIC int	ws_xton (char ch)
	Convert a hexadecimal character to its numeric value.

WS_DLL_PUBLIC char *	format_units (wmem_allocator_t *allocator, double size, format_size_units_e unit, uint16_t flags, int precision)

WS_DLL_PUBLIC char *	format_size_wmem (wmem_allocator_t *allocator, int64_t size, format_size_units_e unit, uint16_t flags)

WS_DLL_PUBLIC char	printable_char_or_period (char c)
	Return a printable character or '.' if non-printable.

WS_DLL_PUBLIC WS_RETNONNULL const char *	ws_strerrorname_r (int errnum, char *buf, size_t buf_size)
	Return the symbolic name of an error code.

WS_DLL_PUBLIC char *	ws_strdup_underline (wmem_allocator_t *allocator, long offset, size_t len)
	Create a string of underscores for visual alignment or highlighting.

WS_DLL_PUBLIC char *	format_text (wmem_allocator_t allocator, const char string, size_t len)

WS_DLL_PUBLIC char *	format_text_string (wmem_allocator_t allocator, const char string)

WS_DLL_PUBLIC char *	format_text_wsp (wmem_allocator_t allocator, const char line, size_t len)

WS_DLL_PUBLIC char *	format_text_chr (wmem_allocator_t allocator, const char string, size_t len, char chr)

WS_DLL_PUBLIC char *	format_char (wmem_allocator_t *allocator, char c)

WS_DLL_PUBLIC char *	ws_utf8_truncate (char *string, size_t len)

WS_DLL_PUBLIC void	EBCDIC_to_ASCII (uint8_t *buf, unsigned bytes)
	Convert a buffer of EBCDIC-encoded bytes to ASCII in-place.

WS_DLL_PUBLIC uint8_t	EBCDIC_to_ASCII1 (uint8_t c)
	Convert a single EBCDIC-encoded byte to its ASCII equivalent.

WS_DLL_PUBLIC bool	hex_dump_buffer (bool(print_line)(void , const char ), void fp, const unsigned char *cp, unsigned length, hex_dump_enc encoding, unsigned ascii_option)
	Generate a formatted hex dump of a byte buffer.

Detailed Description

String utility definitions

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

◆ format_size

#define format_size	(	size,
		unit,
		flags
	)	format_size_wmem(NULL, size, unit, flags)

Convenience macro for formatting a size value using the NULL allocator.

This macro wraps format_size_wmem() with a NULL allocator.

Parameters

size	The size value to format.
unit	The base unit to use (e.g., bytes, bits), specified by `format_size_units_e`.
flags	Flags to control formatting behavior (e.g., SI vs IEC, unit suffixes). Unit and prefix flags may be ORed together.

Returns: A newly allocated null-terminated string representing the formatted size, or NULL on failure.

◆ FORMAT_SIZE_PREFIX_IEC

#define FORMAT_SIZE_PREFIX_IEC (1 << 1)

IEC (power of 1024) prefixes will be used.

◆ FORMAT_SIZE_PREFIX_SI

#define FORMAT_SIZE_PREFIX_SI (1 << 0)

SI (power of 1000) prefixes will be used.

◆ HEXDUMP_ASCII_DELIMIT

#define HEXDUMP_ASCII_DELIMIT (0x0001U)

Include ASCII section with delimiters for reliable parsing.

Useful when post-processing or detecting the end of hex data programmatically.

◆ HEXDUMP_ASCII_EXCLUDE

#define HEXDUMP_ASCII_EXCLUDE (0x0002U)

Exclude ASCII section from hexdump output entirely.

Use this when the ASCII portion is unnecessary or undesired in reports.

◆ HEXDUMP_ASCII_INCLUDE

#define HEXDUMP_ASCII_INCLUDE (0x0000U)

Include ASCII section in hexdump output without delimiters.

This reflects legacy tshark behavior, where the ASCII portion is appended directly after the hex bytes.

◆ HEXDUMP_ASCII_OPTION

#define HEXDUMP_ASCII_OPTION ( option ) ((option) & HEXDUMP_ASCII_MASK)

Extract the ASCII display option from a hexdump flags value.

Parameters

option The full hexdump option bitfield.

Returns: The masked ASCII option value.

◆ plurality

#define plurality	(	d,
		s,
		p
	)	((d) == 1 ? (s) : (p))

Selects a singular or plural string based on a count.

Useful for formatting messages that depend on quantity.

Parameters

d	The numeric count.
s	The singular form of the string.
p	The plural form of the string.

Returns: s if d == 1, otherwise p.

◆ string_or_null

#define string_or_null ( val ) ((val) ? (val) : "[NULL]")

Returns a string or a placeholder if NULL.

Parameters

val	Pointer to a string.

Returns: val if non-NULL, otherwise "[NULL]".

◆ true_or_false

#define true_or_false ( val ) ((val) ? "TRUE" : "FALSE")

Converts a boolean value to a string literal.

Parameters

val	Boolean expression.

Returns: "TRUE" if val is non-zero, "FALSE" otherwise.

Enumeration Type Documentation

◆ format_size_units_e

enum format_size_units_e

Unit types used by format_size_wmem() for formatting size values.

Specifies the base unit to append to a formatted size string. Some units adapt their suffix depending on whether a prefix (e.g., "K", "Mi") is applied. For example, "bytes" becomes "B" when prefixed, and "bits/s" becomes "bps".

These values are used in conjunction with formatting flags to control output from functions like format_size_wmem() and format_size().

Enumerator
FORMAT_SIZE_UNIT_NONE	No unit will be appended. You must supply your own.
FORMAT_SIZE_UNIT_BYTES	"bytes" for un-prefixed sizes, "B" otherwise.
FORMAT_SIZE_UNIT_BITS	"bits" for un-prefixed sizes, "b" otherwise.
FORMAT_SIZE_UNIT_BITS_S	"bits/s" for un-prefixed sizes, "bps" otherwise.
FORMAT_SIZE_UNIT_BYTES_S	"bytes/s" for un-prefixed sizes, "Bps" otherwise.
FORMAT_SIZE_UNIT_PACKETS	"packets"
FORMAT_SIZE_UNIT_PACKETS_S	"packets/s"
FORMAT_SIZE_UNIT_EVENTS	"events"
FORMAT_SIZE_UNIT_EVENTS_S	"events/s"
FORMAT_SIZE_UNIT_FIELDS	"fields"
FORMAT_SIZE_UNIT_SECONDS	"seconds" for un-prefixed sizes, "s" otherwise.
FORMAT_SIZE_UNIT_ERLANGS	"erlangs" for un-prefixed sizes, "E" otherwise.

◆ hex_dump_enc

enum hex_dump_enc

Character encoding types supported by hex dump formatting.

Specifies the encoding used when rendering the ASCII portion of a hex dump. This affects how byte values are interpreted and displayed in the printable column.

Enumerator
HEXDUMP_ENC_ASCII	Interpret bytes as standard ASCII characters.
HEXDUMP_ENC_EBCDIC	Interpret bytes using EBCDIC encoding.

Function Documentation

◆ ascii_strdown_inplace()

WS_DLL_PUBLIC char * ascii_strdown_inplace ( char * str )

In-place converstion of upper-case ASCII letters to lower-case.

Convert all upper-case ASCII letters to their ASCII lower-case equivalents, in place, with a simple non-locale-dependent ASCII mapping (A-Z -> a-z). All other characters are left unchanged, as the mapping to lower case may be locale-dependent.

The string is assumed to be in a character encoding, such as an ISO 8859 or other EUC encoding, or UTF-8, in which all bytes in the range 0x00 through 0x7F are ASCII characters and non-ASCII characters are constructed from one or more bytes in the range 0x80 through 0xFF.

Parameters

str	The string to be lower-cased.

Returns: ptr to the string

◆ ascii_strup_inplace()

WS_DLL_PUBLIC char * ascii_strup_inplace ( char * str )

In-place converstion of lower-case ASCII letters to upper-case.

Convert all lower-case ASCII letters to their ASCII upper-case equivalents, in place, with a simple non-locale-dependent ASCII mapping (a-z -> A-Z). All other characters are left unchanged, as the mapping to lower case may be locale-dependent.

The string is assumed to be in a character encoding, such as an ISO 8859 or other EUC encoding, or UTF-8, in which all bytes in the range 0x00 through 0x7F are ASCII characters and non-ASCII characters are constructed from one or more bytes in the range 0x80 through 0xFF.

Parameters

str	The string to be upper-cased.

Returns: ptr to the string

◆ EBCDIC_to_ASCII()

WS_DLL_PUBLIC void EBCDIC_to_ASCII	(	uint8_t *	buf,
		unsigned	bytes
	)

Convert a buffer of EBCDIC-encoded bytes to ASCII in-place.

This function modifies the given buffer by converting each byte from EBCDIC to its corresponding ASCII representation. The conversion is done in-place.

Parameters

buf	Pointer to the buffer containing EBCDIC-encoded bytes.
bytes	Number of bytes in the buffer to convert.

◆ EBCDIC_to_ASCII1()

WS_DLL_PUBLIC uint8_t EBCDIC_to_ASCII1 ( uint8_t c )

Convert a single EBCDIC-encoded byte to its ASCII equivalent.

Parameters

c	EBCDIC-encoded byte.

Returns: The corresponding ASCII-encoded byte.

◆ format_char()

WS_DLL_PUBLIC char * format_char	(	wmem_allocator_t *	allocator,
		char	c
	)

Given a wmem scope and an 8-bit character generate a valid UTF-8 string from it, allocated in the specified wmem scope, that:

shows printable Unicode characters as themselves;

shows non-printable ASCII characters as C-style escapes (hex if not one of the standard ones such as LF -> '
');

and return a pointer to it.

Parameters

allocator	The wmem scope
c	A character to format

Returns: A pointer to the formatted string

◆ format_size_wmem()

WS_DLL_PUBLIC char * format_size_wmem	(	wmem_allocator_t *	allocator,
		int64_t	size,
		format_size_units_e	unit,
		uint16_t	flags
	)

Given a size, return its value in a human-readable format

Prefixes up to "T/Ti" (tera, tebi) are currently supported.

Parameters

allocator	memory allocator to use for the returned string.
size	The size value
unit	The base unit to use (e.g., bytes, bits), specified by `format_size_units_e`.
flags	Flags to control the output (unit of measurement, SI vs IEC, etc). Unit and prefix flags may be ORed together.

Returns: A newly-allocated string representing the value.

◆ format_text()

WS_DLL_PUBLIC char * format_text	(	wmem_allocator_t *	allocator,
		const char *	string,
		size_t	len
	)

Given a wmem scope, a not-necessarily-null-terminated string, expected to be in UTF-8 but possibly containing invalid sequences (as it may have come from packet data), and the length of the string, generate a valid UTF-8 string from it, allocated in the specified wmem scope, that:

shows printable Unicode characters as themselves;

shows non-printable ASCII characters as C-style escapes (octal if not one of the standard ones such as LF -> '
');

shows non-printable Unicode-but-not-ASCII characters as their universal character names;

Replaces illegal UTF-8 sequences with U+FFFD (replacement character) ;

and return a pointer to it.

Parameters

allocator	The wmem scope
string	A pointer to the input string
len	The length of the input string

Returns: A pointer to the formatted string

See also: tvb_format_text()

◆ format_text_chr()

WS_DLL_PUBLIC char * format_text_chr	(	wmem_allocator_t *	allocator,
		const char *	string,
		size_t	len,
		char	chr
	)

Given a string, generate a string from it that shows non-printable characters as the chr parameter passed, except a whitespace character (space, tab, carriage return, new line, vertical tab, or formfeed) which will be replaced by a space, and return a pointer to it.

This does not treat the input string as UTF-8.

This is useful for displaying binary data that frequently but not always contains text; otherwise the number of C escape codes makes it unreadable.

Parameters

allocator	The wmem scope
string	A pointer to the input string
len	The length of the input string
chr	The character to use to replace non-printable characters

Returns: A pointer to the formatted string

◆ format_text_string()

WS_DLL_PUBLIC char * format_text_string	(	wmem_allocator_t *	allocator,
		const char *	string
	)

Same as format_text() but accepts a nul-terminated string.

Parameters

allocator	The wmem scope
string	A pointer to the input string

Returns: A pointer to the formatted string

See also: tvb_format_text()

Given a wmem scope and a null-terminated string, expected to be in UTF-8 but possibly containing invalid sequences (as it may have come from packet data), and the length of the string, generate a valid UTF-8 string from it, allocated in the specified wmem scope, that:

shows printable Unicode characters as themselves;

shows non-printable ASCII characters as C-style escapes (octal if not one of the standard ones such as LF -> '
');

shows non-printable Unicode-but-not-ASCII characters as their universal character names;

shows illegal UTF-8 sequences as a sequence of bytes represented as C-style hex escapes;

and return a pointer to it.

◆ format_text_wsp()

WS_DLL_PUBLIC char * format_text_wsp	(	wmem_allocator_t *	allocator,
		const char *	line,
		size_t	len
	)

Same as format_text() but replaces any whitespace characters (space, tab, carriage return, new line, vertical tab, or formfeed) with a space.

Parameters

allocator	The wmem scope
line	A pointer to the input string
len	The length of the input string

Returns: A pointer to the formatted string

◆ format_units()

WS_DLL_PUBLIC char * format_units	(	wmem_allocator_t *	allocator,
		double	size,
		format_size_units_e	unit,
		uint16_t	flags,
		int	precision
	)

Given a floating point value, return it in a human-readable format

Prefixes up to "E/Ei" (exa, exbi) and down to "a" (atto; negative prefixes are SI-only) are currently supported. Values outside that range will use scientific notation.

Parameters

allocator	memory allocator to use for the returned string.
size	The size value
unit	The base unit to use (e.g., bytes, bits), specified by `format_size_units_e`.
flags	Flags to control the output (unit of measurement, SI vs IEC, etc). Unit and prefix flags may be ORed together.
precision	Maximum number of digits to appear after the decimal point. Trailing zeros are removed, as is the decimal point if not digits follow it.

Returns: A newly-allocated string representing the value.

◆ hex_dump_buffer()

WS_DLL_PUBLIC bool hex_dump_buffer	(	bool()(void , const char *)	print_line,
		void *	fp,
		const unsigned char *	cp,
		unsigned	length,
		hex_dump_enc	encoding,
		unsigned	ascii_option
	)

Generate a formatted hex dump of a byte buffer.

This function produces a hex dump of the given buffer cp, formatting it according to the specified encoding and ASCII display options. Each formatted line is passed to the user-supplied print_line callback.

Parameters

print_line	Callback function to receive each formatted line of output. It should return true to continue dumping, or false to abort early.
fp	User-defined context pointer passed to `print_line` (e.g., a file handle or buffer).
cp	Pointer to the byte buffer to be dumped.
length	Number of bytes in the buffer.
encoding	Encoding style for the hex dump (e.g., canonical, compact).
ascii_option	ASCII display mode (e.g., include, exclude, delimit), masked via `HEXDUMP_ASCII_OPTION()`.

Returns: true if the entire buffer was dumped successfully; false if aborted early by print_line.

Note: This function does not write directly to stdout or a file; output is routed through print_line.

◆ isdigit_string()

WS_DLL_PUBLIC bool isdigit_string ( const char * str )

Check if an entire string consists of digits.

Parameters

str	The string to be checked

Returns: true if the entire string is digits, otherwise false

◆ isprint_string()

WS_DLL_PUBLIC bool isprint_string ( const char * str )

Check if an entire string consists of printable characters.

Parameters

str	The string to be checked

Returns: true if the entire string is printable, otherwise false

◆ isprint_utf8_string()

WS_DLL_PUBLIC bool isprint_utf8_string	(	const char *	str,
		const unsigned	length
	)

Given a not-necessarily-null-terminated string, expected to be in UTF-8 but possibly containing invalid sequences (as it may have come from packet data), and the length of the string, deterimine if the string is valid UTF-8 consisting entirely of printable characters.

This means that it:

does not contain an illegal UTF-8 sequence (including overlong encodings, the sequences reserved for UTF-16 surrogate halves, and the values for code points above U+10FFFF that are no longer in Unicode)

does not contain a non-printable Unicode character such as control characters (including internal NULL bytes)

does not end in a partial sequence that could begin a valid character;

does not start with a partial sequence that could end a valid character;

and thus guarantees that the result of format_text() would be the same as that of wmem_strndup() with the same parameters.

Parameters

str	The string to be checked
length	The number of bytes to validate

Returns: true if the entire string is valid and printable UTF-8, otherwise false

◆ printable_char_or_period()

WS_DLL_PUBLIC char printable_char_or_period ( char c )

Return a printable character or '.' if non-printable.

Converts the input character to itself if it is printable, or returns '.' if it is a control or non-printable character.

Parameters

c	The character to evaluate.

Returns: A printable character or '.'.

◆ wmem_ascii_strdown()

WS_DLL_PUBLIC char * wmem_ascii_strdown	(	wmem_allocator_t *	allocator,
		const char *	str,
		ssize_t	len
	)

Converts all upper case ASCII letters to lower case ASCII letters.

Based on g_ascii_strdown

Parameters

allocator	An enumeration of the different types of available allocators.
str	a string.
len	length of str in bytes, or -1 if str is nul-terminated.

Returns: a newly-allocated string, with all the upper case characters in str converted to lower case, with semantics that exactly match g_ascii_tolower(). (Note that this is unlike the old g_strdown(), which modified the string in place.)

◆ wmem_strconcat()

WS_DLL_PUBLIC char * wmem_strconcat	(	wmem_allocator_t *	allocator,
		const char *	first,
			...
	)

Concatenate multiple strings into a single newly allocated string.

Appends all non-NULL strings passed as variadic arguments into a single buffer. No separator is added between strings.

Parameters

allocator	Memory allocator to use for the returned string.
first	The first string to concatenate.
...	Additional strings to concatenate, ending with NULL.

Returns: A newly allocated null-terminated string containing the concatenated result.

Note: The returned string is allocated using allocator and should be freed appropriately.

◆ wmem_strjoin()

WS_DLL_PUBLIC char * wmem_strjoin	(	wmem_allocator_t *	allocator,
		const char *	separator,
		const char *	first,
			...
	)

Join multiple strings using a separator into a single newly allocated string.

Inserts the specified separator between each non-NULL string in the variadic list.

Parameters

allocator	Memory allocator to use for the returned string.
separator	Separator string to insert between each element.
first	The first string to join.
...	Additional strings to join, ending with NULL.

Returns: A newly allocated null-terminated string containing the joined result.

Note: The returned string is allocated using allocator and should be freed appropriately.

◆ wmem_strjoinv()

WS_DLL_PUBLIC char * wmem_strjoinv	(	wmem_allocator_t *	allocator,
		const char *	separator,
		char **	str_array
	)

Joins a number of strings together to form one long string, with the optional separator inserted between each of them.

As g_strjoinv, with the returned string wmem allocated.

Parameters

allocator	The wmem scope to use to allocate the returned string
separator	A string to insert between each of the strings, or NULL.
str_array	A NULL-terminated array of strings to join

Note: If str_array has no items, the return value is an empty string. str_array should not be NULL (NULL is returned with an warning.) NULL as a separator is equivalent to the empty string.

◆ wmem_strsplit()

WS_DLL_PUBLIC char ** wmem_strsplit	(	wmem_allocator_t *	allocator,
		const char *	src,
		const char *	delimiter,
		int	max_tokens
	)

Splits a string into a maximum of max_tokens pieces, using the given delimiter.

If max_tokens is reached, the remainder of string is appended to the last token. Successive tokens are not folded and will instead result in an empty string as element.

If src or delimiter are NULL, or if delimiter is empty, this will return NULL.

Do not use with a NULL allocator, use g_strsplit instead.

◆ ws_ascii_strcasestr()

WS_DLL_PUBLIC const char * ws_ascii_strcasestr	(	const char *	haystack,
		const char *	needle
	)

Finds the first occurrence of string 'needle' in string 'haystack'. The matching is done ignoring the case of ASCII characters in a non-locale-dependent way.

The string is assumed to be in a character encoding, such as an ISO 8859 or other EUC encoding, or UTF-8, in which all bytes in the range 0x00 through 0x7F are ASCII characters and non-ASCII characters are constructed from one or more bytes in the range 0x80 through 0xFF.

Parameters

haystack	The string possibly containing the substring
needle	The substring to be searched

Returns: A pointer into 'haystack' where 'needle' is first found. Otherwise it returns NULL.

◆ ws_escape_csv()

WS_DLL_PUBLIC char * ws_escape_csv	(	wmem_allocator_t *	alloc,
		const char *	string,
		bool	add_quotes,
		char	quote_char,
		bool	double_quote,
		bool	escape_whitespace
	)

Escape as in a number of CSV dialects.

Parameters

alloc	The wmem scope to use to allocate the returned string
string	The input string to escape
add_quotes	Whether to surround the string with quote_char
quote_char	The quote character, always escaped in some way.
double_quote	Whether to escape the quote character by doubling it
escape_whitespace	Whether to escape whitespace with a backslash

Returns: The escaped string

Note: If double_quote is false, then quote_or_delim is escaped with a backslash ('\'). The quote character can be '\0', in which case it is ignored. If any character is being escaped with a backslash (i.e., quote_char is not '\0' and double_quote is false, or escape_whitespace is true), then backslash is also escaped. If add_quotes is false, then quote_char can either be a quote character (if the string will be quoted later after further manipulation) or the delimiter (to escape it, since the string is not being quoted.).

◆ ws_escape_null()

WS_DLL_PUBLIC char * ws_escape_null	(	wmem_allocator_t *	alloc,
		const char *	string,
		size_t	len,
		bool	add_quotes
	)

Escape null bytes in a string for safe display or logging.

Scans the input buffer and replaces each null byte (\0) with the literal string "\\0", making the result printable and distinguishable in output. Optionally wraps the result in double quotes.

Parameters

alloc	Memory allocator to use for the returned string.
string	Pointer to the input buffer.
len	Number of bytes to process from `string`.
add_quotes	If true, the result will be wrapped in double quotes.

Returns: A newly allocated null-terminated string with escaped nulls, or NULL on failure.

Note: The returned string is allocated using alloc and must be freed appropriately.; This function is binary-safe and does not rely on null termination in the input.

◆ ws_escape_string()

WS_DLL_PUBLIC char * ws_escape_string	(	wmem_allocator_t *	alloc,
		const char *	string,
		bool	add_quotes
	)

Escape a null-terminated string for safe display or output.

Converts control characters, quotes, and other non-printable bytes into escaped sequences (e.g., \n, \\, \") suitable for logging or serialization. Optionally wraps the result in double quotes.

Parameters

alloc	Memory allocator to use for the returned string.
string	Null-terminated input string to escape.
add_quotes	If true, the result will be wrapped in double quotes.

Returns: A newly allocated escaped string, or NULL on failure.

◆ ws_escape_string_len()

WS_DLL_PUBLIC char * ws_escape_string_len	(	wmem_allocator_t *	alloc,
		const char *	string,
		ssize_t	len,
		bool	add_quotes
	)

Escape a string of specified length for safe display or output.

Similar to ws_escape_string(), but allows escaping of strings that are not null-terminated or contain embedded nulls. Useful for binary-safe formatting.

Parameters

alloc	Memory allocator to use for the returned string.
string	Pointer to the input buffer to escape.
len	Number of bytes to process from `string`.
add_quotes	If true, the result will be wrapped in double quotes.

Returns: A newly allocated escaped string, or NULL on failure.

◆ ws_memrchr()

WS_DLL_PUBLIC const uint8_t * ws_memrchr	(	const void *	haystack,
		int	ch,
		size_t	n
	)

Like the memchr() function, except it scans backwards from the end.

Parameters

haystack	Pointer to the bytes of memory to search
ch	The character to search
n	The length of bytes to search from the end

Returns: A pointer to the last occurrence of "ch" in "haystack". If "ch" isn't found or "n" is 0, returns NULL.

◆ ws_strdup_underline()

WS_DLL_PUBLIC char * ws_strdup_underline	(	wmem_allocator_t *	allocator,
		long	offset,
		size_t	len
	)

Create a string of underscores for visual alignment or highlighting.

Allocates a string consisting of len underscores (_), optionally offset by offset spaces. Useful for underlining or aligning output in diagnostics.

Parameters

allocator	Memory allocator to use for the returned string.
offset	Number of leading spaces before the underscores.
len	Number of underscores to generate.

Returns: A newly allocated null-terminated string, or NULL on failure.

Note: The returned string is allocated using allocator and must be freed appropriately.

◆ ws_strerrorname_r()

WS_DLL_PUBLIC WS_RETNONNULL const char * ws_strerrorname_r	(	int	errnum,
		char *	buf,
		size_t	buf_size
	)

Return the symbolic name of an error code.

Converts a numeric error code (typically from errno) to its symbolic name (e.g., "EINVAL", "ENOMEM"), storing the result in buf.

Parameters

errnum	The error code to translate.
buf	Buffer to store the symbolic name.
buf_size	Size of the buffer in bytes.

Returns: Pointer to buf, containing the symbolic name or a fallback string.

Note: The returned pointer is always non-NULL.

◆ ws_utf8_truncate()

WS_DLL_PUBLIC char * ws_utf8_truncate	(	char *	string,
		size_t	len
	)

Truncate a UTF-8 string in place so that it is no larger than len bytes, ensuring that the string is null terminated and ends with a complete character instead of a partial sequence (e.g., possibly truncating up to 3 additional bytes if the terminal character is 4 bytes long).

The buffer holding the string must be large enough (at least len + 1 including the null terminator), and the first len bytes of the buffer must be a valid UTF-8 string, except for possibly ending in a partial sequence or not being null terminated. This is a convenience function that for speed does not check either of those conditions.

A common use case is when a valid UTF-8 string has been copied into a buffer of length len+1 via snprintf, strlcpy, or strlcat and truncated, to ensure that the final UTF-8 character is not a partial sequence.

Parameters

string	A pointer to the input string
len	The maximum length to truncate to

Returns: ptr to the string

◆ ws_xton()

WS_DLL_PUBLIC int ws_xton ( char ch )

Convert a hexadecimal character to its numeric value.

Converts a single ASCII character representing a hexadecimal digit ('0'–'9', 'a'–'f', 'A'–'F') into its corresponding integer value (0–15).

Parameters

ch	The character to convert.

Returns: The numeric value of the hex digit, or -1 if ch is not a valid hex character.

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ format_size

◆ FORMAT_SIZE_PREFIX_IEC

◆ FORMAT_SIZE_PREFIX_SI

◆ HEXDUMP_ASCII_DELIMIT

◆ HEXDUMP_ASCII_EXCLUDE

◆ HEXDUMP_ASCII_INCLUDE

◆ HEXDUMP_ASCII_OPTION

◆ plurality

◆ string_or_null

◆ true_or_false

Enumeration Type Documentation

◆ format_size_units_e

◆ hex_dump_enc

Function Documentation

◆ ascii_strdown_inplace()

◆ ascii_strup_inplace()

◆ EBCDIC_to_ASCII()

◆ EBCDIC_to_ASCII1()

◆ format_char()

◆ format_size_wmem()

◆ format_text()

◆ format_text_chr()

◆ format_text_string()

◆ format_text_wsp()

◆ format_units()

◆ hex_dump_buffer()

◆ isdigit_string()

◆ isprint_string()

◆ isprint_utf8_string()

◆ printable_char_or_period()

◆ wmem_ascii_strdown()

◆ wmem_strconcat()

◆ wmem_strjoin()

◆ wmem_strjoinv()

◆ wmem_strsplit()

◆ ws_ascii_strcasestr()

◆ ws_escape_csv()

◆ ws_escape_null()

◆ ws_escape_string()

◆ ws_escape_string_len()

◆ ws_memrchr()

◆ ws_strdup_underline()

◆ ws_strerrorname_r()

◆ ws_utf8_truncate()

◆ ws_xton()