<!-- SPDX-FileCopyrightText: Copyright 2023 Jetperch LLC
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. -->

<a id="h-union"></a>

# 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](#structjsdrv__union__s_1a48af9dab09413493219e3e375e54652b). 

*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](#_CPPv413jsdrv_union_s) \*v1, const struct [jsdrv_union_s](#_CPPv413jsdrv_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()](#group__jsdrv__union_1gaaa940662d46067e8f0250cc715b76398) to also compare these fields. Use [jsdrv_union_equiv()](#group__jsdrv__union_1gad49976a90d406a8a27661331d81b23cf) 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](#_CPPv413jsdrv_union_s) \*v1, const struct [jsdrv_union_s](#_CPPv413jsdrv_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](#_CPPv413jsdrv_union_s) \*v1, const struct [jsdrv_union_s](#_CPPv413jsdrv_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](#_CPPv413jsdrv_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()](#group__jsdrv__union_1gab686390e325483b8a9f9b16c8c4de687)

* **Parameters:**
  **x** – The value to widen in place. 

### int32_t jsdrv_union_as_type(struct [jsdrv_union_s](#_CPPv413jsdrv_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](#_CPPv413jsdrv_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](#_CPPv413jsdrv_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](#group__jsdrv__union_1ga2a05d885f40b41bfd2c499659678b597) type. 
* **Returns:**
  The user-meaningful string representation for the type. 

### int32_t jsdrv_union_value_to_str(const struct [jsdrv_union_s](#_CPPv413jsdrv_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](#_CPPv413jsdrv_union_s) \*dst, const struct [jsdrv_union_s](#_CPPv413jsdrv_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](#structjsdrv__union__s) past a [jsdrv_subscribe_fn](https://docs.joulescope.com/en/software/joulescope_driver/h_jsdrv.md#group__jsdrv__api_1ga1a0dfa56785bfb2ed3c0ac29414ee6e9) 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](https://docs.joulescope.com/en/software/joulescope_driver/h_error_code.md#group__jsdrv__ec_1gga4bb10d6ebaa503f491a70539b49df124aef600eacd8a0257c02bac780011c5cee) if dst or src is NULL, or [JSDRV_ERROR_TOO_SMALL](https://docs.joulescope.com/en/software/joulescope_driver/h_error_code.md#group__jsdrv__ec_1gga4bb10d6ebaa503f491a70539b49df124aef806f51d59aead5e00e8acf1fda0765) 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](#structjsdrv__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](#group__jsdrv__union_1ga2a05d885f40b41bfd2c499659678b597) data format indicator. 

### uint8_t flags

The [jsdrv_union_flag_e](#group__jsdrv__union_1ga479b4f3b1d1bc92fb1e0e57023981c1e) 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](#_CPPv419jsdrv_union_inner_u) value

The actual value.