#include <stdint.h>
#include "ws_symbol_export.h"
#include <wsutil/nstime.h>

Classes
struct	_value_string
	Mapping between a 32-bit integer value and its string representation. More...

struct	_val64_string
	Mapping between a 64-bit integer value and its string representation. More...

struct	_value_string_ext
	Extended metadata for a value_string array. More...

struct	_val64_string_ext
	Extended metadata for a 64-bit value-string mapping array. More...

struct	_string_string

struct	_range_string

struct	_time_value_string

struct	_bytes_string

Macros
#define	VALUE_STRING_ENUM( array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY)

#define	VALUE_STRING_ARRAY( array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY, static)

#define	VALUE_STRING_ARRAY_GLOBAL_DEF( array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY)

#define	VALUE_STRING_ARRAY_GLOBAL_DCL( array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)

#define	VALUE_STRING_ENUM2( array_name) _VS_ENUM_XXX( array_name, _VS_ENUM_ENTRY2)

#define	VALUE_STRING_ARRAY2( array_name) _VS_ARRAY_SC_XXX(array_name, _VS_ARRAY_ENTRY2, static)

#define	VALUE_STRING_ARRAY2_GLOBAL_DEF(array_name) _VS_ARRAY_XXX(array_name, _VS_ARRAY_ENTRY2)

#define	VALUE_STRING_ARRAY2_GLOBAL_DCL(array_name) _VS_ARRAY_SC_TYPE_NAME(array_name, extern)

#define	_VS_ENUM_XXX(array_name, macro)

#define	_VS_ARRAY_SC_XXX(array_name, macro, sc)

#define	_VS_ARRAY_XXX(array_name, macro)

#define	_VS_ARRAY_SC_TYPE_NAME(array_name, sc) sc const value_string array_name[]

#define	_VS_ARRAY_TYPE_NAME(array_name) const value_string array_name[]

#define	_VS_ENUM_ENTRY(name, value, string) name = value,

#define	_VS_ARRAY_ENTRY(name, value, string) { value, string },

#define	_VS_ENUM_ENTRY2(name, value) name = value,

#define	_VS_ARRAY_ENTRY2(name, value) { value, #name },

#define	VALUE_STRING_EXT_VS_P(x) (x)->_vs_p

#define	VALUE_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries

#define	VALUE_STRING_EXT_VS_NAME(x) (x)->_vs_name

#define	VALUE_STRING_EXT_INIT(x) { _try_val_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }

#define	VAL64_STRING_EXT_VS_P(x) (x)->_vs_p

#define	VAL64_STRING_EXT_VS_NUM_ENTRIES(x) (x)->_vs_num_entries

#define	VAL64_STRING_EXT_VS_NAME(x) (x)->_vs_name

#define	VAL64_STRING_EXT_INIT(x) { _try_val64_to_str_ext_init, 0, G_N_ELEMENTS(x)-1, x, #x, NULL }

Typedefs
typedef struct _value_string	value_string
	Mapping between a 32-bit integer value and its string representation.

typedef struct _val64_string	val64_string
	Mapping between a 64-bit integer value and its string representation.

typedef struct _value_string_ext	value_string_ext

typedef const value_string (	_value_string_match2_t) (const uint32_t, value_string_ext *)

typedef struct _val64_string_ext	val64_string_ext

typedef const val64_string (	_val64_string_match2_t) (const uint64_t, val64_string_ext *)

typedef struct _string_string	string_string

typedef struct _range_string	range_string

typedef struct _time_value_string	time_value_string

typedef struct _bytes_string	bytes_string

Functions
WS_DLL_PUBLIC char *	val_to_str (wmem_allocator_t scope, const uint32_t val, const value_string vs, const char *fmt)
	Convert a numeric value to a string using a value-string mapping.

WS_DLL_PUBLIC const char *	val_to_str_const (const uint32_t val, const value_string vs, const char unknown_str)
	Convert a numeric value to a constant string using a value-string mapping.

WS_DLL_PUBLIC const char *	try_val_to_str (const uint32_t val, const value_string *vs)
	Attempt to convert a numeric value to a string using a value-string mapping.

WS_DLL_PUBLIC const char *	try_val_to_str_idx (const uint32_t val, const value_string vs, int idx)
	Attempt to convert a numeric value to a string and retrieve its index.

WS_DLL_PUBLIC const char *	val64_to_str_wmem (wmem_allocator_t scope, const uint64_t val, const val64_string vs, const char *fmt)
	Convert a 64-bit value to a string using a value-string mapping.

