automerge.h

#ifndef AUTOMERGE_C_H
#define AUTOMERGE_C_H

/**
 * \file
 * \brief All constants, functions and types in the core Automerge C API.
 *
 * \warning This file is auto-generated by cbindgen.
 */


#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>


/**
 * \defgroup enumerations Public Enumerations
 *  Symbolic names for integer constants.
 */

/**
 * \memberof AMdoc
 * \def AM_ROOT
 * \brief The root object of a document.
 */
#define AM_ROOT NULL

/**
 * \memberof AMdoc
 * \def AM_CHANGE_HASH_SIZE
 * \brief The count of bytes in a change hash.
 */
#define AM_CHANGE_HASH_SIZE 32


/**
 * \ingroup enumerations
 * \enum AMidxType
 * \installed_headerfile
 * \brief The type of an item's index.
 */
enum AMidxType {
  /**
   * The default tag, not a type signifier.
   */
  AM_IDX_TYPE_DEFAULT = 0,
  /**
   * A UTF-8 string view key.
   */
  AM_IDX_TYPE_KEY,
  /**
   * A 64-bit unsigned integer position.
   */
  AM_IDX_TYPE_POS,
};
typedef uint8_t AMidxType;

/**
 * \ingroup enumerations
 * \enum AMmarkExpand
 * \installed_headerfile
 * \brief A mark's expansion mode for when bordering text is inserted.
 */
enum AMmarkExpand {
  /**
   * Include text inserted at the end offset.
   */
  AM_MARK_EXPAND_AFTER = 3,
  /**
   * Include text inserted at the start offset.
   */
  AM_MARK_EXPAND_BEFORE = 2,
  /**
   * Include text inserted at either offset.
   */
  AM_MARK_EXPAND_BOTH = 4,
  /**
   * The default tag, not a mark expansion mode signifier.
   */
  AM_MARK_EXPAND_DEFAULT = 0,
  /**
   * Exclude text inserted at either offset.
   */
  AM_MARK_EXPAND_NONE = 1,
};
typedef uint8_t AMmarkExpand;

/**
 * \ingroup enumerations
 * \enum AMobjType
 * \installed_headerfile
 * \brief The type of an object.
 */
enum AMobjType {
  /**
   * The default tag, not a type signifier.
   */
  AM_OBJ_TYPE_DEFAULT = 0,
  /**
   * A list.
   */
  AM_OBJ_TYPE_LIST = 1,
  /**
   * A key-value map.
   */
  AM_OBJ_TYPE_MAP,
  /**
   * A list of Unicode graphemes.
   */
  AM_OBJ_TYPE_TEXT,
};
typedef uint8_t AMobjType;

/**
 * \ingroup enumerations
 * \enum AMstatus
 * \installed_headerfile
 * \brief The status of an API call.
 */
enum AMstatus {
  /**
   * Success.
   * \note This tag is unalphabetized so that `0` indicates success.
   */
  AM_STATUS_OK,
  /**
   * Failure due to an error.
   */
  AM_STATUS_ERROR,
  /**
   * Failure due to an invalid result.
   */
  AM_STATUS_INVALID_RESULT,
};
typedef uint8_t AMstatus;

/**
 * \ingroup enumerations
 * \enum AMvalType
 * \installed_headerfile
 * \brief The type of an item's value.
 */
enum AMvalType {
  /**
   * An actor identifier value.
   */
  AM_VAL_TYPE_ACTOR_ID = (1 << 1),
  /**
   * A boolean value.
   */
  AM_VAL_TYPE_BOOL = (1 << 2),
  /**
   * A view onto an array of bytes value.
   */
  AM_VAL_TYPE_BYTES = (1 << 3),
  /**
   * A change value.
   */
  AM_VAL_TYPE_CHANGE = (1 << 4),
  /**
   * A change hash value.
   */
  AM_VAL_TYPE_CHANGE_HASH = (1 << 5),
  /**
   * A CRDT counter value.
   */
  AM_VAL_TYPE_COUNTER = (1 << 6),
  /**
   * The default tag, not a type signifier.
   */
  AM_VAL_TYPE_DEFAULT = 0,
  /**
   * A document value.
   */
  AM_VAL_TYPE_DOC = (1 << 7),
  /**
   * A 64-bit float value.
   */
  AM_VAL_TYPE_F64 = (1 << 8),
  /**
   * A 64-bit signed integer value.
   */
  AM_VAL_TYPE_INT = (1 << 9),
  /**
   * A mark.
   */
  AM_VAL_TYPE_MARK = (1 << 10),
  /**
   * A null value.
   */
  AM_VAL_TYPE_NULL = (1 << 11),
  /**
   * An object type value.
   */
  AM_VAL_TYPE_OBJ_TYPE = (1 << 12),
  /**
   * A UTF-8 string view value.
   */
  AM_VAL_TYPE_STR = (1 << 13),
  /**
   * A synchronization have value.
   */
  AM_VAL_TYPE_SYNC_HAVE = (1 << 14),
  /**
   * A synchronization message value.
   */
  AM_VAL_TYPE_SYNC_MESSAGE = (1 << 15),
  /**
   * A synchronization state value.
   */
  AM_VAL_TYPE_SYNC_STATE = (1 << 16),
  /**
   * A *nix timestamp (milliseconds) value.
   */
  AM_VAL_TYPE_TIMESTAMP = (1 << 17),
  /**
   * A 64-bit unsigned integer value.
   */
  AM_VAL_TYPE_UINT = (1 << 18),
  /**
   * An unknown type of value.
   */
  AM_VAL_TYPE_UNKNOWN = (1 << 19),
  /**
   * A void.
   */
  AM_VAL_TYPE_VOID = (1 << 0),
};
typedef uint32_t AMvalType;

/**
 * \struct AMactorId
 * \installed_headerfile
 * \brief An actor's unique identifier.
 */
typedef struct AMactorId AMactorId;

/**
 * \struct AMchange
 * \installed_headerfile
 * \brief A group of operations performed by an actor.
 */
typedef struct AMchange AMchange;

/**
 * \struct AMdoc
 * \installed_headerfile
 * \brief A JSON-like CRDT.
 */
typedef struct AMdoc AMdoc;

/**
 * \struct AMitem
 * \installed_headerfile
 * \brief An item within a result.
 */
typedef struct AMitem AMitem;

typedef struct AMmark AMmark;

/**
 * \struct AMobjId
 * \installed_headerfile
 * \brief An object's unique identifier.
 */
typedef struct AMobjId AMobjId;

/**
 * \struct AMresult
 * \installed_headerfile
 * \brief A discriminated union of result variants.
 */
typedef struct AMresult AMresult;

/**
 * \struct AMsyncHave
 * \installed_headerfile
 * \brief A summary of the changes that the sender of a synchronization
 *        message already has.
 */
typedef struct AMsyncHave AMsyncHave;

/**
 * \struct AMsyncMessage
 * \installed_headerfile
 * \brief A synchronization message for a peer.
 */
typedef struct AMsyncMessage AMsyncMessage;

