| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
value_string.h File Reference
`#include <stdint.h>`
`#include "ws_symbol_export.h"`
`#include <wsutil/nstime.h>`

Go to the source code of this file.

## 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) G_GNUC_PRINTF(4
| Convert a numeric value to a string using a value-string mapping.
WS_DLL_PUBLIC char 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) G_GNUC_PRINTF(4
| Convert a 64-bit value to a string using a value-string mapping.
WS_DLL_PUBLIC const char 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) G_GNUC_PRINTF(4
| Convert a numeric value to a string using an extended value-string mapping.
WS_DLL_PUBLIC char 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)
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) G_GNUC_PRINTF(4
WS_DLL_PUBLIC char 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)
WS_DLL_PUBLIC const char * | str_to_str_wmem (wmem_allocator_t *scope, const char *val, const string_string *vs, const char *fmt) G_GNUC_PRINTF(4
WS_DLL_PUBLIC const char WS_DLL_PUBLIC const char * | try_str_to_str (const char *val, const string_string *vs)
WS_DLL_PUBLIC const char * | try_str_to_str_idx (const char *val, const string_string *vs, int *idx)
WS_DLL_PUBLIC const char * | rval_to_str_wmem (wmem_allocator_t *scope, const uint32_t val, const range_string *rs, const char *fmt) G_GNUC_PRINTF(4
WS_DLL_PUBLIC const char 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)
WS_DLL_PUBLIC const char * | try_rval_to_str_idx (const uint32_t val, const range_string *rs, int *idx)
WS_DLL_PUBLIC const char * | try_rval64_to_str (const uint64_t val, const range_string *rs)
WS_DLL_PUBLIC const char * | try_rval64_to_str_idx (const uint64_t val, const range_string *rs, int *idx)
WS_DLL_PUBLIC const char * | try_time_val_to_str (const nstime_t *val, const time_value_string *vs)
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) G_GNUC_PRINTF(5
WS_DLL_PUBLIC const char 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) G_GNUC_PRINTF(5
WS_DLL_PUBLIC const char WS_DLL_PUBLIC const char * | try_bytesprefix_to_str (const uint8_t *haystack, const size_t haystack_len, const bytes_string *bs)
WS_DLL_PUBLIC void | register_external_value_string (const char *name, const value_string *vs)
WS_DLL_PUBLIC value_string * | get_external_value_string (const char *name)
WS_DLL_PUBLIC void | register_external_value_string_ext (const char *name, const value_string_ext *vse)
WS_DLL_PUBLIC value_string_ext * | get_external_value_string_ext (const char *name)
WS_DLL_PUBLIC void | value_string_externals_init (void)
WS_DLL_PUBLIC void | value_string_externals_cleanup (void)
WS_DLL_PUBLIC bool | value_string_ext_validate (const value_string_ext *vse)
WS_DLL_PUBLIC const char * | value_string_ext_match_type_str (const value_string_ext *vse)
WS_DLL_PUBLIC bool | val64_string_ext_validate (const val64_string_ext *vse)
WS_DLL_PUBLIC const char * | val64_string_ext_match_type_str (const val64_string_ext *vse)

## Detailed Description

Definitions for value_string structures and routines

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

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.

## ◆ 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_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_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_to_str_const()

WS_DLL_PUBLIC const char 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 char 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 char 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_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.