automerge-rb 0.1.1

data/vendor/automerge-rust/automerge-c/examples/quickstart.c

@@ -0,0 +1,131 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <automerge-c/automerge.h>
+#include <automerge-c/utils/enum_string.h>
+#include <automerge-c/utils/stack.h>
+#include <automerge-c/utils/stack_callback_data.h>
+#include <automerge-c/utils/string.h>
+
+static bool abort_cb(AMstack**, void*);
+
+/**
+ * \brief Based on https://automerge.github.io/docs/quickstart
+ */
+int main(int argc, char** argv) {
+    AMstack* stack = NULL;
+    AMdoc* doc1;
+    AMitemToDoc(AMstackItem(&stack, AMcreate(NULL), abort_cb, AMexpect(AM_VAL_TYPE_DOC)), &doc1);
+    AMobjId const* const cards =
+        AMitemObjId(AMstackItem(&stack, AMmapPutObject(doc1, AM_ROOT, AMstr("cards"), AM_OBJ_TYPE_LIST), abort_cb,
+                                AMexpect(AM_VAL_TYPE_OBJ_TYPE)));
+    AMobjId const* const card1 =
+        AMitemObjId(AMstackItem(&stack, AMlistPutObject(doc1, cards, SIZE_MAX, true, AM_OBJ_TYPE_MAP), abort_cb,
+                                AMexpect(AM_VAL_TYPE_OBJ_TYPE)));
+    AMstackItem(NULL, AMmapPutStr(doc1, card1, AMstr("title"), AMstr("Rewrite everything in Clojure")), abort_cb,
+                AMexpect(AM_VAL_TYPE_VOID));
+    AMstackItem(NULL, AMmapPutBool(doc1, card1, AMstr("done"), false), abort_cb, AMexpect(AM_VAL_TYPE_VOID));
+    AMobjId const* const card2 =
+        AMitemObjId(AMstackItem(&stack, AMlistPutObject(doc1, cards, SIZE_MAX, true, AM_OBJ_TYPE_MAP), abort_cb,
+                                AMexpect(AM_VAL_TYPE_OBJ_TYPE)));
+    AMstackItem(NULL, AMmapPutStr(doc1, card2, AMstr("title"), AMstr("Rewrite everything in Haskell")), abort_cb,
+                AMexpect(AM_VAL_TYPE_VOID));
+    AMstackItem(NULL, AMmapPutBool(doc1, card2, AMstr("done"), false), abort_cb, AMexpect(AM_VAL_TYPE_VOID));
+    AMstackItem(NULL, AMcommit(doc1, AMstr("Add card"), NULL), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+
+    AMdoc* doc2;
+    AMitemToDoc(AMstackItem(&stack, AMcreate(NULL), abort_cb, AMexpect(AM_VAL_TYPE_DOC)), &doc2);
+    AMstackItem(NULL, AMmerge(doc2, doc1), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+
+    AMbyteSpan binary;
+    AMitemToBytes(AMstackItem(&stack, AMsave(doc1), abort_cb, AMexpect(AM_VAL_TYPE_BYTES)), &binary);
+    AMitemToDoc(AMstackItem(&stack, AMload(binary.src, binary.count), abort_cb, AMexpect(AM_VAL_TYPE_DOC)), &doc2);
+
+    AMstackItem(NULL, AMmapPutBool(doc1, card1, AMstr("done"), true), abort_cb, AMexpect(AM_VAL_TYPE_VOID));
+    AMstackItem(NULL, AMcommit(doc1, AMstr("Mark card as done"), NULL), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+
+    AMstackItem(NULL, AMlistDelete(doc2, cards, 0), abort_cb, AMexpect(AM_VAL_TYPE_VOID));
+    AMstackItem(NULL, AMcommit(doc2, AMstr("Delete card"), NULL), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+
+    AMstackItem(NULL, AMmerge(doc1, doc2), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+
+    AMitems changes = AMstackItems(&stack, AMgetChanges(doc1, NULL), abort_cb, AMexpect(AM_VAL_TYPE_CHANGE));
+    AMitem* item = NULL;
+    while ((item = AMitemsNext(&changes, 1)) != NULL) {
+        AMchange* change;
+        AMitemToChange(item, &change);
+        AMitems const heads = AMstackItems(&stack, AMitemFromChangeHash(AMchangeHash(change)), abort_cb,
+                                           AMexpect(AM_VAL_TYPE_CHANGE_HASH));
+        char* const c_msg = AMstrdup(AMchangeMessage(change), NULL);
+        printf("%s %zu\n", c_msg, AMobjSize(doc1, cards, &heads));
+        free(c_msg);
+    }
+    AMstackFree(&stack);
+}
+
+/**
+ * \brief Examines the result at the top of the given stack and, if it's
+ *        invalid, prints an error message to `stderr`, deallocates all results
+ *        in the stack and exits.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] data A pointer to an owned `AMstackCallbackData` struct or `NULL`.
+ * \return `true` if the top `AMresult` in \p stack is valid, `false` otherwise.
+ * \pre \p stack `!= NULL`.
+ */
+static bool abort_cb(AMstack** stack, void* data) {
+    static char buffer[512] = {0};
+
+    char const* suffix = NULL;
+    if (!stack) {
+        suffix = "stack*";
+    } else if (!*stack) {
+        suffix = "stack";
+    } else if (!(*stack)->result) {
+        suffix = "result";
+    }
+    if (suffix) {
+        fprintf(stderr, "Null `AM%s*`.\n", suffix);
+        free(data);
+        AMstackFree(stack);
+        exit(EXIT_FAILURE);
+        return false;
+    }
+    AMstatus const status = AMresultStatus((*stack)->result);
+    switch (status) {
+        case AM_STATUS_ERROR:
+            strcpy(buffer, "Error");
+            break;
+        case AM_STATUS_INVALID_RESULT:
+            strcpy(buffer, "Invalid result");
+            break;
+        case AM_STATUS_OK:
+            break;
+        default:
+            sprintf(buffer, "Unknown `AMstatus` tag %d", status);
+    }
+    if (buffer[0]) {
+        char* const c_msg = AMstrdup(AMresultError((*stack)->result), NULL);
+        fprintf(stderr, "%s; %s.\n", buffer, c_msg);
+        free(c_msg);
+        free(data);
+        AMstackFree(stack);
+        exit(EXIT_FAILURE);
+        return false;
+    }
+    if (data) {
+        AMstackCallbackData* sc_data = (AMstackCallbackData*)data;
+        AMvalType const tag = AMitemValType(AMresultItem((*stack)->result));
+        if (tag != sc_data->bitmask) {
+            fprintf(stderr, "Unexpected tag `%s` (%d) instead of `%s` at %s:%d.\n", AMvalTypeToString(tag), tag,
+                    AMvalTypeToString(sc_data->bitmask), sc_data->file, sc_data->line);
+            free(data);
+            AMstackFree(stack);
+            exit(EXIT_FAILURE);
+            return false;
+        }
+    }
+    free(data);
+    return true;
+}

data/vendor/automerge-rust/automerge-c/include/automerge-c/utils/result.h

@@ -0,0 +1,30 @@
+#ifndef AUTOMERGE_C_UTILS_RESULT_H
+#define AUTOMERGE_C_UTILS_RESULT_H
+/**
+ * \file
+ * \brief Utility functions for use with `AMresult` structs.
+ */
+
+#include <stdarg.h>
+
+#include <automerge-c/automerge.h>
+
+/**
+ * \brief Transfers the items within an arbitrary list of results into a
+ *        new result in their order of specification.
+ * \param[in] count The count of subsequent arguments.
+ * \param[in] ... A \p count list of arguments, each of which is a pointer to
+ *                an `AMresult` struct whose items will be transferred out of it
+ *                and which is subsequently freed.
+ * \return A pointer to an `AMresult` struct or `NULL`.
+ * \pre `∀𝑥 ∈` \p ... `, AMresultStatus(𝑥) == AM_STATUS_OK`
+ * \post `(∃𝑥 ∈` \p ... `, AMresultStatus(𝑥) != AM_STATUS_OK) -> NULL`
+ * \attention All `AMresult` struct pointer arguments are passed to
+ *            `AMresultFree()` regardless of success; use `AMresultCat()`
+ *            instead if you wish to pass them to `AMresultFree()` yourself.
+ * \warning The returned `AMresult` struct pointer must be passed to
+ *          `AMresultFree()` in order to avoid a memory leak.
+ */
+AMresult* AMresultFrom(int count, ...);
+
+#endif /* AUTOMERGE_C_UTILS_RESULT_H */

data/vendor/automerge-rust/automerge-c/include/automerge-c/utils/stack.h

@@ -0,0 +1,130 @@
+#ifndef AUTOMERGE_C_UTILS_STACK_H
+#define AUTOMERGE_C_UTILS_STACK_H
+/**
+ * \file
+ * \brief Utility data structures and functions for hiding `AMresult` structs,
+ *        managing their lifetimes, and automatically applying custom
+ *        validation logic to the `AMitem` structs that they contain.
+ *
+ * \note The `AMstack` struct and its related functions drastically reduce the
+ *       need for boilerplate code and/or `goto` statement usage within a C
+ *       application but a higher-level programming language offers even better
+ *       ways to do the same things.
+ */
+
+#include <automerge-c/automerge.h>
+
+/**
+ * \struct AMstack
+ * \brief A node in a singly-linked list of result pointers.
+ */
+typedef struct AMstack {
+    /** A result to be deallocated. */
+    AMresult* result;
+    /** The previous node in the singly-linked list or `NULL`. */ 
+    struct AMstack* prev;
+} AMstack;
+
+/**
+ * \memberof AMstack
+ * \brief The prototype of a function that examines the result at the top of
+ *        the given stack in terms of some arbitrary data.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] data A pointer to arbitrary data or `NULL`.
+ * \return `true` if the top `AMresult` struct in \p stack is valid, `false`
+ *         otherwise.
+ * \pre \p stack `!= NULL`.
+ */
+typedef bool (*AMstackCallback)(AMstack** stack, void* data);
+
+/**
+ * \memberof AMstack
+ * \brief Deallocates the storage for a stack of results.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \pre \p stack `!= NULL`
+ * \post `*stack == NULL`
+ */
+void AMstackFree(AMstack** stack);
+
+/**
+ * \memberof AMstack
+ * \brief Gets a result from the stack after removing it.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] result A pointer to the `AMresult` to be popped or `NULL` to
+ *                   select the top result in \p stack.
+ * \return A pointer to an `AMresult` struct or `NULL`.
+ * \pre \p stack `!= NULL`
+ * \warning The returned `AMresult` struct pointer must be passed to
+ *          `AMresultFree()` in order to avoid a memory leak.
+ */
+AMresult* AMstackPop(AMstack** stack, AMresult const* result);
+
+/**
+ * \memberof AMstack
+ * \brief Pushes the given result onto the given stack, calls the given
+ *        callback with the given data to validate it and then either gets the
+ *        result if it's valid or gets `NULL` instead.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] result A pointer to an `AMresult` struct.
+ * \param[in] callback A pointer to a function with the same signature as
+ *                     `AMstackCallback()` or `NULL`.
+ * \param[in] data A pointer to arbitrary data or `NULL` which is passed to
+ *                 \p callback.
+ * \return \p result or `NULL`.
+ * \warning If \p stack `== NULL` then \p result is deallocated in order to
+ *          avoid a memory leak.
+ */
+AMresult* AMstackResult(AMstack** stack, AMresult* result, AMstackCallback callback, void* data);
+
+/**
+ * \memberof AMstack
+ * \brief Pushes the given result onto the given stack, calls the given
+ *        callback with the given data to validate it and then either gets the
+ *        first item in the sequence of items within that result if it's valid
+ *        or gets `NULL` instead.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] result A pointer to an `AMresult` struct.
+ * \param[in] callback A pointer to a function with the same signature as
+ *                     `AMstackCallback()` or `NULL`.
+ * \param[in] data A pointer to arbitrary data or `NULL` which is passed to
+ *                 \p callback.
+ * \return A pointer to an `AMitem` struct or `NULL`.
+ * \warning If \p stack `== NULL` then \p result is deallocated in order to
+ *          avoid a memory leak.
+ */
+AMitem* AMstackItem(AMstack** stack, AMresult* result, AMstackCallback callback, void* data);
+
+/**
+ * \memberof AMstack
+ * \brief Pushes the given result onto the given stack, calls the given
+ *        callback with the given data to validate it and then either gets an
+ *        `AMitems` struct over the sequence of items within that result if it's
+ *        valid or gets an empty `AMitems` instead.
+ *
+ * \param[in,out] stack A pointer to a pointer to an `AMstack` struct.
+ * \param[in] result A pointer to an `AMresult` struct.
+ * \param[in] callback A pointer to a function with the same signature as
+ *                     `AMstackCallback()` or `NULL`.
+ * \param[in] data A pointer to arbitrary data or `NULL` which is passed to
+ *                 \p callback.
+ * \return An `AMitems` struct.
+ * \warning If \p stack `== NULL` then \p result is deallocated immediately
+ *          in order to avoid a memory leak.
+ */
+AMitems AMstackItems(AMstack** stack, AMresult* result, AMstackCallback callback, void* data);
+
+/**
+ * \memberof AMstack
+ * \brief Gets the count of results that have been pushed onto the stack.
+ *
+ * \param[in,out] stack A pointer to an `AMstack` struct.
+ * \return A 64-bit unsigned integer.
+ */
+size_t AMstackSize(AMstack const* const stack);
+
+#endif /* AUTOMERGE_C_UTILS_STACK_H */

data/vendor/automerge-rust/automerge-c/include/automerge-c/utils/stack_callback_data.h

@@ -0,0 +1,53 @@
+#ifndef AUTOMERGE_C_UTILS_PUSH_CALLBACK_DATA_H
+#define AUTOMERGE_C_UTILS_PUSH_CALLBACK_DATA_H
+/**
+ * \file
+ * \brief Utility data structures, functions and macros for supplying
+ *        parameters to the custom validation logic applied to `AMitem`
+ *        structs.
+ */
+
+#include <automerge-c/automerge.h>
+
+/**
+ * \struct AMstackCallbackData
+ * \brief  A data structure for passing the parameters of an item value test
+ *         to an implementation of the `AMstackCallback` function prototype.
+ */
+typedef struct {
+    /** A bitmask of `AMvalType` tags. */
+    AMvalType bitmask;
+    /** A null-terminated file path string. */
+    char const* file;
+    /** The ordinal number of a line within a file. */
+    int line;
+} AMstackCallbackData;
+
+/**
+ * \memberof AMstackCallbackData
+ * \brief Allocates a new `AMstackCallbackData` struct and initializes its
+ *        members from their corresponding arguments.
+ *
+ * \param[in] bitmask A bitmask of `AMvalType` tags.
+ * \param[in] file A null-terminated file path string.
+ * \param[in] line The ordinal number of a line within a file.
+ * \return A pointer to a disowned `AMstackCallbackData` struct.
+ * \warning The returned pointer must be passed to `free()` to avoid a memory
+ *          leak.
+ */
+AMstackCallbackData* AMstackCallbackDataInit(AMvalType const bitmask, char const* const file, int const line);
+
+/**
+ * \memberof AMstackCallbackData
+ * \def AMexpect
+ * \brief Allocates a new `AMstackCallbackData` struct and initializes it from
+ *        an `AMvalueType` bitmask.
+ *
+ * \param[in] bitmask A bitmask of `AMvalType` tags.
+ * \return A pointer to a disowned `AMstackCallbackData` struct.
+ * \warning The returned pointer must be passed to `free()` to avoid a memory
+ *          leak.
+ */
+#define AMexpect(bitmask) AMstackCallbackDataInit(bitmask, __FILE__, __LINE__)
+
+#endif /* AUTOMERGE_C_UTILS_PUSH_CALLBACK_DATA_H */

data/vendor/automerge-rust/automerge-c/include/automerge-c/utils/string.h

@@ -0,0 +1,29 @@
+#ifndef AUTOMERGE_C_UTILS_STRING_H
+#define AUTOMERGE_C_UTILS_STRING_H
+/**
+ * \file
+ * \brief Utility functions for use with `AMbyteSpan` structs that provide
+ *        UTF-8 string views.
+ */
+
+#include <automerge-c/automerge.h>
+
+/**
+ * \memberof AMbyteSpan
+ * \brief Returns a pointer to a null-terminated byte string which is a
+ *        duplicate of the given UTF-8 string view except for the substitution
+ *        of its NUL (0) characters with the specified null-terminated byte
+ *        string.
+ *        
+ * \param[in] str A UTF-8 string view as an `AMbyteSpan` struct.
+ * \param[in] nul A null-terminated byte string to substitute for NUL characters
+ *                or `NULL` to substitute `"\\0"` for NUL characters.
+ * \return A disowned null-terminated byte string.
+ * \pre \p str.src `!= NULL`
+ * \pre \p str.count `<= sizeof(`\p str.src `)`
+ * \warning The returned pointer must be passed to `free()` to avoid a memory
+ *          leak. 
+ */
+char* AMstrdup(AMbyteSpan const str, char const* nul);
+
+#endif /* AUTOMERGE_C_UTILS_STRING_H */

data/vendor/automerge-rust/automerge-c/src/actor_id.rs

@@ -0,0 +1,193 @@
+use automerge as am;
+use libc::c_int;
+use std::cell::RefCell;
+use std::cmp::Ordering;
+use std::str::FromStr;
+
+use crate::byte_span::AMbyteSpan;
+use crate::result::{to_result, AMresult};
+
+macro_rules! to_actor_id {
+    ($handle:expr) => {{
+        let handle = $handle.as_ref();
+        match handle {
+            Some(b) => b,
+            None => return AMresult::error("Invalid `AMactorId*`").into(),
+        }
+    }};
+}
+
+pub(crate) use to_actor_id;
+
+/// \struct AMactorId
+/// \installed_headerfile
+/// \brief An actor's unique identifier.
+#[derive(Eq, PartialEq)]
+pub struct AMactorId {
+    body: *const am::ActorId,
+    hex_str: RefCell<Option<Box<str>>>,
+}
+
+impl AMactorId {
+    pub fn new(actor_id: &am::ActorId) -> Self {
+        Self {
+            body: actor_id,
+            hex_str: Default::default(),
+        }
+    }
+
+    fn to_str(&self) -> AMbyteSpan {
+        let mut hex_str = self.hex_str.borrow_mut();
+        match hex_str.as_mut() {
+            None => {
+                let hex_string = unsafe { (*self.body).to_hex_string() };
+                hex_str
+                    .insert(hex_string.into_boxed_str())
+                    .as_bytes()
+                    .into()
+            }
+            Some(hex_str) => hex_str.as_bytes().into(),
+        }
+    }
+}
+
+impl AsRef<am::ActorId> for AMactorId {
+    fn as_ref(&self) -> &am::ActorId {
+        unsafe { &*self.body }
+    }
+}
+
+/// \memberof AMactorId
+/// \brief Gets the value of an actor identifier as an array of bytes.
+///
+/// \param[in] actor_id A pointer to an `AMactorId` struct.
+/// \return An `AMbyteSpan` struct for an array of bytes.
+/// \pre \p actor_id `!= NULL`
+/// \internal
+///
+/// # Safety
+/// actor_id must be a valid pointer to an AMactorId
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdBytes(actor_id: *const AMactorId) -> AMbyteSpan {
+    match actor_id.as_ref() {
+        Some(actor_id) => actor_id.as_ref().into(),
+        None => Default::default(),
+    }
+}
+
+/// \memberof AMactorId
+/// \brief Compares two actor identifiers.
+///
+/// \param[in] actor_id1 A pointer to an `AMactorId` struct.
+/// \param[in] actor_id2 A pointer to an `AMactorId` struct.
+/// \return `-1` if \p actor_id1 `<` \p actor_id2, `0` if
+///         \p actor_id1 `==` \p actor_id2 and `1` if
+///         \p actor_id1 `>` \p actor_id2.
+/// \pre \p actor_id1 `!= NULL`
+/// \pre \p actor_id2 `!= NULL`
+/// \internal
+///
+/// #Safety
+/// actor_id1 must be a valid pointer to an AMactorId
+/// actor_id2 must be a valid pointer to an AMactorId
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdCmp(
+    actor_id1: *const AMactorId,
+    actor_id2: *const AMactorId,
+) -> c_int {
+    match (actor_id1.as_ref(), actor_id2.as_ref()) {
+        (Some(actor_id1), Some(actor_id2)) => match actor_id1.as_ref().cmp(actor_id2.as_ref()) {
+            Ordering::Less => -1,
+            Ordering::Equal => 0,
+            Ordering::Greater => 1,
+        },
+        (None, Some(_)) => -1,
+        (None, None) => 0,
+        (Some(_), None) => 1,
+    }
+}
+
+/// \memberof AMactorId
+/// \brief Allocates a new actor identifier and initializes it from a random
+///        UUID value.
+///
+/// \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_ACTOR_ID` item.
+/// \warning The returned `AMresult` struct pointer must be passed to
+///          `AMresultFree()` in order to avoid a memory leak.
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdInit() -> *mut AMresult {
+    to_result(Ok::<am::ActorId, am::AutomergeError>(am::ActorId::random()))
+}
+
+/// \memberof AMactorId
+/// \brief Allocates a new actor identifier and initializes it from an array of
+///        bytes value.
+///
+/// \param[in] src A pointer to an array of bytes.
+/// \param[in] count The count of bytes to copy from the array pointed to by
+///                  \p src.
+/// \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_ACTOR_ID` item.
+/// \pre \p src `!= NULL`
+/// \pre `sizeof(`\p src `) > 0`
+/// \pre \p count `<= sizeof(`\p src `)`
+/// \warning The returned `AMresult` struct pointer must be passed to
+///          `AMresultFree()` in order to avoid a memory leak.
+/// \internal
+///
+/// # Safety
+/// src must be a byte array of length `>= count`
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdFromBytes(src: *const u8, count: usize) -> *mut AMresult {
+    if !src.is_null() {
+        let value = std::slice::from_raw_parts(src, count);
+        to_result(Ok::<am::ActorId, am::InvalidActorId>(am::ActorId::from(
+            value,
+        )))
+    } else {
+        AMresult::error("Invalid uint8_t*").into()
+    }
+}
+
+/// \memberof AMactorId
+/// \brief Allocates a new actor identifier and initializes it from a
+///        hexadecimal UTF-8 string view value.
+///
+/// \param[in] value A UTF-8 string view as an `AMbyteSpan` struct.
+/// \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_ACTOR_ID` item.
+/// \warning The returned `AMresult` struct pointer must be passed to
+///          `AMresultFree()` in order to avoid a memory leak.
+/// \internal
+///
+/// # Safety
+/// value.src must be a byte array of length >= value.count
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdFromStr(value: AMbyteSpan) -> *mut AMresult {
+    use am::AutomergeError::InvalidActorId;
+
+    to_result(match (&value).try_into() {
+        Ok(s) => match am::ActorId::from_str(s) {
+            Ok(actor_id) => Ok(actor_id),
+            Err(_) => Err(InvalidActorId(String::from(s))),
+        },
+        Err(e) => Err(e),
+    })
+}
+
+/// \memberof AMactorId
+/// \brief Gets the value of an actor identifier as a UTF-8 hexadecimal string
+///        view.
+///
+/// \param[in] actor_id A pointer to an `AMactorId` struct.
+/// \return A UTF-8 string view as an `AMbyteSpan` struct.
+/// \pre \p actor_id `!= NULL`
+/// \internal
+///
+/// # Safety
+/// actor_id must be a valid pointer to an AMactorId
+#[no_mangle]
+pub unsafe extern "C" fn AMactorIdStr(actor_id: *const AMactorId) -> AMbyteSpan {
+    match actor_id.as_ref() {
+        Some(actor_id) => actor_id.to_str(),
+        None => Default::default(),
+    }
+}