/**
 * \struct AMsyncState
 * \installed_headerfile
 * \brief The state of synchronization with a peer.
 */
typedef struct AMsyncState AMsyncState;

/**
 * \struct AMbyteSpan
 * \installed_headerfile
 * \brief A view onto an array of bytes.
 */
typedef struct AMbyteSpan {
  /**
   * A pointer to the first byte of an array of bytes.
   * \warning \p src is only valid until the array of bytes to which it
   *          points is freed.
   * \note If the `AMbyteSpan` came from within an `AMitem` struct then
   *       \p src will be freed when the pointer to the `AMresult` struct
   *       containing the `AMitem` struct is passed to `AMresultFree()`.
   */
  const uint8_t *src;
  /**
   * The count of bytes in the array.
   */
  size_t count;
} AMbyteSpan;

/**
 * \struct AMitems
 * \installed_headerfile
 * \brief A random-access iterator over a sequence of `AMitem` structs.
 */
typedef struct AMitems {
  /**
   * An implementation detail that is intentionally opaque.
   * \warning Modifying \p detail will cause undefined behavior.
   * \note The actual size of \p detail will vary by platform, this is just
   *       the one for the platform this documentation was built on.
   */
  uint8_t detail[+8+8+8];
} AMitems;

/**
 * \struct AMunknownValue
 * \installed_headerfile
 * \brief A value (typically for a `set` operation) whose type is unknown.
 */
typedef struct AMunknownValue {
  /**
   * The value's raw bytes.
   */
  struct AMbyteSpan bytes;
  /**
   * The value's encoded type identifier.
   */
  uint8_t type_code;
} AMunknownValue;



/**
 * \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
 */
struct AMbyteSpan AMactorIdBytes(const struct AMactorId *actor_id);

/**
 * \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
 */
int AMactorIdCmp(const struct AMactorId *actor_id1, const struct AMactorId *actor_id2);

/**
 * \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.
 */
struct AMresult *AMactorIdInit(void);

/**
 * \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`
 */
struct AMresult *AMactorIdFromBytes(const uint8_t *src, size_t count);

/**
 * \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
 */
struct AMresult *AMactorIdFromStr(struct AMbyteSpan value);

/**
 * \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
 */
struct AMbyteSpan AMactorIdStr(const struct AMactorId *actor_id);

/**
 * \memberof AMbyteSpan
 * \brief Creates a view onto an array of bytes.
 *
 * \param[in] src A pointer to an array of bytes or `NULL`.
 * \param[in] count The count of bytes to view from the array pointed to by
 *                  \p src.
 * \return An `AMbyteSpan` struct.
 * \pre \p count `<= sizeof(`\p src `)`
 * \post `(`\p src `== NULL) -> (AMbyteSpan){NULL, 0}`
 * \internal
 *
 * #Safety
 * src must be a byte array of length `>= count` or `std::ptr::null()`
 */
struct AMbyteSpan AMbytes(const uint8_t *src, size_t count);

/**
 * \memberof AMbyteSpan
 * \brief Creates a view onto a C string.
 *
 * \param[in] c_str A null-terminated byte string or `NULL`.
 * \return An `AMbyteSpan` struct.
 * \pre Each byte in \p c_str encodes one UTF-8 character.
 * \internal
 *
 * #Safety
 * c_str must be a null-terminated array of `std::os::raw::c_char` or `std::ptr::null()`.
 */
struct AMbyteSpan AMstr(const char *c_str);

/**
 * \memberof AMbyteSpan
 * \brief Compares two UTF-8 string views lexicographically.
 *
 * \param[in] lhs A UTF-8 string view as an `AMbyteSpan` struct.
 * \param[in] rhs A UTF-8 string view as an `AMbyteSpan` struct.
 * \return Negative value if \p lhs appears before \p rhs in lexicographical order.
 *         Zero if \p lhs and \p rhs compare equal.
 *         Positive value if \p lhs appears after \p rhs in lexicographical order.
 * \pre \p lhs.src `!= NULL`
 * \pre \p lhs.count `<= sizeof(`\p lhs.src `)`
 * \pre \p rhs.src `!= NULL`
 * \pre \p rhs.count `<= sizeof(`\p rhs.src `)`
 * \internal
 *
 * #Safety
 * lhs.src must be a byte array of length >= lhs.count
 * rhs.src must be a a byte array of length >= rhs.count
 */
int AMstrCmp(struct AMbyteSpan lhs, struct AMbyteSpan rhs);

/**
 * \memberof AMchange
 * \brief Gets the first referenced actor identifier in a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_ACTOR_ID` item.
 * \pre \p change `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMresult *AMchangeActorId(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Compresses the raw bytes of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
void AMchangeCompress(struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the dependencies of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p change `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMresult *AMchangeDeps(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the extra bytes of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return An `AMbyteSpan` struct.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMbyteSpan AMchangeExtraBytes(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Allocates a new change 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 load from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_CHANGE` 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`
 */
struct AMresult *AMchangeFromBytes(const uint8_t *src, size_t count);

/**
 * \memberof AMchange
 * \brief Gets the hash of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return An `AMbyteSpan` struct for a change hash.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMbyteSpan AMchangeHash(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Tests the emptiness of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return `true` if \p change is empty, `false` otherwise.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
bool AMchangeIsEmpty(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Loads a document into a sequence of changes.
 *
 * \param[in] src A pointer to an array of bytes.
 * \param[in] count The count of bytes to load from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE` items.
 * \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`
 */
struct AMresult *AMchangeLoadDocument(const uint8_t *src, size_t count);

/**
 * \memberof AMchange
 * \brief Gets the maximum operation index of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
uint64_t AMchangeMaxOp(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the message of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A UTF-8 string view as an `AMbyteSpan` struct.
 * \pre \p change `!= NULL`
 * \post `(`\p change `== NULL) -> (AMbyteSpan){NULL, 0}`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMbyteSpan AMchangeMessage(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the index of a change in the changes from an actor.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
uint64_t AMchangeSeq(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the size of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
size_t AMchangeSize(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the start operation index of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
uint64_t AMchangeStartOp(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the commit time of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return A 64-bit signed integer.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
int64_t AMchangeTime(const struct AMchange *change);

/**
 * \memberof AMchange
 * \brief Gets the raw bytes of a change.
 *
 * \param[in] change A pointer to an `AMchange` struct.
 * \return An `AMbyteSpan` struct for an array of bytes.
 * \pre \p change `!= NULL`
 * \internal
 *
 * # Safety
 * change must be a valid pointer to an AMchange
 */
struct AMbyteSpan AMchangeRawBytes(const struct AMchange *change);

/**
 * \memberof AMdoc
 * \brief Applies a sequence of changes to a document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] items A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE`
 *                  items.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p items `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * items must be a valid pointer to an AMitems.
 */
struct AMresult *AMapplyChanges(struct AMdoc *doc, const struct AMitems *items);

/**
 * \memberof AMdoc
 * \brief Allocates storage for a document and initializes it by duplicating
 *        the given document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_DOC` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMclone(const struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Allocates a new document and initializes it with defaults.
 *
 * \param[in] actor_id A pointer to an `AMactorId` struct or `NULL` for a
 *                     random one.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_DOC` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * actor_id must be a valid pointer to an AMactorId or std::ptr::null()
 */
