Union value type

group Union value type

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_STDMSG

mb_stdmsg_s constant binary message, see mb/stdmsg.h

enumerator JSDRV_UNION_FRAME

Comm frame binary message, see doc/comm/frame.md and mb/comm/frame.h.

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, it ignores the additional fields [flags, op, app]. Use jsdrv_union_eq_exact() 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. Float types are widened to f64, signed integer types to i64, and unsigned integer types to u64. Pointer types (string, JSON, binary) are unchanged.

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.

int32_t jsdrv_union_copy(struct jsdrv_union_s *dst, const struct jsdrv_union_s *src, void *buffer, size_t buffer_size)

Copy a union value into caller-owned storage.

This helper makes it safe to retain a jsdrv_union_s past a jsdrv_subscribe_fn callback invocation (the callback documents that value and any referenced memory are only valid for the duration of the call). For scalar types the struct is copied verbatim. For pointer types, the payload is copied into buffer and dst is updated to reference buffer. The JSDRV_UNION_FLAG_HEAP_MEMORY flag is cleared on dst since the caller owns buffer.

Parameters:

• dst – [out] The destination union. Its fields will be fully overwritten; it does not need to be pre-initialized.

• src – [in] The source union.

• buffer – [out] Caller-provided storage used only for pointer types (string, JSON, binary, stdmsg, frame). May be NULL when buffer_size is 0 and the caller knows src is a scalar type.

• buffer_size – [in] The size of buffer in bytes.

Returns:

0 on success, or JSDRV_ERROR_PARAMETER_INVALID if dst or src is NULL, or JSDRV_ERROR_TOO_SMALL if buffer is too small for a pointer payload.

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.