WS_DLL_PUBLIC const char *	val64_to_str_const (const uint64_t val, const val64_string vs, const char unknown_str)
	Convert a 64-bit value to a constant string using a value-string mapping.

WS_DLL_PUBLIC const char *	try_val64_to_str (const uint64_t val, const val64_string *vs)
	Attempt to convert a 64-bit value to a string using a value-string mapping.

WS_DLL_PUBLIC const char *	try_val64_to_str_idx (const uint64_t val, const val64_string vs, int idx)
	Attempt to convert a 64-bit value to a string and retrieve its index.

WS_DLL_PUBLIC uint32_t	str_to_val (const char val, const value_string vs, const uint32_t err_val)
	Convert a string to its corresponding numeric value using a value-string mapping.

WS_DLL_PUBLIC int	str_to_val_idx (const char val, const value_string vs)
	Retrieve the index of a string in a value-string mapping array.

WS_DLL_PUBLIC const value_string *	_try_val_to_str_ext_init (const uint32_t val, value_string_ext *vse)
	Attempt to initialize and retrieve a value-string entry from an extended mapping.

WS_DLL_PUBLIC value_string_ext *	value_string_ext_new (wmem_allocator_t scope, const value_string vs, unsigned vs_tot_num_entries, const char *vs_name)
	Create a new extended value-string mapping structure.

WS_DLL_PUBLIC void	value_string_ext_free (value_string_ext *vse)
	Free an extended value-string mapping structure.

WS_DLL_PUBLIC char *	val_to_str_ext (wmem_allocator_t scope, const uint32_t val, value_string_ext vse, const char *fmt)
	Convert a numeric value to a string using an extended value-string mapping.

WS_DLL_PUBLIC const char *	val_to_str_ext_const (const uint32_t val, value_string_ext vs, const char unknown_str)
	Convert a numeric value to a constant string using an extended value-string mapping.

WS_DLL_PUBLIC const char *	try_val_to_str_ext (const uint32_t val, value_string_ext *vse)
	Attempt to convert a numeric value to a string using an extended value-string mapping.

WS_DLL_PUBLIC const char *	try_val_to_str_idx_ext (const uint32_t val, value_string_ext vse, int idx)
	Attempt to convert a numeric value to a string and retrieve its index from an extended mapping.

WS_DLL_PUBLIC int	value_str_value_compare (const void a, const void b)
	Compare two value_string entries by their numeric value.

WS_DLL_PUBLIC const val64_string *	_try_val64_to_str_ext_init (const uint64_t val, val64_string_ext *vse)
	Attempt to initialize and retrieve a 64-bit value-string entry from an extended mapping.

WS_DLL_PUBLIC val64_string_ext *	val64_string_ext_new (wmem_allocator_t scope, const val64_string vs, unsigned vs_tot_num_entries, const char *vs_name)
	Create a new extended value string structure.

WS_DLL_PUBLIC void	val64_string_ext_free (val64_string_ext *vse)

WS_DLL_PUBLIC char *	val64_to_str_ext_wmem (wmem_allocator_t scope, const uint64_t val, val64_string_ext vse, const char *fmt)

WS_DLL_PUBLIC const char *	val64_to_str_ext_const (const uint64_t val, val64_string_ext vs, const char unknown_str)

WS_DLL_PUBLIC const char *	try_val64_to_str_ext (const uint64_t val, val64_string_ext *vse)

WS_DLL_PUBLIC const char *	try_val64_to_str_idx_ext (const uint64_t val, val64_string_ext vse, int idx)
	Convert a 64-bit value to its corresponding string index and pointer.

WS_DLL_PUBLIC const char *	str_to_str_wmem (wmem_allocator_t scope, const char val, const string_string vs, const char fmt)
	Converts a string value to a formatted string using a value string table.

WS_DLL_PUBLIC const char *	try_str_to_str (const char val, const string_string vs)
	Converts a string to another string based on a value-string mapping.

WS_DLL_PUBLIC const char *	try_str_to_str_idx (const char val, const string_string vs, int *idx)
	Converts a string to an index in a string-string mapping table.

WS_DLL_PUBLIC const char *	rval_to_str_wmem (wmem_allocator_t scope, const uint32_t val, const range_string rs, const char *fmt)

WS_DLL_PUBLIC const char *	rval_to_str_const (const uint32_t val, const range_string rs, const char unknown_str)

WS_DLL_PUBLIC const char *	try_rval_to_str (const uint32_t val, const range_string *rs)
	Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.