struct AMresult *AMcreate(const struct AMactorId *actor_id);

/**
 * \memberof AMdoc
 * \brief Commits the current operations on a document with an optional
 *        message and/or *nix timestamp (milliseconds).
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] message A UTF-8 string view as an `AMbyteSpan` struct.
 * \param[in] timestamp A pointer to a 64-bit integer or `NULL`.
 * \return A pointer to an `AMresult` struct with one `AM_VAL_TYPE_CHANGE_HASH`
 *         item if there were operations to commit or an `AM_VAL_TYPE_VOID` item
 *         if there were no operations to commit.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMcommit(struct AMdoc *doc, struct AMbyteSpan message, const int64_t *timestamp);

/**
 * \memberof AMdoc
 * \brief Creates an empty change with an optional message and/or *nix
 *        timestamp (milliseconds).
 *
 * \details This is useful if you wish to create a "merge commit" which has as
 *          its dependents the current heads of the document but you don't have
 *          any operations to add to the document.
 *
 * \note If there are outstanding uncommitted changes to the document
 *       then two changes will be created: one for creating the outstanding
 *       changes and one for the empty change. The empty change will always be
 *       the latest change in the document after this call and the returned
 *       hash will be the hash of that empty change.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] message A UTF-8 string view as an `AMbyteSpan` struct.
 * \param[in] timestamp A pointer to a 64-bit integer or `NULL`.
 * \return A pointer to an `AMresult` struct with one `AM_VAL_TYPE_CHANGE_HASH`
 *         item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMemptyChange(struct AMdoc *doc, struct AMbyteSpan message, const int64_t *timestamp);

/**
 * \memberof AMdoc
 * \brief Tests the equality of two documents after closing their respective
 *        transactions.
 *
 * \param[in] doc1 A pointer to an `AMdoc` struct.
 * \param[in] doc2 A pointer to an `AMdoc` struct.
 * \return `true` if \p doc1 `==` \p doc2 and `false` otherwise.
 * \pre \p doc1 `!= NULL`
 * \pre \p doc2 `!= NULL`
 * \internal
 *
 * #Safety
 * doc1 must be a valid pointer to an AMdoc
 * doc2 must be a valid pointer to an AMdoc
 */
bool AMequal(struct AMdoc *doc1, struct AMdoc *doc2);

/**
 * \memberof AMdoc
 * \brief Forks this document at its current or a historical point for use by
 *        a different actor.
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical point or `NULL` to select its
 *                  current point.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMfork(struct AMdoc *doc, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Generates a synchronization message for a peer based upon the given
 *        synchronization state.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \return A pointer to an `AMresult` struct with either an
 *         `AM_VAL_TYPE_SYNC_MESSAGE` or `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p sync_state `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * sync_state must be a valid pointer to an AMsyncState
 */
struct AMresult *AMgenerateSyncMessage(struct AMdoc *doc, struct AMsyncState *sync_state);

/**
 * \memberof AMdoc
 * \brief Gets a document's actor identifier.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_ACTOR_ID` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMgetActorId(const struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Gets the change added to a document by its respective hash.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \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_CHANGE` item.
 * \pre \p doc `!= NULL`
 * \pre \p src `!= NULL`
 * \pre `sizeof(`\p src') >= AM_CHANGE_HASH_SIZE`
 * \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
 * doc must be a valid pointer to an AMdoc
 * src must be a byte array of length `>= automerge::types::HASH_SIZE`
 */
struct AMresult *AMgetChangeByHash(struct AMdoc *doc, const uint8_t *src, size_t count);

/**
 * \memberof AMdoc
 * \brief Gets the changes added to a document by their respective hashes.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] have_deps A pointer to an `AMitems` struct with
 *                      `AM_VAL_TYPE_CHANGE_HASH` items or `NULL`.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE` items.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMgetChanges(struct AMdoc *doc, const struct AMitems *have_deps);

/**
 * \memberof AMdoc
 * \brief Gets the changes added to a second document that weren't added to
 *        a first document.
 *
 * \param[in] doc1 A pointer to an `AMdoc` struct.
 * \param[in] doc2 A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE` items.
 * \pre \p doc1 `!= NULL`
 * \pre \p doc2 `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc1 must be a valid pointer to an AMdoc
 * doc2 must be a valid pointer to an AMdoc
 */
struct AMresult *AMgetChangesAdded(struct AMdoc *doc1, struct AMdoc *doc2);

/**
 * \memberof AMdoc
 * \brief Gets the current heads of a document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMgetHeads(struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Gets the hashes of the changes in a document that aren't transitive
 *        dependencies of the given hashes of changes.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items or `NULL`.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMgetMissingDeps(struct AMdoc *doc, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Gets the last change made to a document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct containing either an
 *         `AM_VAL_TYPE_CHANGE` or `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMgetLastLocalChange(struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical keys of a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select historical keys or `NULL` to select current
 *                  keys.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_STR` items.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMkeys(const struct AMdoc *doc, const struct AMobjId *obj_id, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Allocates storage for a document and initializes it with the compact
 *        form of an incremental save.
 *
 * \param[in] src A pointer to an array of bytes.
 * \param[in] count The count of bytes to load from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_DOC` 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`
 */
struct AMresult *AMload(const uint8_t *src, size_t count);

/**
 * \memberof AMdoc
 * \brief Loads the compact form of an incremental save into a document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] src A pointer to an array of bytes.
 * \param[in] count The count of bytes to load from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_UINT` item.
 * \pre \p doc `!= NULL`
 * \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
 * doc must be a valid pointer to an AMdoc
 * src must be a byte array of length `>= count`
 */
struct AMresult *AMloadIncremental(struct AMdoc *doc, const uint8_t *src, size_t count);

/**
 * \memberof AMdoc
 * \brief Applies all of the changes in \p src which are not in \p dest to
 *        \p dest.
 *
 * \param[in] dest A pointer to an `AMdoc` struct.
 * \param[in] src A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p dest `!= NULL`
 * \pre \p src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * dest must be a valid pointer to an AMdoc
 * src must be a valid pointer to an AMdoc
 */
