Union value type

group jsdrv_union

A generic union value type.

Defines

jsdrv_union_null()

jsdrv_union_null_r()

jsdrv_union_f32(_value)

jsdrv_union_f32_r(_value)

jsdrv_union_f64(_value)

jsdrv_union_f64_r(_value)

jsdrv_union_u8(_value)

jsdrv_union_u8_r(_value)

jsdrv_union_u16(_value)

jsdrv_union_u16_r(_value)

jsdrv_union_u32(_value)

jsdrv_union_u32_r(_value)

jsdrv_union_u64(_value)

jsdrv_union_u64_r(_value)

jsdrv_union_i8(_value)

jsdrv_union_i8_r(_value)

jsdrv_union_i16(_value)

jsdrv_union_i16_r(_value)

jsdrv_union_i32(_value)

jsdrv_union_i32_r(_value)

jsdrv_union_i64(_value)

jsdrv_union_i64_r(_value)

jsdrv_union_str(_value)

jsdrv_union_cstr(_value)

jsdrv_union_cstr_r(_value)

jsdrv_union_json(_value)

jsdrv_union_cjson(_value)

jsdrv_union_cjson_r(_value)

jsdrv_union_bin(_value, _size)

jsdrv_union_cbin(_value, _size)

jsdrv_union_cbin_r(_value, _size)

Enums

enum jsdrv_union_e

The allowed data types.

Values:

enumerator JSDRV_UNION_NULL

NULL value. Also used to clear existing value.

enumerator JSDRV_UNION_STR

UTF-8 string value, null terminated.

enumerator JSDRV_UNION_JSON

UTF-8 JSON string value, null terminated.

enumerator JSDRV_UNION_BIN

Raw binary value.

enumerator JSDRV_UNION_RSV0

Reserved, do not use.

enumerator JSDRV_UNION_RSV1

Reserved, do not use.

enumerator JSDRV_UNION_F32

32-bit IEEE 754 floating point

enumerator JSDRV_UNION_F64

64-bit IEEE 754 floating point

enumerator JSDRV_UNION_U8

Unsigned 8-bit integer value.

enumerator JSDRV_UNION_U16

Unsigned 16-bit integer value.

enumerator JSDRV_UNION_U32

Unsigned 32-bit integer value.

enumerator JSDRV_UNION_U64

Unsigned 64-bit integer value.

enumerator JSDRV_UNION_I8

Signed 8-bit integer value.

enumerator JSDRV_UNION_I16

Signed 16-bit integer value.

enumerator JSDRV_UNION_I32

Signed 32-bit integer value.

enumerator JSDRV_UNION_I64

Signed 64-bit integer value.

enum jsdrv_union_flag_e

The standardized Joulescope driver union flags.

Applications may define custom flags in jsdrv_union_s.app.

Values:

enumerator JSDRV_UNION_FLAG_NONE

No flags specified.

enumerator JSDRV_UNION_FLAG_RETAIN

The PubSub instance should retain this value.

enumerator JSDRV_UNION_FLAG_CONST

The value points to a const that will remain valid indefinitely.

enumerator JSDRV_UNION_FLAG_HEAP_MEMORY

The value uses dynamically allocated heap memory that must be freed.

Functions

bool jsdrv_union_eq(const struct jsdrv_union_s *v1, const struct jsdrv_union_s *v2)

Check if two values are equal.

This check only compares the type and value. The types and values must match exactly. However, if ignores the additional fields [flags, op, app]. Use jsdrv_union_eq_strict() to also compare these fields. Use jsdrv_union_equiv() to more loosely check the value.

Parameters:

• v1 – The first value.

• v2 – The second value.

Returns:

True if equal, false if not equal.

bool jsdrv_union_eq_exact(const struct jsdrv_union_s *v1, const struct jsdrv_union_s *v2)

Check if two values are equal.

This check strictly compares every field.

Parameters:

• v1 – The first value.

• v2 – The second value.

Returns:

True if equal, false if not equal.

bool jsdrv_union_equiv(const struct jsdrv_union_s *v1, const struct jsdrv_union_s *v2)

Check if two values are equivalent.

This check performs type up-conversions to attempt to match the two fields.

Parameters:

• v1 – The first value.

• v2 – The second value.

Returns:

True if equal, false if not equal.

void jsdrv_union_widen(struct jsdrv_union_s *x)

Widen to the largest-size, compatible numeric type.

This widening conversion preserves float, signed, and unsigned characteristics. This check performs type up-conversions to attempt to match the two fields.

See also

jsdrv_union_as_type()

Parameters:

x – The value to widen in place.

int32_t jsdrv_union_as_type(struct jsdrv_union_s *x, uint8_t type)

Convert value to a specific type.

Parameters:

• x – The value to convert in place.

• type – The target type.

Returns:

0 or error code.

int32_t jsdrv_union_to_bool(const struct jsdrv_union_s *value, bool *rv)

Convert a value to a boolean.

Parameters:

• value – The value to convert. For numeric types, and non-zero value is presumed true. String and JSON compare against a case insensitive string list using jsdrv_cstr_to_bool.. True is [“true”, “on”, “enable”, “enabled”, “yes”] and False is [“false”, “off”, “disable”, “disabled”, “no”]. All other values return an error.

• rv – The resulting boolean value.

Returns:

0 or error code.

static inline bool jsdrv_union_is_type_ptr(const struct jsdrv_union_s *value)

Check if the union contains a pointer type.

Parameters:

value – The union value.

Returns:

True is the union contains a pointer type, false otherwise.

const char *jsdrv_union_type_to_str(uint8_t type)

Convert the type to a user-meaningful string.

Parameters:

type – The jsdrv_union_e type.

Returns:

The user-meaningful string representation for the type.

int32_t jsdrv_union_value_to_str(const struct jsdrv_union_s *value, char *str, uint32_t str_len, uint32_t opts)

Convert the value to a user-meaningful string.

Parameters:

• value – The value.

• str – [out] The string to hold the value.

• str_len – The maximum length of str, in bytes.

• opts – The formatting options. 0=value only, 1=verbose with type and flags.

Returns:

0 or error code.

union jsdrv_union_inner_u

#include <union.h>

The actual value holder for jsdrv_union_s.

Public Members

const char *str

JSDRV_UNION_STR, JSDRV_UNION_JSON.

const uint8_t *bin

JSDRV_UNION_BIN.

float f32

JSDRV_UNION_F32.

double f64

JSDRV_UNION_F64.

uint8_t u8

JSDRV_UNION_U8.

uint16_t u16

JSDRV_UNION_U16.

uint32_t u32

JSDRV_UNION_U32.

uint64_t u64

JSDRV_UNION_U64.

int8_t i8

JSDRV_UNION_I8.

int16_t i16

JSDRV_UNION_I16.

int32_t i32

JSDRV_UNION_I32.

int64_t i64

JSDRV_UNION_I64.

struct jsdrv_union_s

#include <union.h>

The value holder for all types.

Public Members

uint8_t type

The jsdrv_union_e data format indicator.

uint8_t flags

The jsdrv_union_flag_e flags.

uint8_t op

The application-specific operation.

uint8_t app

Application specific data. If unused, write to 0.

uint32_t size

payload size for pointer types, including null terminator for strings.

union jsdrv_union_inner_u value

The actual value.