WS_DLL_PUBLIC const char *	try_rval_to_str_idx (const uint32_t val, const range_string rs, int idx)
	Converts a 32-bit unsigned integer value to its corresponding string representation based on a range_string array.

WS_DLL_PUBLIC const char *	try_rval64_to_str (const uint64_t val, const range_string *rs)
	Convert a 64-bit unsigned integer value to a string based on a range of strings.

WS_DLL_PUBLIC const char *	try_rval64_to_str_idx (const uint64_t val, const range_string rs, int idx)
	Converts a 64-bit unsigned integer value to its corresponding string representation based on a range of values.

WS_DLL_PUBLIC const char *	try_time_val_to_str (const nstime_t val, const time_value_string vs)
	Tries to match a time value against an array of time_value_string entries.

WS_DLL_PUBLIC const char *	bytesval_to_str_wmem (wmem_allocator_t scope, const uint8_t val, const size_t val_len, const bytes_string bs, const char fmt)
	Converts a byte value to a string using a format string.

WS_DLL_PUBLIC const char *	try_bytesval_to_str (const uint8_t val, const size_t val_len, const bytes_string bs)

WS_DLL_PUBLIC const char *	bytesprefix_to_str (wmem_allocator_t scope, const uint8_t haystack, const size_t haystack_len, const bytes_string bs, const char fmt)
	Convert a byte prefix to a string using a value_string array.

WS_DLL_PUBLIC const char *	try_bytesprefix_to_str (const uint8_t haystack, const size_t haystack_len, const bytes_string bs)
	Tries to find a string representation for a byte prefix in a bytes_string array.

WS_DLL_PUBLIC void	register_external_value_string (const char name, const value_string vs)
	Registers an external value string with a given name.

WS_DLL_PUBLIC value_string *	get_external_value_string (const char *name)
	Retrieves an external value string by name.

WS_DLL_PUBLIC void	register_external_value_string_ext (const char name, const value_string_ext vse)
	Registers an external value string extension.

WS_DLL_PUBLIC value_string_ext *	get_external_value_string_ext (const char *name)
	Retrieves an external value string extension by name.

WS_DLL_PUBLIC void	value_string_externals_init (void)
	Initializes external value string and extension registries.

WS_DLL_PUBLIC void	value_string_externals_cleanup (void)
	Cleans up external value string resources.

WS_DLL_PUBLIC bool	value_string_ext_validate (const value_string_ext *vse)
	Validates a value_string_ext structure.

WS_DLL_PUBLIC const char *	value_string_ext_match_type_str (const value_string_ext *vse)
	Returns a string representation of the match type for a value_string_ext.

WS_DLL_PUBLIC bool	val64_string_ext_validate (const val64_string_ext *vse)
	Validates a value_string_ext structure.

WS_DLL_PUBLIC const char *	val64_string_ext_match_type_str (const val64_string_ext *vse)
	Returns a string representation of the match type for a 64-bit value string extension.

Detailed Description

Definitions for value_string structures and routines

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

Macro Definition Documentation

◆ _VS_ARRAY_SC_XXX

#define _VS_ARRAY_SC_XXX	(	array_name,
		macro,
		sc
	)

Value:

    _VS_ARRAY_SC_TYPE_NAME(array_name, sc) = { \
    array_name##_VALUE_STRING_LIST(macro) \
    { 0, NULL } \
}

◆ _VS_ARRAY_XXX

#define _VS_ARRAY_XXX	(	array_name,
		macro
	)

Value:

    _VS_ARRAY_TYPE_NAME(array_name) = { \
    array_name##_VALUE_STRING_LIST(macro) \
    { 0, NULL } \
}

◆ _VS_ENUM_XXX

#define _VS_ENUM_XXX	(	array_name,
		macro
	)

Value:

enum { \
    array_name##_VALUE_STRING_LIST(macro) \
    _##array_name##_ENUM_DUMMY = 0 \
}

Typedef Documentation

◆ val64_string

typedef struct _val64_string val64_string

Mapping between a 64-bit integer value and its string representation.

Used to associate a uint64_t value with a human-readable string. This is useful for converting large numeric constants to descriptive labels in protocol dissectors, debug output, or UI elements.

◆ value_string

typedef struct _value_string value_string

Mapping between a 32-bit integer value and its string representation.

Used to associate a uint32_t value with a human-readable string. This is commonly employed in protocol dissectors and diagnostic tools to convert numeric constants into descriptive labels.

Function Documentation

◆ _try_val64_to_str_ext_init()