struct AMresult *AMmerge(struct AMdoc *dest, struct AMdoc *src);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical size of an object.
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical size or `NULL` to select its
 *                  current size.
 * \return The count of items in the object identified by \p obj_id.
 *         For an `AM_OBJ_TYPE_TEXT` object, if `AUTOMERGE_C_UTF8` is defined
 *         then the items are bytes but if `AUTOMERGE_C_UTF32` is defined then
 *         the items are Unicode code points.
 * \pre \p doc `!= NULL`
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
size_t AMobjSize(const struct AMdoc *doc, const struct AMobjId *obj_id, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Gets the type of an object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \return An `AMobjType` tag or `0`.
 * \pre \p doc `!= NULL`
 * \pre \p obj_id `!= NULL`
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
AMobjType AMobjObjType(const struct AMdoc *doc, const struct AMobjId *obj_id);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical items of an entire object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select its historical items or `NULL` to select
 *                  its current items.
 * \return A pointer to an `AMresult` struct with an `AMitems` struct.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMobjItems(const struct AMdoc *doc, const struct AMobjId *obj_id, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Gets the number of pending operations added during a document's
 *        current transaction.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return The count of pending operations for \p doc.
 * \pre \p doc `!= NULL`
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
size_t AMpendingOps(const struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Receives a synchronization message from a peer based upon a given
 *        synchronization state.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p sync_state `!= NULL`
 * \pre \p sync_message `!= NULL`
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * sync_state must be a valid pointer to an AMsyncState
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMreceiveSyncMessage(struct AMdoc *doc, struct AMsyncState *sync_state, const struct AMsyncMessage *sync_message);

/**
 * \memberof AMdoc
 * \brief Cancels the pending operations added during a document's current
 *        transaction and gets the number of cancellations.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return The count of pending operations for \p doc that were cancelled.
 * \pre \p doc `!= NULL`
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
size_t AMrollback(struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Saves the entirety of a document into a compact form.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_BYTES` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMsave(struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Saves the changes to a document since its last save into a compact
 *        form.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_BYTES` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 */
struct AMresult *AMsaveIncremental(struct AMdoc *doc);

/**
 * \memberof AMdoc
 * \brief Puts the actor identifier of a document.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] actor_id A pointer to an `AMactorId` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p actor_id `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * actor_id must be a valid pointer to an AMactorId
 */
struct AMresult *AMsetActorId(struct AMdoc *doc, const struct AMactorId *actor_id);

/**
 * \memberof AMdoc
 * \brief Splices values into and/or removes values from the identified object
 *        at a given position within it.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos A position in the object identified by \p obj_id or
 *                `SIZE_MAX` to indicate one past its end.
 * \param[in] del The number of values to delete. If \p del `> 0` then
 *                deletion begins at \p pos but if \p del `< 0` then deletion
 *                ends at \p pos.
 * \param[in] values A copy of an `AMitems` struct from which values will be
 *                   spliced <b>starting at its current position</b>; call
 *                   `AMitemsRewound()` on a used `AMitems` first to ensure
 *                   that all of its values are spliced in. Pass `(AMitems){0}`
 *                   when zero values should be spliced in.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \pre `-AMobjSize(`\p obj_id `) <=` \p del `<= AMobjSize(`\p obj_id `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * values must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMsplice(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, ptrdiff_t del, struct AMitems values);

/**
 * \memberof AMdoc
 * \brief Splices characters into and/or removes characters from the
 *        identified object at a given position within it.
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos A position in the text object identified by \p obj_id or
 *                `SIZE_MAX` to indicate one past its end.
 *                If `AUTOMERGE_C_UTF8` is defined then \p pos is in units of
 *                bytes but if `AUTOMERGE_C_UTF32` is defined then \p pos is in
 *                units of Unicode code points.
 * \param[in] del The number of characters to delete. If \p del `> 0` then
 *                deletion begins at \p pos but if \p del `< 0` then deletion
 *                ends at \p pos.
 *                If `AUTOMERGE_C_UTF8` is defined then \p del is in units of
 *                bytes but if `AUTOMERGE_C_UTF32` is defined then \p del is in
 *                units of Unicode code points.
 * \param[in] text A UTF-8 string view as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \pre `-AMobjSize(`\p obj_id `) <=` \p del `<= AMobjSize(`\p obj_id `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMspliceText(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, ptrdiff_t del, struct AMbyteSpan text);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical string represented by a text object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] heads A pointer to an `AMitems` struct containing
 *                  `AM_VAL_TYPE_CHANGE_HASH` items to select a historical string
 *                  or `NULL` to select the current string.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_STR` item.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMtext(const struct AMdoc *doc, const struct AMobjId *obj_id, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Deletes an item from a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistDelete(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos);

/**
 * \memberof AMdoc
 * \brief Gets a current or historical item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical item at \p pos or `NULL`
 *                  to select the current item at \p pos.
 * \return A pointer to an `AMresult` struct with an `AMitem` struct.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMlistGet(const struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Gets all of the historical items at a position within a list object
 *        until its current one or a specific one.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical last item or `NULL` to select
 *                  the current last item.
 * \return A pointer to an `AMresult` struct with an `AMitems` struct.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMlistGetAll(const struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Increments a counter value in an item within a list object by the
 *        given value.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistIncrement(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts a boolean value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A boolean.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutBool(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, bool value);

/**
 * \memberof AMdoc
 * \brief Puts an array of bytes value at a position within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A view onto the array of bytes to copy from as an
 *                  `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \pre \p value.src `!= NULL`
 * \pre `0 <` \p value.count `<= sizeof(`\p value.src `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * value.src must be a byte array of length >= value.count
 */
struct AMresult *AMlistPutBytes(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, struct AMbyteSpan value);

/**
 * \memberof AMdoc
 * \brief Puts a CRDT counter value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutCounter(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts a float value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A 64-bit float.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutF64(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, double value);

/**
 * \memberof AMdoc
 * \brief Puts a signed integer value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutInt(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts a null value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutNull(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert);

/**
 * \memberof AMdoc
 * \brief Puts an empty object value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] obj_type An `AMobjIdType` enum tag.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_OBJ_TYPE` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutObject(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, AMobjType obj_type);

/**
 * \memberof AMdoc
 * \brief Puts a UTF-8 string value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A UTF-8 string view as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \pre \p value.src `!= NULL`
 * \pre `0 <` \p value.count `<= sizeof(`\p value.src `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * value.src must be a byte array of length >= value.count
 */
struct AMresult *AMlistPutStr(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, struct AMbyteSpan value);

/**
 * \memberof AMdoc
 * \brief Puts a *nix timestamp (milliseconds) value into an item within a
 *        list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutTimestamp(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts an unsigned integer value into an item within a list object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] pos The position of an item within the list object identified by
 *                \p obj_id or `SIZE_MAX` to indicate its last item if
 *                \p insert `== false` or one past its last item if
 *                \p insert `== true`.
 * \param[in] insert A flag for inserting a new item for \p value before
 *                   \p pos instead of putting \p value into the item at
 *                   \p pos.
 * \param[in] value A 64-bit unsigned integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre `0 <=` \p pos `<= AMobjSize(`\p obj_id `)` or \p pos `== SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 */
struct AMresult *AMlistPutUint(struct AMdoc *doc, const struct AMobjId *obj_id, size_t pos, bool insert, uint64_t value);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical items in the list object within the
 *        given range.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] begin The first pos in a range of indices.
 * \param[in] end At least one past the last pos in a range of indices.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select historical items or `NULL` to select
 *                  current items.
 * \return A pointer to an `AMresult` struct with an `AMitems` struct.
 * \pre \p doc `!= NULL`
 * \pre \p begin `<=` \p end `<= SIZE_MAX`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMlistRange(const struct AMdoc *doc, const struct AMobjId *obj_id, size_t begin, size_t end, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Deletes an item from a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapDelete(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key);

/**
 * \memberof AMdoc
 * \brief Gets a current or historical item within a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical item at \p key or `NULL`
 *                  to select the current item at \p key.
 * \return A pointer to an `AMresult` struct with an `AMitem` struct.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMmapGet(const struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Gets all of the historical items at a key within a map object until
 *        its current one or a specific one.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select a historical last item or `NULL` to
 *                  select the current last item.
 * \return A pointer to an `AMresult` struct with an `AMItems` struct.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMmapGetAll(const struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Increments a counter at a key in a map object by the given value.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapIncrement(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts a boolean as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A boolean.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutBool(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, bool value);

/**
 * \memberof AMdoc
 * \brief Puts an array of bytes value at a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key The UTF-8 string view key of an item within the map object
 *                identified by \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A view onto an array of bytes as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \pre \p value.src `!= NULL`
 * \pre `0 <` \p value.count `<= sizeof(`\p value.src `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 * value.src must be a byte array of length >= value.count
 */
struct AMresult *AMmapPutBytes(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, struct AMbyteSpan value);

/**
 * \memberof AMdoc
 * \brief Puts a CRDT counter as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutCounter(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts null as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutNull(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key);

/**
 * \memberof AMdoc
 * \brief Puts an empty object as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] obj_type An `AMobjIdType` enum tag.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_OBJ_TYPE` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutObject(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, AMobjType obj_type);

/**
 * \memberof AMdoc
 * \brief Puts a float as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit float.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutF64(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, double value);

/**
 * \memberof AMdoc
 * \brief Puts a signed integer as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutInt(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts a UTF-8 string as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A UTF-8 string view as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutStr(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, struct AMbyteSpan value);

/**
 * \memberof AMdoc
 * \brief Puts a *nix timestamp (milliseconds) as the value of a key in a map
 *        object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutTimestamp(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, int64_t value);

/**
 * \memberof AMdoc
 * \brief Puts an unsigned integer as the value of a key in a map object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] key A UTF-8 string view key for the map object identified by
 *                \p obj_id as an `AMbyteSpan` struct.
 * \param[in] value A 64-bit unsigned integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p key.src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * key.src must be a byte array of length >= key.count
 */
struct AMresult *AMmapPutUint(struct AMdoc *doc, const struct AMobjId *obj_id, struct AMbyteSpan key, uint64_t value);

/**
 * \memberof AMdoc
 * \brief Gets the current or historical items of the map object within the
 *        given range.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] begin The first key in a subrange or `AMstr(NULL)` to indicate the
 *                  absolute first key.
 * \param[in] end The key one past the last key in a subrange or `AMstr(NULL)`
 *                to indicate one past the absolute last key.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items to select historical items or `NULL` to select
 *                  current items.
 * \return A pointer to an `AMresult` struct with an `AMitems` struct.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * begin.src must be a byte array of length >= begin.count or std::ptr::null()
 * end.src must be a byte array of length >= end.count or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMmapRange(const struct AMdoc *doc,
                            const struct AMobjId *obj_id,
                            struct AMbyteSpan begin,
                            struct AMbyteSpan end,
                            const struct AMitems *heads);

/**
 * \memberof AMmark
 * \brief Gets the name of a mark.
 *
 * \param[in] mark A pointer to an `AMmark` struct.
 * \return A UTF-8 string view as an `AMbyteSpan` struct.
 * \pre \p mark `!= NULL`
 * \post `(`\p mark `== NULL) -> (AMbyteSpan){NULL, 0}`
 * \internal
 *
 * # Safety
 * mark must be a valid pointer to an AMmark
 */
struct AMbyteSpan AMmarkName(const struct AMmark *mark);

/**
 * \memberof AMmark
 * \brief Gets the value of a mark.
 *
 * \param[in] mark A pointer to an `AMmark` struct.
 * \return A pointer to an `AMresult` struct with an `AMitem` struct.
 * \pre \p mark `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * mark must be a valid pointer to an AMmark
 */
struct AMresult *AMmarkValue(const struct AMmark *mark);

/**
 * \memberof AMmark
 * \brief Gets the start offset of a mark.
 *
 * \param[in] mark A pointer to an `AMmark` struct.
 * \return The offset at which the mark starts.
 * \pre \p mark `!= NULL`
 * \post `(`\p mark `== NULL) -> 0`
 * \internal
 *
 * # Safety
 * mark must be a valid pointer to an AMmark
 */
size_t AMmarkStart(const struct AMmark *mark);

/**
 * \memberof AMmark
 * \brief Gets the end offset of a mark.
 *
 * \param[in] mark A pointer to an `AMmark` struct.
 * \return The offset at which the mark ends.
 * \pre \p mark `!= NULL`
 * \post `(`\p mark `== NULL) -> SIZE_MAX`
 * \internal
 *
 * # Safety
 * mark must be a valid pointer to an AMmark
 */
size_t AMmarkEnd(const struct AMmark *mark);

/**
 * \memberof AMdoc
 * \brief Gets the marks associated with an object.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] heads A pointer to an `AMitems` struct with `AM_VAL_TYPE_CHANGE_HASH`
 *                  items or `NULL`.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_MARK` items.
 * \pre \p doc `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * heads must be a valid pointer to an AMitems or std::ptr::null()
 */
struct AMresult *AMmarks(const struct AMdoc *doc, const struct AMobjId *obj_id, const struct AMitems *heads);

/**
 * \memberof AMdoc
 * \brief Creates a mark.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] start The start offset of the mark.
 * \param[in] end The end offset of the mark.
 * \param[in] expand The mode of expanding the mark to include text inserted at
 *                   one of its offsets.
 * \param[in] name A UTF-8 string view as an `AMbyteSpan`struct.
 * \param[in] value A pointer to an `AMitem` struct with an `AM_VAL_TYPE_MARK`.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p start `<` \p end
 * \pre \p name.src `!= NULL`
 * \pre \p name.count `<= sizeof(`\p name.src `)`
 * \pre \p value `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * name.src must be a byte array of length >= name.count
 * value must be a valid pointer to an AMitem
 */
struct AMresult *AMmarkCreate(struct AMdoc *doc,
                              const struct AMobjId *obj_id,
                              size_t start,
                              size_t end,
                              AMmarkExpand expand,
                              struct AMbyteSpan name,
                              const struct AMitem *value);

/**
 * \memberof AMdoc
 * \brief Clears a mark.
 *
 * \param[in] doc A pointer to an `AMdoc` struct.
 * \param[in] obj_id A pointer to an `AMobjId` struct or `AM_ROOT`.
 * \param[in] start The start offset of the mark.
 * \param[in] end The end offset of the mark.
 * \param[in] expand The mode of expanding the mark to include text inserted at
 *                   one of its offsets.
 * \param[in] name A UTF-8 string view s an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_VOID` item.
 * \pre \p doc `!= NULL`
 * \pre \p start `<` \p end
 * \pre \p name.src `!= NULL`
 * \pre \p name.count `<= sizeof(`\p name.src `)`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * doc must be a valid pointer to an AMdoc
 * obj_id must be a valid pointer to an AMobjId or std::ptr::null()
 * name.src must be a byte array of length >= name.count
 */
struct AMresult *AMmarkClear(struct AMdoc *doc,
                             const struct AMobjId *obj_id,
                             size_t start,
                             size_t end,
                             AMmarkExpand expand,
                             struct AMbyteSpan name);

/**
 * \memberof AMitem
 * \brief Tests the equality of two items.
 *
 * \param[in] item1 A pointer to an `AMitem` struct.
 * \param[in] item2 A pointer to an `AMitem` struct.
 * \return `true` if \p item1 `==` \p item2 and `false` otherwise.
 * \pre \p item1 `!= NULL`
 * \pre \p item2 `!= NULL`
 * \post `!(`\p item1 `&&` \p item2 `) -> false`
 * \internal
 *
 * #Safety
 * item1 must be a valid AMitem pointer
 * item2 must be a valid AMitem pointer
 */
bool AMitemEqual(const struct AMitem *item1, const struct AMitem *item2);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a boolean value.
 *
 * \param[in] value A boolean.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_BOOL` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromBool(bool value);

/**
 * \memberof AMitem
 * \brief Allocates a new item 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_BYTES` 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
 * value.src must be a byte array of length >= value.count
 */
struct AMresult *AMitemFromBytes(const uint8_t *src, size_t count);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a change hash value.
 *
 * \param[in] value A change hash as an `AMbyteSpan` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_CHANGE_HASH` item.
 * \pre \p value.src `!= NULL`
 * \pre `0 <` \p value.count `<= sizeof(`\p value.src `)`
 * \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
 */
struct AMresult *AMitemFromChangeHash(struct AMbyteSpan value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a CRDT counter value.
 *
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_COUNTER` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromCounter(int64_t value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a float value.
 *
 * \param[in] value A 64-bit float.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_F64` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromF64(double value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a signed integer value.
 *
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_INT` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromInt(int64_t value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a null value.
 *
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_NULL` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromNull(void);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a UTF-8 string 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_STR` item.
 * \pre \p value.src `!= NULL`
 * \pre `0 <` \p value.count `<= sizeof(`\p value.src `)`
 * \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
 */
struct AMresult *AMitemFromStr(struct AMbyteSpan value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from a *nix timestamp
 *        (milliseconds) value.
 *
 * \param[in] value A 64-bit signed integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_TIMESTAMP` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromTimestamp(int64_t value);

/**
 * \memberof AMitem
 * \brief Allocates a new item and initializes it from an unsigned integer value.
 *
 * \param[in] value A 64-bit unsigned integer.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_UINT` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMitemFromUint(uint64_t value);

/**
 * \memberof AMitem
 * \brief Gets the type of an item's index.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \return An `AMidxType` enum tag.
 * \pre \p item `!= NULL`
 * \post `(`\p item `== NULL) -> 0`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
AMidxType AMitemIdxType(const struct AMitem *item);

/**
 * \memberof AMitem
 * \brief Gets the object identifier of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \return A pointer to an `AMobjId` struct.
 * \pre \p item `!= NULL`
 * \post `(`\p item `== NULL) -> NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
const struct AMobjId *AMitemObjId(const struct AMitem *item);

/**
 * \memberof AMitem
 * \brief Gets the UTF-8 string view key index of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a UTF-8 string view as an `AMbyteSpan` struct.
 * \return `true` if `AMitemIdxType(`\p item `) == AM_IDX_TYPE_KEY` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemKey(const struct AMitem *item, struct AMbyteSpan *value);

/**
 * \memberof AMitem
 * \brief Gets the unsigned integer position index of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a `size_t`.
 * \return `true` if `AMitemIdxType(`\p item `) == AM_IDX_TYPE_POS` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemPos(const struct AMitem *item, size_t *value);

/**
 * \memberof AMitem
 * \brief Gets the reference count of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p item `!= NULL`
 * \post `(`\p item `== NULL) -> 0`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
size_t AMitemRefCount(const struct AMitem *item);

/**
 * \memberof AMitem
 * \brief Gets a new result for an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \return A pointer to an `AMresult` struct.
 * \pre \p item `!= NULL`
 * \post `(`\p item `== NULL) -> NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
struct AMresult *AMitemResult(const struct AMitem *item);

/**
 * \memberof AMitem
 * \brief Gets the actor identifier value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMactorId` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_ACTOR_ID` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToActorId(const struct AMitem *item, const struct AMactorId **value);

/**
 * \memberof AMitem
 * \brief Gets the boolean value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a boolean.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_BOOL` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToBool(const struct AMitem *item, bool *value);

/**
 * \memberof AMitem
 * \brief Gets the array of bytes value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMbyteSpan` struct.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_BYTES` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToBytes(const struct AMitem *item, struct AMbyteSpan *value);

/**
 * \memberof AMitem
 * \brief Gets the change value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMchange` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_CHANGE` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToChange(struct AMitem *item, struct AMchange **value);

/**
 * \memberof AMitem
 * \brief Gets the change hash value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMbyteSpan` struct.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_CHANGE_HASH` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToChangeHash(const struct AMitem *item, struct AMbyteSpan *value);

/**
 * \memberof AMitem
 * \brief Gets the CRDT counter value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a signed 64-bit integer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_COUNTER` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToCounter(const struct AMitem *item, int64_t *value);

/**
 * \memberof AMitem
 * \brief Gets the document value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMdoc` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_DOC` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToDoc(struct AMitem *item, const struct AMdoc **value);

/**
 * \memberof AMitem
 * \brief Gets the float value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a 64-bit float.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_F64` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToF64(const struct AMitem *item, double *value);

/**
 * \memberof AMitem
 * \brief Gets the integer value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a signed 64-bit integer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_INT` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToInt(const struct AMitem *item, int64_t *value);

/**
 * \memberof AMitem
 * \brief Gets the mark value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMmark` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_MARK` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToMark(const struct AMitem *item, const struct AMmark **value);

/**
 * \memberof AMitem
 * \brief Gets the UTF-8 string view value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a UTF-8 string view as an `AMbyteSpan` struct.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_STR` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToStr(const struct AMitem *item, struct AMbyteSpan *value);

/**
 * \memberof AMitem
 * \brief Gets the synchronization have value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMsyncHave` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_SYNC_HAVE` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToSyncHave(const struct AMitem *item, const struct AMsyncHave **value);

/**
 * \memberof AMitem
 * \brief Gets the synchronization message value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMsyncMessage` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_SYNC_MESSAGE` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToSyncMessage(const struct AMitem *item, const struct AMsyncMessage **value);

/**
 * \memberof AMitem
 * \brief Gets the synchronization state value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMsyncState` struct pointer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_SYNC_STATE` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToSyncState(struct AMitem *item, struct AMsyncState **value);

/**
 * \memberof AMitem
 * \brief Gets the *nix timestamp (milliseconds) value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a signed 64-bit integer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_TIMESTAMP` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToTimestamp(const struct AMitem *item, int64_t *value);

/**
 * \memberof AMitem
 * \brief Gets the unsigned integer value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to a unsigned 64-bit integer.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_UINT` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToUint(const struct AMitem *item, uint64_t *value);

/**
 * \memberof AMitem
 * \brief Gets the unknown type of value of an item.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \param[out] value A pointer to an `AMunknownValue` struct.
 * \return `true` if `AMitemValType(`\p item `) == AM_VAL_TYPE_UNKNOWN` and
 *         \p *value has been reassigned, `false` otherwise.
 * \pre \p item `!= NULL`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
bool AMitemToUnknown(const struct AMitem *item, struct AMunknownValue *value);

/**
 * \memberof AMitem
 * \brief Gets the type of an item's value.
 *
 * \param[in] item A pointer to an `AMitem` struct.
 * \return An `AMvalType` enum tag.
 * \pre \p item `!= NULL`
 * \post `(`\p item `== NULL) -> 0`
 * \internal
 *
 * # Safety
 * item must be a valid pointer to an AMitem
 */
AMvalType AMitemValType(const struct AMitem *item);

/**
 * \memberof AMitems
 * \brief Advances an iterator over a sequence of object items by at most
 *        \p |n| positions where the sign of \p n is relative to the
 *        iterator's direction.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \param[in] n The direction (\p -n -> opposite, \p n -> same) and maximum
 *              number of positions to advance.
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
void AMitemsAdvance(struct AMitems *items, ptrdiff_t n);

/**
 * \memberof AMitems
 * \brief Tests the equality of two sequences of object items underlying a
 *        pair of iterators.
 *
 * \param[in] items1 A pointer to an `AMitems` struct.
 * \param[in] items2 A pointer to an `AMitems` struct.
 * \return `true` if \p items1 `==` \p items2 and `false` otherwise.
 * \pre \p items1 `!= NULL`
 * \pre \p items1 `!= NULL`
 * \post `!(`\p items1 `&&` \p items2 `) -> false`
 * \internal
 *
 * #Safety
 * items1 must be a valid pointer to an AMitems
 * items2 must be a valid pointer to an AMitems
 */
bool AMitemsEqual(const struct AMitems *items1, const struct AMitems *items2);

/**
 * \memberof AMitems
 * \brief Gets the object item at the current position of an iterator over a
 *        sequence of object items and then advances it by at most \p |n|
 *        positions where the sign of \p n is relative to the iterator's
 *        direction.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \param[in] n The direction (\p -n -> opposite, \p n -> same) and maximum
 *              number of positions to advance.
 * \return A pointer to an `AMitem` struct that's `NULL` when \p items
 *         was previously advanced past its forward/reverse limit.
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
struct AMitem *AMitemsNext(struct AMitems *items, ptrdiff_t n);

/**
 * \memberof AMitems
 * \brief Advances an iterator over a sequence of object items by at most
 *        \p |n| positions where the sign of \p n is relative to the
 *        iterator's direction and then gets the object item at its new
 *        position.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \param[in] n The direction (\p -n -> opposite, \p n -> same) and maximum
 *              number of positions to advance.
 * \return A pointer to an `AMitem` struct that's `NULL` when \p items
 *         is presently advanced past its forward/reverse limit.
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
struct AMitem *AMitemsPrev(struct AMitems *items, ptrdiff_t n);

/**
 * \memberof AMitems
 * \brief Gets the size of the sequence underlying an iterator.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \return The count of items in \p items.
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
size_t AMitemsSize(const struct AMitems *items);

/**
 * \memberof AMitems
 * \brief Creates an iterator over the same sequence of items as the
 *        given one but with the opposite position and direction.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \return An `AMitems` struct
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
struct AMitems AMitemsReversed(const struct AMitems *items);

/**
 * \memberof AMitems
 * \brief Creates an iterator at the starting position over the same sequence
 *        of items as the given one.
 *
 * \param[in] items A pointer to an `AMitems` struct.
 * \return An `AMitems` struct
 * \pre \p items `!= NULL`
 * \internal
 *
 * #Safety
 * items must be a valid pointer to an AMitems
 */
struct AMitems AMitemsRewound(const struct AMitems *items);

/**
 * \memberof AMobjId
 * \brief Gets the actor identifier component of an object identifier.
 *
 * \param[in] obj_id A pointer to an `AMobjId` struct.
 * \return A pointer to an `AMactorId` struct or `NULL`.
 * \pre \p obj_id `!= NULL`
 * \internal
 *
 * # Safety
 * obj_id must be a valid pointer to an AMobjId
 */
const struct AMactorId *AMobjIdActorId(const struct AMobjId *obj_id);

/**
 * \memberof AMobjId
 * \brief Gets the counter component of an object identifier.
 *
 * \param[in] obj_id A pointer to an `AMobjId` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p obj_id `!= NULL`
 * \internal
 *
 * # Safety
 * obj_id must be a valid pointer to an AMobjId
 */
uint64_t AMobjIdCounter(const struct AMobjId *obj_id);

/**
 * \memberof AMobjId
 * \brief Tests the equality of two object identifiers.
 *
 * \param[in] obj_id1 A pointer to an `AMobjId` struct.
 * \param[in] obj_id2 A pointer to an `AMobjId` struct.
 * \return `true` if \p obj_id1 `==` \p obj_id2 and `false` otherwise.
 * \pre \p obj_id1 `!= NULL`
 * \pre \p obj_id1 `!= NULL`
 * \post `!(`\p obj_id1 `&&` \p obj_id2 `) -> false`
 * \internal
 *
 * #Safety
 * obj_id1 must be a valid AMobjId pointer
 * obj_id2 must be a valid AMobjId pointer
 */
bool AMobjIdEqual(const struct AMobjId *obj_id1, const struct AMobjId *obj_id2);

/**
 * \memberof AMobjId
 * \brief Gets the index component of an object identifier.
 *
 * \param[in] obj_id A pointer to an `AMobjId` struct.
 * \return A 64-bit unsigned integer.
 * \pre \p obj_id `!= NULL`
 * \internal
 *
 * # Safety
 * obj_id must be a valid pointer to an AMobjId
 */
size_t AMobjIdIndex(const struct AMobjId *obj_id);

/**
 * \memberof AMresult
 * \brief Concatenates the items from two results.
 *
 * \param[in] dest A pointer to an `AMresult` struct.
 * \param[in] src A pointer to an `AMresult` struct.
 * \return A pointer to an `AMresult` struct with the items from \p dest in
 *         their original order followed by the items from \p src in their
 *         original order.
 * \pre \p dest `!= NULL`
 * \pre \p src `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * dest must be a valid pointer to an AMresult
 * src must be a valid pointer to an AMresult
 */
struct AMresult *AMresultCat(const struct AMresult *dest, const struct AMresult *src);

/**
 * \memberof AMresult
 * \brief Gets a result's error message string.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \return A UTF-8 string view as an `AMbyteSpan` struct.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
struct AMbyteSpan AMresultError(const struct AMresult *result);

/**
 * \memberof AMresult
 * \brief Deallocates the storage for a result.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
void AMresultFree(struct AMresult *result);

/**
 * \memberof AMresult
 * \brief Gets a result's first item.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \return A pointer to an `AMitem` struct.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
struct AMitem *AMresultItem(struct AMresult *result);

/**
 * \memberof AMresult
 * \brief Gets a result's items.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \return An `AMitems` struct.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
struct AMitems AMresultItems(struct AMresult *result);

/**
 * \memberof AMresult
 * \brief Gets the size of a result.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \return The count of items within \p result.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
size_t AMresultSize(const struct AMresult *result);

/**
 * \memberof AMresult
 * \brief Gets the status code of a result.
 *
 * \param[in] result A pointer to an `AMresult` struct.
 * \return An `AMstatus` enum tag.
 * \pre \p result `!= NULL`
 * \internal
 *
 * # Safety
 * result must be a valid pointer to an AMresult
 */
AMstatus AMresultStatus(const struct AMresult *result);

/**
 * \memberof AMsyncHave
 * \brief Gets the heads of the sender.
 *
 * \param[in] sync_have A pointer to an `AMsyncHave` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_have `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_have must be a valid pointer to an AMsyncHave
 */
struct AMresult *AMsyncHaveLastSync(const struct AMsyncHave *sync_have);

/**
 * \memberof AMsyncMessage
 * \brief Gets the changes for the recipient to apply.
 *
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE` items.
 * \pre \p sync_message `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMsyncMessageChanges(const struct AMsyncMessage *sync_message);

/**
 * \memberof AMsyncMessage
 * \brief Decodes an array of bytes into a synchronization message.
 *
 * \param[in] src A pointer to an array of bytes.
 * \param[in] count The count of bytes to decode from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_SYNC_MESSAGE` 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`
 */
struct AMresult *AMsyncMessageDecode(const uint8_t *src, size_t count);

/**
 * \memberof AMsyncMessage
 * \brief Encodes a synchronization message as an array of bytes.
 *
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_BYTES` item.
 * \pre \p sync_message `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMsyncMessageEncode(const struct AMsyncMessage *sync_message);

/**
 * \memberof AMsyncMessage
 * \brief Gets a summary of the changes that the sender already has.
 *
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with `AM_SYNC_HAVE` items.
 * \pre \p sync_message `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMsyncMessageHaves(const struct AMsyncMessage *sync_message);

/**
 * \memberof AMsyncMessage
 * \brief Gets the heads of the sender.
 *
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_message `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMsyncMessageHeads(const struct AMsyncMessage *sync_message);

/**
 * \memberof AMsyncMessage
 * \brief Gets the hashes of any changes that are being explicitly requested
 *        by the recipient.
 *
 * \param[in] sync_message A pointer to an `AMsyncMessage` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_message `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_message must be a valid pointer to an AMsyncMessage
 */
struct AMresult *AMsyncMessageNeeds(const struct AMsyncMessage *sync_message);

/**
 * \memberof AMsyncState
 * \brief Decodes an array of bytes into a synchronization state.
 *
 * \param[in] src A pointer to an array of bytes.
 * \param[in] count The count of bytes to decode from the array pointed to by
 *                  \p src.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_SYNC_STATE` 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`
 */
struct AMresult *AMsyncStateDecode(const uint8_t *src, size_t count);

/**
 * \memberof AMsyncState
 * \brief Encodes a synchronization state as an array of bytes.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_BYTE_SPAN` item.
 * \pre \p sync_state `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 */
struct AMresult *AMsyncStateEncode(const struct AMsyncState *sync_state);

/**
 * \memberof AMsyncState
 * \brief Tests the equality of two synchronization states.
 *
 * \param[in] sync_state1 A pointer to an `AMsyncState` struct.
 * \param[in] sync_state2 A pointer to an `AMsyncState` struct.
 * \return `true` if \p sync_state1 `==` \p sync_state2 and `false` otherwise.
 * \pre \p sync_state1 `!= NULL`
 * \pre \p sync_state2 `!= NULL`
 * \post `!(`\p sync_state1 `&&` \p sync_state2 `) -> false`
 * \internal
 *
 * #Safety
 * sync_state1 must be a valid pointer to an AMsyncState
 * sync_state2 must be a valid pointer to an AMsyncState
 */
bool AMsyncStateEqual(const struct AMsyncState *sync_state1, const struct AMsyncState *sync_state2);

/**
 * \memberof AMsyncState
 * \brief Allocates a new synchronization state and initializes it from
 *        default values.
 *
 * \return A pointer to an `AMresult` struct with an `AM_VAL_TYPE_SYNC_STATE` item.
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 */
struct AMresult *AMsyncStateInit(void);

/**
 * \memberof AMsyncState
 * \brief Gets the heads that are shared by both peers.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_state `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 */
struct AMresult *AMsyncStateSharedHeads(const struct AMsyncState *sync_state);

/**
 * \memberof AMsyncState
 * \brief Gets the heads that were last sent by this peer.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_state `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 */
struct AMresult *AMsyncStateLastSentHeads(const struct AMsyncState *sync_state);

/**
 * \memberof AMsyncState
 * \brief Gets a summary of the changes that the other peer already has.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \param[out] has_value A pointer to a boolean flag that is set to `true` if
 *             the returned `AMitems` struct is relevant, `false` otherwise.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_SYNC_HAVE` items.
 * \pre \p sync_state `!= NULL`
 * \pre \p has_value `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 * has_value must be a valid pointer to a bool.
 */
struct AMresult *AMsyncStateTheirHaves(const struct AMsyncState *sync_state, bool *has_value);

/**
 * \memberof AMsyncState
 * \brief Gets the heads that were sent by the other peer.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \param[out] has_value A pointer to a boolean flag that is set to `true` if
 *                       the returned `AMitems` struct is relevant, `false`
 *                       otherwise.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_state `!= NULL`
 * \pre \p has_value `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 * has_value must be a valid pointer to a bool
 */
struct AMresult *AMsyncStateTheirHeads(const struct AMsyncState *sync_state, bool *has_value);

/**
 * \memberof AMsyncState
 * \brief Gets the needs that were sent by the other peer.
 *
 * \param[in] sync_state A pointer to an `AMsyncState` struct.
 * \param[out] has_value A pointer to a boolean flag that is set to `true` if
 *                       the returned `AMitems` struct is relevant, `false`
 *                       otherwise.
 * \return A pointer to an `AMresult` struct with `AM_VAL_TYPE_CHANGE_HASH` items.
 * \pre \p sync_state `!= NULL`
 * \pre \p has_value `!= NULL`
 * \warning The returned `AMresult` struct pointer must be passed to
 *          `AMresultFree()` in order to avoid a memory leak.
 * \internal
 *
 * # Safety
 * sync_state must be a valid pointer to an AMsyncState
 * has_value must be a valid pointer to a bool
 */
struct AMresult *AMsyncStateTheirNeeds(const struct AMsyncState *sync_state, bool *has_value);

#endif /* AUTOMERGE_C_H */