WS_DLL_PUBLIC const val64_string * _try_val64_to_str_ext_init	(	const uint64_t	val,
		val64_string_ext *	vse
	)

Attempt to initialize and retrieve a 64-bit value-string entry from an extended mapping.

Searches the extended val64_string_ext structure vse for an entry matching val. If found, returns a pointer to the corresponding val64_string entry. If not found, returns NULL. This function may also perform internal initialization of the val64_string_ext structure if required.

This is useful for advanced lookup scenarios where metadata and scoped memory management are involved, and where direct access to the matched entry is needed for further processing.

Parameters

val	64-bit value to look up.
vse	Pointer to an extended 64-bit value-string mapping structure.

Returns: Pointer to the matching val64_string entry, or NULL if not found.

◆ _try_val_to_str_ext_init()

WS_DLL_PUBLIC const value_string * _try_val_to_str_ext_init	(	const uint32_t	val,
		value_string_ext *	vse
	)

Attempt to initialize and retrieve a value-string entry from an extended mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns a pointer to the corresponding value_string entry. If not found, returns NULL. This function may also perform internal initialization of the value_string_ext structure if needed.

Parameters

val	Numeric value to look up.
vse	Pointer to an extended value-string mapping structure.

Returns: Pointer to the matching value_string entry, or NULL if not found.

◆ bytesprefix_to_str()

WS_DLL_PUBLIC const char * bytesprefix_to_str	(	wmem_allocator_t *	scope,
		const uint8_t *	haystack,
		const size_t	haystack_len,
		const bytes_string *	bs,
		const char *	fmt
	)

Convert a byte prefix to a string using a value_string array.

This function attempts to find a prefix match of any prefix from the bytes_string array against the haystack and returns the corresponding string if found. If no match is found, it uses a format string to create a new string.

Parameters

scope	Memory allocator scope for the returned string.
haystack	The byte array to search within.
haystack_len	Length of the haystack array.
bs	Pointer to the bytes_string array containing prefix-value pairs.
fmt	Format string to use if no prefix match is found.

Returns: A newly allocated string representing the matched prefix or formatted value, or NULL on error.

◆ bytesval_to_str_wmem()

WS_DLL_PUBLIC const char * bytesval_to_str_wmem	(	wmem_allocator_t *	scope,
		const uint8_t *	val,
		const size_t	val_len,
		const bytes_string *	bs,
		const char *	fmt
	)

Converts a byte value to a string using a format string.

This function attempts to convert a byte value to a string based on a provided format string. If the conversion is successful, it returns the converted string; otherwise, it returns an error message.

Parameters

scope	The memory allocator scope for the returned string.
val	The byte value to be converted.
val_len	The length of the byte value.
bs	A pointer to a bytes_string structure containing possible values and their corresponding strings.
fmt	The format string used for conversion. If NULL, an error message is returned.

Returns: A pointer to the converted string or an error message if the conversion fails.

◆ get_external_value_string()

WS_DLL_PUBLIC value_string * get_external_value_string ( const char * name )

Retrieves an external value string by name.

Parameters

name	The name of the value string to retrieve.

Returns: A pointer to the value_string if found, otherwise NULL.

◆ get_external_value_string_ext()

WS_DLL_PUBLIC value_string_ext * get_external_value_string_ext ( const char * name )

Retrieves an external value string extension by name.

Parameters

name	The name of the external value string extension to retrieve.

Returns: A pointer to the external value string extension, or NULL if not found.

◆ register_external_value_string()

WS_DLL_PUBLIC void register_external_value_string	(	const char *	name,
		const value_string *	vs
	)

Registers an external value string with a given name.

Parameters

name	The name under which the value string is registered.
vs	The value string to be registered.

◆ register_external_value_string_ext()

WS_DLL_PUBLIC void register_external_value_string_ext	(	const char *	name,
		const value_string_ext *	vse
	)

Registers an external value string extension.

Parameters

name	The name of the value string extension to register.
vse	The value string extension to register.

◆ str_to_str_wmem()

WS_DLL_PUBLIC const char * str_to_str_wmem	(	wmem_allocator_t *	scope,
		const char *	val,
		const string_string *	vs,
		const char *	fmt
	)

Converts a string value to a formatted string using a value string table.

Parameters

scope	The memory allocator scope for the returned string.
val	The input string value to convert.
vs	The value string table containing mappings from values to strings.
fmt	The format string to use if no exact match is found in the value string table.

Returns: The converted string, or a default error message if both the value string table and format are NULL.

◆ str_to_val()

WS_DLL_PUBLIC uint32_t str_to_val	(	const char *	val,
		const value_string *	vs,
		const uint32_t	err_val
	)

Convert a string to its corresponding numeric value using a value-string mapping.

Searches the provided value_string array vs for an entry whose string matches val. If found, returns the associated numeric value. If not found, returns err_val.

This function is useful for parsing user input or protocol fields that use string representations of enumerated values.

Parameters

val	String to convert.
vs	Array of value-string mappings.
err_val	Value to return if `val` is not found in `vs`.

Returns: The numeric value corresponding to val, or err_val if not found.

◆ str_to_val_idx()

WS_DLL_PUBLIC int str_to_val_idx	(	const char *	val,
		const value_string *	vs
	)

Retrieve the index of a string in a value-string mapping array.

Searches the provided value_string array vs for an entry whose string matches val. If found, returns the index of the matching entry. If not found, returns -1.

This function is useful when the caller needs the position of a matched string for further processing or lookup.

Parameters

val	String to search for.
vs	Array of value-string mappings.

Returns: Index of the matching entry, or -1 if not found.

◆ try_bytesprefix_to_str()

WS_DLL_PUBLIC const char * try_bytesprefix_to_str	(	const uint8_t *	haystack,
		const size_t	haystack_len,
		const bytes_string *	bs
	)

Tries to find a string representation for a byte prefix in a bytes_string array.

Parameters

haystack	The buffer containing the byte sequence to search.
haystack_len	The length of the byte sequence.
bs	The bytes_string array to search within.

Returns: const char* A pointer to the corresponding string if found, NULL otherwise.

◆ try_rval64_to_str()

WS_DLL_PUBLIC const char * try_rval64_to_str	(	const uint64_t	val,
		const range_string *	rs
	)

Convert a 64-bit unsigned integer value to a string based on a range of strings.

Parameters

val	The 64-bit unsigned integer value to convert.
rs	Pointer to the range_string structure containing the mapping from values to strings.

Returns: const char* A pointer to the corresponding string, or NULL if no match is found.

◆ try_rval64_to_str_idx()

WS_DLL_PUBLIC const char * try_rval64_to_str_idx	(	const uint64_t	val,
		const range_string *	rs,
		int *	idx
	)

Converts a 64-bit unsigned integer value to its corresponding string representation based on a range of values.

This function searches through an array of range_string structures to find a match for the given value. If a match is found, it sets the index parameter to the position of the matching range and returns the corresponding string pointer. If no match is found, it sets the index to -1 and returns NULL.

Parameters

val	The 64-bit unsigned integer value to convert.
rs	Pointer to an array of range_string structures containing the ranges and their corresponding strings.
idx	Pointer to an integer where the index of the matching range will be stored.

Returns: A pointer to the string representation of the value, or NULL if no match is found.

◆ try_rval_to_str()

WS_DLL_PUBLIC const char * try_rval_to_str	(	const uint32_t	val,
		const range_string *	rs
	)

Convert a 32-bit unsigned integer to its corresponding string representation based on a range string.

Parameters

val	The 32-bit unsigned integer value to convert.
rs	Pointer to the range_string structure containing the mapping of values to strings.

Returns: const char* The corresponding string representation, or NULL if not found.

◆ try_rval_to_str_idx()

WS_DLL_PUBLIC const char * try_rval_to_str_idx	(	const uint32_t	val,
		const range_string *	rs,
		int *	idx
	)

Converts a 32-bit unsigned integer value to its corresponding string representation based on a range_string array.

Parameters

val	The 32-bit unsigned integer value to convert.
rs	Pointer to the range_string array containing the value ranges and their corresponding strings.
idx	Pointer to an integer where the index of the matched range will be stored. If no match is found, -1 is stored.

Returns: const char* The string representation of the value if a match is found; otherwise, NULL.

◆ try_str_to_str()

WS_DLL_PUBLIC const char * try_str_to_str	(	const char *	val,
		const string_string *	vs
	)

Converts a string to another string based on a value-string mapping.

Parameters

val	The input string to convert.
vs	The value-string mapping table.

Returns: The converted string, or NULL if no match is found.

◆ try_str_to_str_idx()

WS_DLL_PUBLIC const char * try_str_to_str_idx	(	const char *	val,
		const string_string *	vs,
		int *	idx
	)

Converts a string to an index in a string-string mapping table.

Parameters

val	The string to look up.
vs	The string-string mapping table.
idx	Pointer to store the resulting index.

Returns: The corresponding string from the table, or NULL if not found.

◆ try_time_val_to_str()

WS_DLL_PUBLIC const char * try_time_val_to_str	(	const nstime_t *	val,
		const time_value_string *	vs
	)

Tries to match a time value against an array of time_value_string entries.

Parameters

val	Pointer to the nstime_t structure representing the time value to be matched.
vs	Pointer to the time_value_string array containing possible matches.

Returns: const char* The associated string pointer if a match is found, otherwise NULL.

◆ try_val64_to_str()

WS_DLL_PUBLIC const char * try_val64_to_str	(	const uint64_t	val,
		const val64_string *	vs
	)

Attempt to convert a 64-bit value to a string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to detect unknown values without falling back to a default string or allocating memory.

Parameters

val	64-bit value to convert.
vs	Array of 64-bit value-string mappings.

Returns: A constant string if found, or NULL if not found.

◆ try_val64_to_str_idx()

WS_DLL_PUBLIC const char * try_val64_to_str_idx	(	const uint64_t	val,
		const val64_string *	vs,
		int *	idx
	)

Attempt to convert a 64-bit value to a string and retrieve its index.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed for further processing or diagnostics.

Parameters

val	64-bit value to convert.
vs	Array of 64-bit value-string mappings.
idx	Pointer to an integer to receive the index of the match.

Returns: A constant string if found, or NULL if not found.

◆ try_val64_to_str_idx_ext()

WS_DLL_PUBLIC const char * try_val64_to_str_idx_ext	(	const uint64_t	val,
		val64_string_ext *	vse,
		int *	idx
	)

Convert a 64-bit value to its corresponding string index and pointer.

Parameters

val	The 64-bit value to convert.
vse	Pointer to the value_string_ext structure containing the mapping.
idx	Pointer to store the resulting index.

Returns: The corresponding string pointer, or NULL if not found.

◆ try_val_to_str()

WS_DLL_PUBLIC const char * try_val_to_str	(	const uint32_t	val,
		const value_string *	vs
	)

Attempt to convert a numeric value to a string using a value-string mapping.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to distinguish between known and unknown values without falling back to a default string.

Parameters

val	Numeric value to convert.
vs	Array of value-string mappings.

Returns: A constant string if found, or NULL if not found.

◆ try_val_to_str_ext()

WS_DLL_PUBLIC const char * try_val_to_str_ext	(	const uint32_t	val,
		value_string_ext *	vse
	)

Attempt to convert a numeric value to a string using an extended value-string mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string. If not found, returns NULL.

This function is useful when the caller wants to detect unknown values without allocating memory or falling back to a default string.

Parameters

val	Numeric value to convert.
vse	Pointer to the extended value-string mapping structure.

Returns: A constant string if found, or NULL if not found.

◆ try_val_to_str_idx()

WS_DLL_PUBLIC const char * try_val_to_str_idx	(	const uint32_t	val,
		const value_string *	vs,
		int *	idx
	)

Attempt to convert a numeric value to a string and retrieve its index.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed.

Parameters

val	Numeric value to convert.
vs	Array of value-string mappings.
idx	Pointer to an integer to receive the index of the match.

Returns: A constant string if found, or NULL if not found.

◆ try_val_to_str_idx_ext()

WS_DLL_PUBLIC const char * try_val_to_str_idx_ext	(	const uint32_t	val,
		value_string_ext *	vse,
		int *	idx
	)

Attempt to convert a numeric value to a string and retrieve its index from an extended mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string and sets *idx to the index of the matching entry within the original value_string array. If not found, returns NULL and leaves *idx unchanged.

This function is useful when both the string representation and its position in the mapping array are needed for diagnostics or further processing.

Parameters

val	Numeric value to convert.
vse	Pointer to the extended value-string mapping structure.
idx	Pointer to an integer to receive the index of the match.

Returns: A constant string if found, or NULL if not found.

◆ val64_string_ext_match_type_str()

WS_DLL_PUBLIC const char * val64_string_ext_match_type_str ( const val64_string_ext * vse )

Returns a string representation of the match type for a 64-bit value string extension.

Parameters

vse	Pointer to the val64_string_ext structure containing the match type information.

Returns: const char* A string describing the match type, or "[Invalid]" if the type is not recognized.

◆ val64_string_ext_new()

WS_DLL_PUBLIC val64_string_ext * val64_string_ext_new	(	wmem_allocator_t *	scope,
		const val64_string *	vs,
		unsigned	vs_tot_num_entries,
		const char *	vs_name
	)

Create a new extended value string structure.

Parameters

scope	Memory allocator scope for the new structure.
vs	Pointer to the base value string array.
vs_tot_num_entries	Total number of entries in the value string array.
vs_name	Name of the value string.

Returns: A pointer to the newly created val64_string_ext structure, or NULL if an error occurred.

◆ val64_string_ext_validate()

WS_DLL_PUBLIC bool val64_string_ext_validate ( const val64_string_ext * vse )

Validates a value_string_ext structure.

This function checks if the provided value_string_ext pointer is valid and if its match function is one of the allowed types.

Parameters

vse	Pointer to the value_string_ext structure to validate.

Returns: true if the validation passes, false otherwise.

◆ val64_to_str_const()

WS_DLL_PUBLIC const char * val64_to_str_const	(	const uint64_t	val,
		const val64_string *	vs,
		const char *	unknown_str
	)

Convert a 64-bit value to a constant string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the specified unknown_str.

This function does not allocate memory and is suitable for use in contexts where a constant string is sufficient and memory management must be avoided.

Parameters

val	64-bit value to convert.
vs	Array of 64-bit value-string mappings.
unknown_str	Fallback string if `val` is not found in `vs`.

Returns: A constant string representing the value or unknown_str.

◆ val64_to_str_wmem()

WS_DLL_PUBLIC const char * val64_to_str_wmem	(	wmem_allocator_t *	scope,
		const uint64_t	val,
		const val64_string *	vs,
		const char *	fmt
	)

Convert a 64-bit value to a string using a value-string mapping.

Searches the provided val64_string array vs for an entry matching val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string and returns the result. The returned string is allocated using the specified wmem_allocator_t scope.

Parameters

scope	Memory allocator scope for the returned string.
val	64-bit value to convert.
vs	Array of 64-bit value-string mappings.
fmt	Format string used if `val` is not found in `vs`.

Returns: A newly allocated string representing the value.

◆ val_to_str()

WS_DLL_PUBLIC char * val_to_str	(	wmem_allocator_t *	scope,
		const uint32_t	val,
		const value_string *	vs,
		const char *	fmt
	)

Convert a numeric value to a string using a value-string mapping.

Searches the provided value_string array vs for a matching entry with value val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string and returns the result. Memory is allocated using the specified wmem_allocator_t scope.

Parameters

scope	Memory allocator scope for the returned string.
val	Numeric value to convert.
vs	Array of value-string mappings.
fmt	Format string used if `val` is not found in `vs`.

Returns: A newly allocated string representing the value.

◆ val_to_str_const()

WS_DLL_PUBLIC const char * val_to_str_const	(	const uint32_t	val,
		const value_string *	vs,
		const char *	unknown_str
	)

Convert a numeric value to a constant string using a value-string mapping.

Searches the provided value_string array vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the provided unknown_str.

This function does not allocate memory and is suitable for use in contexts where a constant string is sufficient and memory management must be avoided.

Parameters

val	Numeric value to convert.
vs	Array of value-string mappings.
unknown_str	Fallback string if `val` is not found in `vs`.

Returns: A constant string representing the value or unknown_str.

◆ val_to_str_ext()

WS_DLL_PUBLIC char * val_to_str_ext	(	wmem_allocator_t *	scope,
		const uint32_t	val,
		value_string_ext *	vse,
		const char *	fmt
	)

Convert a numeric value to a string using an extended value-string mapping.

Searches the extended value-string structure vse for an entry matching val. If found, returns the corresponding string. If not found, formats the value using the provided fmt string. The result is allocated using the specified wmem_allocator_t scope.

This function is useful for enhanced lookup scenarios where additional metadata or scoped memory management is required.

Parameters

scope	Memory allocator scope for the returned string.
val	Numeric value to convert.
vse	Pointer to the extended value-string mapping structure.
fmt	Format string used if `val` is not found in `vse`.

Returns: A newly allocated string representing the value.

◆ val_to_str_ext_const()

WS_DLL_PUBLIC const char * val_to_str_ext_const	(	const uint32_t	val,
		value_string_ext *	vs,
		const char *	unknown_str
	)

Convert a numeric value to a constant string using an extended value-string mapping.

Searches the extended value-string structure vs for an entry matching val. If found, returns the corresponding constant string. If not found, returns the specified unknown_str.

This function does not allocate memory and is suitable for contexts where a constant string is sufficient and memory management must be avoided.

Parameters

val	Numeric value to convert.
vs	Pointer to the extended value-string mapping structure.
unknown_str	Fallback string if `val` is not found in `vs`.

Returns: A constant string representing the value or unknown_str.

◆ value_str_value_compare()

WS_DLL_PUBLIC int value_str_value_compare	(	const void *	a,
		const void *	b
	)

Compare two value_string entries by their numeric value.

Used primarily for sorting or searching operations on arrays of value_string structures. This function compares the value fields of the two entries pointed to by a and b.

Parameters

a	Pointer to the first `value_string` entry.
b	Pointer to the second `value_string` entry.

Returns: Negative if a < b, zero if a == b, positive if a > b.

◆ value_string_ext_free()

WS_DLL_PUBLIC void value_string_ext_free ( value_string_ext * vse )

Free an extended value-string mapping structure.

Releases any memory associated with the given value_string_ext structure, including its internal scope if applicable. This function should be called when the extended mapping is no longer needed to avoid memory leaks.

Parameters

vse	Pointer to the `value_string_ext` structure to be freed.

◆ value_string_ext_match_type_str()

WS_DLL_PUBLIC const char * value_string_ext_match_type_str ( const value_string_ext * vse )

Returns a string representation of the match type for a value_string_ext.

Parameters

vse	Pointer to the value_string_ext structure.

Returns: const char* A string describing the match type, or "[Invalid]" if unknown.

◆ value_string_ext_new()

WS_DLL_PUBLIC value_string_ext * value_string_ext_new	(	wmem_allocator_t *	scope,
		const value_string *	vs,
		unsigned	vs_tot_num_entries,
		const char *	vs_name
	)

Create a new extended value-string mapping structure.

Allocates and initializes a value_string_ext object using the provided value_string array.

Parameters

scope	Memory allocator scope for the new structure.
vs	Pointer to the value-string array.
vs_tot_num_entries	Total number of entries in the array (excluding the final {0, NULL}).
vs_name	Descriptive name for the mapping (used in diagnostics).

Returns: Pointer to the newly created value_string_ext structure.

◆ value_string_ext_validate()

WS_DLL_PUBLIC bool value_string_ext_validate ( const value_string_ext * vse )

Validates a value_string_ext structure.

This function checks if the provided value_string_ext pointer is valid and if its match function pointer is one of the allowed types.

Parameters

vse	Pointer to the value_string_ext structure to validate.

Returns: true if the validation passes, false otherwise.

◆ value_string_externals_cleanup()

WS_DLL_PUBLIC void value_string_externals_cleanup ( void )

Cleans up external value string resources.

This function destroys the hash tables used to store registered value strings and their extensions.

◆ value_string_externals_init()

WS_DLL_PUBLIC void value_string_externals_init ( void )

Initializes external value string and extension registries.

This function initializes two hash tables to store registered external value strings and their extensions.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ _VS_ARRAY_SC_XXX

◆ _VS_ARRAY_XXX

◆ _VS_ENUM_XXX

Typedef Documentation

◆ val64_string

◆ value_string

Function Documentation

◆ _try_val64_to_str_ext_init()

◆ _try_val_to_str_ext_init()

◆ bytesprefix_to_str()

◆ bytesval_to_str_wmem()

◆ get_external_value_string()

◆ get_external_value_string_ext()

◆ register_external_value_string()

◆ register_external_value_string_ext()

◆ str_to_str_wmem()

◆ str_to_val()

◆ str_to_val_idx()

◆ try_bytesprefix_to_str()

◆ try_rval64_to_str()

◆ try_rval64_to_str_idx()

◆ try_rval_to_str()

◆ try_rval_to_str_idx()

◆ try_str_to_str()

◆ try_str_to_str_idx()

◆ try_time_val_to_str()

◆ try_val64_to_str()

◆ try_val64_to_str_idx()

◆ try_val64_to_str_idx_ext()

◆ try_val_to_str()

◆ try_val_to_str_ext()

◆ try_val_to_str_idx()

◆ try_val_to_str_idx_ext()

◆ val64_string_ext_match_type_str()

◆ val64_string_ext_new()

◆ val64_string_ext_validate()

◆ val64_to_str_const()

◆ val64_to_str_wmem()

◆ val_to_str()

◆ val_to_str_const()

◆ val_to_str_ext()

◆ val_to_str_ext_const()

◆ value_str_value_compare()

◆ value_string_ext_free()

◆ value_string_ext_match_type_str()

◆ value_string_ext_new()

◆ value_string_ext_validate()

◆ value_string_externals_cleanup()

◆ value_string_externals_init()