libasdf-rs 0.2.2

/**
 * .. _asdf/core/ndarray.h:
 *
 * Minimalistic prototype implementation of the
 * :ref:`stsci.edu/asdf/core/ndarray-1.1.0` schema
 *
 * Support is not yet fully complete.  What is implemented:
 *
 * * ASDF internal block sources
 * * All int and most float data types (other data types can be read but are
 *   not fully implemented)
 * * :c:member:`shape <asdf_ndarray_t.shape>`,
 *   :c:member:`byteorder <asdf_ndarray_t.byteorder>`, and
 *   :c:member:`offset <asdf_ndarray_t.offset>`
 * * :c:member:`strides <asdf_ndarray_t.strides>` are partially supported
 *
 * It can provide direct access to the raw data of an ndarray (via a
 * ``void *``); users must use
 * the metadata provided in the `asdf_ndarray_t` struct to interpret the data.
 * However, data can also be copied as tiles using the
 * `asdf_ndarray_read_tile_ndim` and `asdf_ndarray_read_tile_2d` functions.
 *
 *
 * What is not yet supported:
 *
 * * Shape containing '*'
 * * Reading ``complex64`` or ``complex128`` datatypes
 * * Reading string datatypes (``ascii`` or ``ucs4``)
 * * Reading structured datatypes (the datatypes are parsed but there is are
 *   no APIs yet for interpreting structured array data)
 * * Reading arbitrarily strided data
 * * Masks are not parsed or used at all, whether simple mask values or mask
 *   arrays (though if present a warning is logged indicating lack of support)
 *
 * The current limitations are purely artificial--it is so that we can rapidly
 * develop the minimal viable product needed to make ASDF ndarray data
 * available in common use cases.
 *
 * Complete ndarray support will follow gradually.
 */

//

#ifndef ASDF_CORE_NDARRAY_H
#define ASDF_CORE_NDARRAY_H

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

#include <asdf/core/datatype.h>
#include <asdf/emitter.h>
#include <asdf/extension.h>
#include <asdf/util.h>

ASDF_BEGIN_DECLS

#define ASDF_CORE_NDARRAY_TAG ASDF_CORE_TAG_PREFIX "ndarray-1.1.0"


/**
 * .. _ndarray-types:
 *
 * Types
 * -----
 */


/**
 * Error codes returned by some functions that read ndarray data
 */
typedef enum {
    /** Indicates that the ndarray was read successfully */
    ASDF_NDARRAY_OK = 0,
    /**
     * Return value indicating that an attempt was made to read beyond the
     * bounds of the ndarray
     */
    ASDF_NDARRAY_ERR_OUT_OF_BOUNDS,
    /** A memory error occurred (typically out-of-memory) */
    ASDF_NDARRAY_ERR_OOM,
    /**
     * An invalid argument was passed to the function (e.g. incorrect number
     * of shape dimensions)
     */
    ASDF_NDARRAY_ERR_INVAL,
    /** An overflow occurred, particularly when reading integer values */
    ASDF_NDARRAY_ERR_OVERFLOW,
    /**
     * Some ndarray data elements could not be converted to the requested
     * output datatype
     */
    ASDF_NDARRAY_ERR_CONVERSION,
} asdf_ndarray_err_t;


#ifndef ASDF_CORE_NDARRAY_INTERNAL
/**
 * Public definition of the `asdf_ndarray_t` type
 *
 * This is the main object through which ndarrays are used.  They can be
 * retrieved via `asdf_get_ndarray` and `asdf_value_as_ndarray`.  The library
 * allocates memory for this data structure which must be freed by the user with
 * `asdf_ndarray_destroy` when no-longer needed.
 *
 * For convenience some basic fields are made public for now, though this may
 * not be ABI-stable in future releases.
 */
typedef struct {
    /** The index of the binary block containing the ndarray data */
    size_t source;
    /** The number of dimensions of the array */
    uint32_t ndim;
    /** The shape of the array, itself an array of size ``.ndim`` */
    const uint64_t *shape;
    /** The datatype of the array as represented by `asdf_datatype_t` */
    asdf_datatype_t datatype;
    /** The byteorder of the array data where applicable */
    asdf_byteorder_t byteorder;
    /** Optional offset into the binary block where the array data begins */
    uint64_t offset;
    /**
     * Optional strides to use when iterating/index array data (an array of
     * size ``.ndim`` giving the stride for each dimension)
     */
    const int64_t *strides;

    // Reserved for internal use
    void *_reserved;
} asdf_ndarray_t;
#else
typedef struct asdf_ndarray asdf_ndarray_t;
#endif


/**
 * .. _ndarray-get:
 *
 * Getting ndarrays
 * ----------------
 */


// NOTE: For now I don't see any good way to generate docstrings for functions
// generated by ASDF_DECLARE_EXTENSION, so we just insert them manually for
// now.  Should be possible with a custom extension to Sphinx (or Hawkmoth)
// but not worth the effort short-term.
//

// clang-format off

/**
 * .. c:function:: asdf_value_err_t asdf_get_ndarray(asdf_file_t *file, const char *path, asdf_ndarray_t **out)
 *
 *   Get an `asdf_ndarray_t *` out of the ASDF tree
 *
 *   :param file: The `asdf_file_t *` for the file
 *   :param path: The :ref:`yaml-pointer` to the ndarray
 *   :param out: An `asdf_ndarray_t **` into which to return the `asdf_ndarray_t *`
 *
 *   :return: `ASDF_VALUE_OK` if the value exists and is an ndarray, otherwise
 *     `ASDF_VALUE_ERR_NOT_FOUND` or `ASDF_VALUE_ERR_TYPE_MISMATCH`.
 */


/**
 * .. c:function:: asdf_value_err_t asdf_set_ndarray(asdf_file_t *file, const char *path, asdf_ndarray_t *ndarray)
 *
 *   Set an `asdf_ndarray_t *` to a path in the ASDF tree
 *
 *   This is used to add a new ndarray to the file at a given path. If the
 *   ndarray has data allocated for it and is set to internal storage (see
 *   `asdf_ndarray_storage_set`, a new binary block will be allocated for its
 *   data when writing the file.
 *
 *   :param file: The `asdf_file_t *` for the file
 *   :param path: The :ref:`yaml-pointer` for the ndarray
 *   :param ndarray: An `asdf_ndarray_t *` to store
 *
 *   :return: `ASDF_VALUE_OK` if the value exists and is an ndarray, otherwise
 *     an error if an inconsistency in the `asdf_ndarray_t` struct prevents
 *     serialization.
 */


/**
 * .. c:function:: asdf_value_err_t asdf_value_as_ndarray(asdf_value_t *value, asdf_ndarray_t **out)
 *
 *   Cast a generic `asdf_value_t *` as an ndarray value, if possible
 *
 *   :param value: The `asdf_value_t *` handle
 *   :param out: An `asdf_ndarray_t **` into which to return the `asdf_ndarray_t *`
 *
 *   :return: `ASDF_VALUE_OK` if the value is an ndarray, otherwise
 *     `ASDF_VALUE_ERR_TYPE_MISMATCH`.
 */


/**
 * .. c:function:: asdf_value_t *asdf_value_of_ndarray(asdf_file_t *file, const asdf_ndarray_t *ndarray)
 *
 *   Create a generic `asdf_value_t *` from an ndarray
 *
 *   This serializes ``ndarray`` into a value belonging to ``file`` (as
 *   `asdf_set_ndarray` does before placing it in the tree), which can then be
 *   assigned into the tree with `asdf_set_value` or nested inside another value.
 *   As with `asdf_set_ndarray`, assigning the ndarray this way transfers
 *   ownership of its data to ``file``.
 *
 *   :param file: The `asdf_file_t *` for the file
 *   :param ndarray: The `asdf_ndarray_t *` to serialize
 *
 *   :return: A new `asdf_value_t *`, or ``NULL`` on failure
 */


/**
 * .. c:function:: void asdf_ndarray_destroy(asdf_ndarray_t *ndarray)
 *
 *   Release datastructures and memory allocated for an `asdf_ndarray_t`
 *
 *   :param ndarray: The `asdf_ndarray_t *`
 */


/**
 * .. c:function:: asdf_ndarray_t *asdf_ndarray_copy(asdf_file_t *file, const asdf_ndarray_t *src)
 *
 *   Make an independent deep copy of an ndarray
 *
 *   The copy duplicates ``src``'s metadata (shape, strides, and datatype) and
 *   its data: an inline array clones its inline data, while a block-backed array
 *   copies its block into a new block managed for ``file`` (preserving
 *   compression).  Because the copy is fully independent of ``src`` and its
 *   file, ``file`` may differ from the source's file, and the returned ndarray
 *   can be assigned (`asdf_set_ndarray`) and written like any other.
 *
 *   The returned `asdf_ndarray_t *` is owned by the caller and must be released
 *   with `asdf_ndarray_destroy` (unless assigned to a file, which then takes
 *   ownership of its data).
 *
 *   :param file: The `asdf_file_t *` that will manage the copy's data
 *   :param src: The `asdf_ndarray_t *` to copy
 *   :return: A newly allocated `asdf_ndarray_t *`, or ``NULL`` on failure
 */

// clang-format on

ASDF_DECLARE_EXTENSION(ndarray, asdf_ndarray_t);


/**
 * .. _ndarray-data-access:
 *
 * Data access
 * -----------
 */

/**
 * Return a pointer to the ndarray's element data
 *
 * If the array is stored in a compressed block a buffer containing the
 * decompressed data is returned (see also :ref:`compression`).
 * The data is presented in the array's source datatype and byte order;
 * use `asdf_ndarray_read_all` or the ``asdf_ndarray_read_tile_*``
 * functions to read it converted to a host datatype and native byte order.
 *
 * The returned pointer is owned by ``ndarray`` and remains valid until the
 * ndarray (or its file) is destroyed; the caller must not free it.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :param size: If non-``NULL``, receives the size of the data in bytes
 * :return: A pointer to the (decompressed) data, or ``NULL`` on error -- for
 *   example if the array has no associated data block (such as an inline
 *   array) or if decompression failed
 */
ASDF_EXPORT const void *asdf_ndarray_data(asdf_ndarray_t *ndarray, size_t *size);


/**
 * Return a pointer to the raw ndarray data, without decompressing it
 *
 * For arrays stored in a compressed block this returns the still-compressed
 * bytes exactly as they appear in the file.  For uncompressed arrays it is
 * equivalent to `asdf_ndarray_data`.
 *
 * As with `asdf_ndarray_data`, the returned pointer is owned by ``ndarray``
 * and must not be freed by the caller.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :param size: If non-``NULL``, receives the size of the raw data in bytes
 * :return: A pointer to the raw data, or ``NULL`` on error
 */
ASDF_EXPORT const void *asdf_ndarray_data_raw(asdf_ndarray_t *ndarray, size_t *size);

/**
 * Return the total number of elements (not bytes) in the ndarray
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :return: Total number of elements in the array (just the product of its
 *   shape)
 */
ASDF_EXPORT uint64_t asdf_ndarray_size(const asdf_ndarray_t *ndarray);


/**
 * Return the total number of bytes in the ndarray data
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :return: The byte size of the ndarray (this is just its size times the
 *   datatype nbytes)
 */
ASDF_EXPORT uint64_t asdf_ndarray_nbytes(const asdf_ndarray_t *ndarray);


/**
 * .. _ndarray-alloc:
 *
 * Allocating data buffers
 * -----------------------
 */


/**
 * Allocate heap memory large enough to store the data for the ndarray
 *
 * Every call to this function should have a corresponding
 * `asdf_ndarray_data_dealloc` to free the allocated memory when it is
 * no longer needed (such as after writing the file).  The memory is not
 * automatically freed.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :return: A `void *` to the allocated memory or `NULL` if the memory
 *   could not be allocated; subsequent calls on the same ndarray will
 *   return the same memory
 */
ASDF_EXPORT void *asdf_ndarray_data_alloc(asdf_ndarray_t *ndarray);


/**
 * Free ndarray data allocated with `asdf_ndarray_data_alloc`
 *
 * If the ndarray never had data allocated this is a no-op but does produce
 * a debug log message if logging is enabled.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 */
ASDF_EXPORT void asdf_ndarray_data_dealloc(asdf_ndarray_t *ndarray);


/**
 * Allocate the ndarray's data buffer and copy its contents from a source buffer
 *
 * A convenience over `asdf_ndarray_data_alloc` for the common case of building
 * an ndarray whose data you already have: it allocates a buffer sized for the
 * array's shape and datatype (exactly as `asdf_ndarray_data_alloc`) and copies
 * `asdf_ndarray_nbytes` bytes into it from ``src``.  This computes the byte
 * count for you, avoiding error-prone manual size arithmetic.
 *
 * The caller is responsible for ensuring ``src`` points to at least
 * `asdf_ndarray_nbytes` bytes; a smaller source buffer results in an over-read.
 *
 * :param ndarray: An `asdf_ndarray_t *` whose shape and datatype are set
 * :param src: The source buffer to copy the array data from
 * :return: `ASDF_NDARRAY_OK` on success, `ASDF_NDARRAY_ERR_INVAL` if an argument
 *   is ``NULL``, or `ASDF_NDARRAY_ERR_OOM` if the buffer could not be allocated
 */
ASDF_EXPORT asdf_ndarray_err_t asdf_ndarray_data_copy(asdf_ndarray_t *ndarray, const void *src);


/**
 * .. _ndarray-storage:
 *
 * Storage and compression
 * -----------------------
 */


/**
 * Set the compression method to use for the ndarray data when writing
 *
 * See also `asdf_block_compression_set` for which this is a shortcut (applies
 * to the block created for holding this ndarray's data).
 *
 * :param ndarray: An `asdf_ndarray_t *` handle
 * :param compression: String representing the compressor to use (e.g. "bzp2")
 *   if any, or NULL or the empty string to set no compression
 * :return: Non-zero if the compression could not be set (e.g. invalid/unknown
 *   compressor); use `asdf_error` to check the error code
 */
ASDF_EXPORT int asdf_ndarray_compression_set(asdf_ndarray_t *ndarray, const char *compression);


/**
 * Return the storage mode that will be used when the ndarray is written.
 *
 * If the ndarray was read from a file this reflects how it was originally
 * stored.  For a newly constructed ndarray this reflects whatever was last
 * passed to `asdf_ndarray_storage_set`, or ``ASDF_ARRAY_STORAGE_INTERNAL``
 * if the storage was never explicitly set.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :return: The `asdf_array_storage_t` for this ndarray.
 */
ASDF_EXPORT asdf_array_storage_t asdf_ndarray_storage(asdf_ndarray_t *ndarray);


/**
 * Set the storage mode used when the ndarray is written.
 *
 * ``ASDF_ARRAY_STORAGE_INLINE`` serializes the data as a nested YAML
 * sequence under the ``data`` key.  A warning is logged if the number of
 * elements exceeds the configured threshold (see
 * ``asdf_emitter_cfg_t.inline_ndarray_warning_thresh``).
 *
 * ``ASDF_ARRAY_STORAGE_INTERNAL`` writes the data in a binary block (the
 * default when no storage mode is set).
 *
 * ``ASDF_ARRAY_STORAGE_EXTERNAL`` is not yet supported; calling this function
 * with that value logs an error and leaves the storage mode unchanged.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :param storage: The desired `asdf_array_storage_t`
 */
ASDF_EXPORT void asdf_ndarray_storage_set(asdf_ndarray_t *ndarray, asdf_array_storage_t storage);


/**
 * Get the pointer to the open `asdf_block_t` associated with the ndarray
 *
 * This is mostly for debugging/low-level inspection and is not needed for
 * typical use cases.
 *
 * :param ndarray: An `asdf_ndarray_t *`
 * :return: A constant pointer to the `asdf_block_t` structure representing
 *   the binary block underlying the array, if any.  This will be `NULL`, for
 *   example, if the ndarray used inline data.
 */
ASDF_EXPORT asdf_block_t *asdf_ndarray_block(asdf_ndarray_t *ndarray);


/**
 * .. _ndarray-read:
 *
 * Reading array data
 * ------------------
 */


/**
 * Read the full ndarray, copying into the provided buffer (or allocating a
 * destination buffer if ``dst = NULL``)
 *
 * This is like `asdf_ndarray_read_tile_ndim` but with a default "tile" size
 * of the full array.  Like `asdf_ndarray_read_tile_ndim` it will also convert
 * the data to the host native byte order if necessary, and can convert it to a
 * different numeric type than the source array.
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param dst_t: An `asdf_scalar_datatype_t` to convert to, or
 *   `ASDF_DATATYPE_SOURCE` to keep the original source datatype
 * :param dst: Pointer to a destination `void *` already allocated to receive
 *   the exact number of bytes in the source ndarray, or `NULL` to indicate
 *   that a buffer should be allocated.  In the latter case the caller is
 *   responsible for releasing the allocated buffer with `asdf_free`.
 * :return: An `asdf_ndarray_err_t`; either `ASDF_NDARRAY_OK` if the data read
 *   successfully; otherwise the relevant error code.
 */
ASDF_EXPORT asdf_ndarray_err_t
asdf_ndarray_read_all(asdf_ndarray_t *ndarray, asdf_scalar_datatype_t dst_t, void **dst);

/**
 * Read tiles of up to N-dimensions out of N-D arrays
 *
 * Tiles can be slices of any number of dimenions <= N and of any shape so long
 * as they don't go past the bounds of the array (otherwise
 * `ASDF_NDARRAY_ERR_OUT_OF_BOUNDS` is returned).
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param origin: The indices of the first pixel of the tile--an array of size
 *   :c:member:`ndim <asdf_ndarray_t.ndim>`
 * :param shape: The shape of the tile to read--an array of size
 *   :c:member:`ndim <asdf_ndarray_t.ndim>`
 * :param dst_t: The output datatype, if conversion from the source array's
 *   datatype to the output datatype is possible
 *
 *   Currently, if no conversion is possible it will just copy the tile data
 *   without conversion--this may change in the future to become an error.
 *   You can pass the special value `ASDF_DATATYPE_SOURCE` to indicate that
 *   the output datatype is the source datatype.
 * :param dst: Pointer to a destination `void *` already allocated to receive
 *   the exact number of bytes in the output tile based on shape and datatype,
 *   or `NULL` to indicate that a buffer should be allocated.  In the latter
 *   case the caller is responsible for releasing the allocated buffer with
 *   `asdf_free`.
 * :return: An `asdf_ndarray_err_t`; either `ASDF_NDARRAY_OK` if the data read
 *   successfully; otherwise the relevant error code.
 */
ASDF_EXPORT asdf_ndarray_err_t asdf_ndarray_read_tile_ndim(
    asdf_ndarray_t *ndarray,
    const uint64_t *origin,
    const uint64_t *shape,
    asdf_scalar_datatype_t dst_t,
    void **dst);

/**
 * Like `asdf_ndarray_read_tile_ndim` but with conveniences for the common 2-D
 * case
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param x: The x coordinate of the tile origin
 * :param y: The y coordinate of the tile origin
 * :param width: The width of the tile in the x direction
 * :param height: The height of the tile in the y direction
 * :param plane_origin: If the source array is greater than 2-dimensional, the
 *   ``ndim - 2`` array of plane coordinates--may be `NULL` if either the source
 *   array is 2-D or otherwise the outer-most plane is used
 * :param dst_t: The output datatype, if conversion from the source array's
 *   datatype to the output datatype is possible
 *
 *   Currently, if no conversion is possible it will just copy the tile data
 *   without conversion--this may change in the future to become an error.
 *   You can pass the special value `ASDF_DATATYPE_SOURCE` to indicate that
 *   the output datatype is the source datatype.
 * :param dst: Pointer to a destination `void *` already allocated to receive
 *   the exact number of bytes in the output tile based on shape and datatype,
 *   or `NULL` to indicate that a buffer should be allocated.  In the latter
 *   case the caller is responsible for releasing the allocated buffer with
 *   `asdf_free`.
 * :return: An `asdf_ndarray_err_t`; either `ASDF_NDARRAY_OK` if the data read
 *   successfully; otherwise the relevant error code.
 */
ASDF_EXPORT asdf_ndarray_err_t asdf_ndarray_read_tile_2d(
    asdf_ndarray_t *ndarray,
    uint64_t x,
    uint64_t y,
    uint64_t width,
    uint64_t height,
    const uint64_t *plane_origin,
    asdf_scalar_datatype_t dst_t,
    void **dst);

// Forward-declaration for documentation; the real implementations of
// asdf_read_at and asdf_read_at_err are later in this file.

/**
 * Read the element at the given indices, converted to ``type``
 *
 * ``type`` must be one of the C scalar types named by the
 * ``asdf_ndarray_read_<type>_at`` functions.  The number of indices is taken
 * from the number of arguments, and must equal the array's
 * :c:member:`ndim <asdf_ndarray_t.ndim>`.  At least one index is required::
 *
 *   double value = asdf_ndarray_at(ndarray, double, 3, 7);
 *
 * Errors are not reported: on any error the value is zero, which is
 * indistinguishable from an element whose value is zero.  Use
 * `asdf_ndarray_at_err` where that matters.
 *
 * This is a macro and is unavailable in C++; use the
 * ``asdf_ndarray_read_<type>_at`` functions instead.
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param type: The C scalar type to convert the element to
 * :param ...: The indices of the element to read
 * :return: The element converted to ``type``, or zero on error
 */
#define asdf_ndarray_at(ndarray, type, ...)
#undef asdf_ndarray_at

/**
 * Like `asdf_ndarray_at` but reporting errors through ``err``
 *
 * The indices are given as a variadic argument list after ``err``::
 *
 *   asdf_ndarray_err_t err = ASDF_NDARRAY_OK;
 *   double value = asdf_ndarray_at_err(ndarray, double, &err, 3, 7);
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param type: The C scalar type to convert the element to
 * :param err: An `asdf_ndarray_err_t *` receiving the error code, or ``NULL``
 * :param ...: The indices of the element to read
 * :return: The element converted to ``type``, or zero on error
 */
#define asdf_ndarray_at_err(ndarray, type, err, ...)
#undef asdf_ndarray_at_err


/**
 * Read a single element of the ndarray, converting it as `asdf_ndarray_read_all`
 * does
 *
 * The element is copied into ``dst``, which must have room for one value of
 * ``dst_t``.  ``dst`` need not be aligned for its type.
 *
 * For C code the `asdf_ndarray_at` and `asdf_ndarray_at_err` macros are more
 * convenient.
 *
 * .. note::
 *
 *   If reading many elements of an array in a loop this call is inefficient;
 *   it is better to read multiple elements in a single pass using
 *   `asdf_ndarray_read_tile_ndim`, `asdf_ndarray_read_tile_2d` or
 *   `asdf_ndarray_read_all` depending on the use case.  This method can still
 *   be useful for a few incidental single-element reads.
 *
 * ``indices`` must have :c:member:`ndim <asdf_ndarray_t.ndim>` entries; that
 * many are read from it.
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param indices: The indices of the element to read--an array of size
 *   :c:member:`ndim <asdf_ndarray_t.ndim>`
 * :param dst_t: An `asdf_scalar_datatype_t` to convert to, or
 *   `ASDF_DATATYPE_SOURCE` to keep the original source datatype
 * :param dst: Pointer to storage receiving the element
 * :return: An `asdf_ndarray_err_t`; `ASDF_NDARRAY_OK` if the element was read
 *   successfully, `ASDF_NDARRAY_ERR_OUT_OF_BOUNDS` if any index is outside the
 *   array's shape; otherwise the relevant error code.
 */
ASDF_EXPORT asdf_ndarray_err_t asdf_ndarray_read_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_scalar_datatype_t dst_t, void *dst);


/**
 * Read a single element of the ndarray, converted to the named type
 *
 * These are the same as `asdf_ndarray_read_at` with ``dst_t`` fixed by the
 * function name, except that the element is returned rather than copied into
 * ``dst``.  On error the returned value is zero and, if ``err`` is not
 * ``NULL``, the error code is stored in it.
 *
 * The `asdf_ndarray_at` and `asdf_ndarray_at_err` macros select among these
 * automatically and are usually easier to read.  They are unavailable in C++,
 * which must call these directly.
 *
 * ``indices`` must have :c:member:`ndim <asdf_ndarray_t.ndim>` entries; that
 * many are read from it.
 *
 * :param ndarray: The `asdf_ndarray_t *` handle to the ndarray
 * :param indices: The indices of the element to read--an array of size
 *   :c:member:`ndim <asdf_ndarray_t.ndim>`
 * :param err: Optional `asdf_ndarray_err_t *` receiving the error code, or
 *   ``NULL`` to ignore errors
 * :return: The element converted to the function's type, or zero on error
 */
ASDF_EXPORT int8_t asdf_ndarray_read_int8_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT uint8_t asdf_ndarray_read_uint8_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT int16_t asdf_ndarray_read_int16_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT uint16_t asdf_ndarray_read_uint16_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT int32_t asdf_ndarray_read_int32_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT uint32_t asdf_ndarray_read_uint32_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT int64_t asdf_ndarray_read_int64_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT uint64_t asdf_ndarray_read_uint64_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
#ifdef ASDF_HAVE_FLOAT16
/** See `asdf_ndarray_read_int8_at`; declared only if ``ASDF_HAVE_FLOAT16`` */
ASDF_EXPORT _Float16 asdf_ndarray_read_float16_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
#endif
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT float asdf_ndarray_read_float32_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);
/** See `asdf_ndarray_read_int8_at` */
ASDF_EXPORT double asdf_ndarray_read_float64_at(
    asdf_ndarray_t *ndarray, const uint64_t *indices, asdf_ndarray_err_t *err);


#ifndef __cplusplus
#ifdef ASDF_HAVE_FLOAT16
#define ASDF__READ_AT_FLOAT16 _Float16 : asdf_ndarray_read_float16_at,
#else
#define ASDF__READ_AT_FLOAT16
#endif


/* Selects the asdf_ndarray_read_<type>_at function for a C scalar type */
// clang-format off
#define ASDF__READ_AT_FN(type) \
    _Generic( \
        ((type){0}), \
        ASDF__READ_AT_FLOAT16 \
        int8_t: asdf_ndarray_read_int8_at, \
        uint8_t: asdf_ndarray_read_uint8_at, \
        int16_t: asdf_ndarray_read_int16_at, \
        uint16_t: asdf_ndarray_read_uint16_at, \
        int32_t: asdf_ndarray_read_int32_at, \
        uint32_t: asdf_ndarray_read_uint32_at, \
        int64_t: asdf_ndarray_read_int64_at, \
        uint64_t: asdf_ndarray_read_uint64_at, \
        float: asdf_ndarray_read_float32_at, \
        double: asdf_ndarray_read_float64_at)
// clang-format on


/* The indices appear twice, but the operand of sizeof is not evaluated */
#define ASDF__INDICES(...) ((const uint64_t[]){__VA_ARGS__})
#define ASDF__NINDICES(...) (sizeof(ASDF__INDICES(__VA_ARGS__)) / sizeof(uint64_t))


/*
 * The read functions take ndim indices, so passing the wrong number of them
 * would read past the end of the array built above.  Substitute NULL in that
 * case, which the read functions reject with ASDF_NDARRAY_ERR_INVAL.
 */
#define ASDF__AT_INDICES(ndarray, ...) \
    (ASDF__NINDICES(__VA_ARGS__) == (ndarray)->ndim ? ASDF__INDICES(__VA_ARGS__) : NULL)


/* Implementation of asdf_ndarray_at; see documentation further up */
#define asdf_ndarray_at(ndarray, type, ...) \
    ASDF__READ_AT_FN(type)((ndarray), ASDF__AT_INDICES((ndarray), __VA_ARGS__), NULL)


/* Implementation of asdf_ndarray_at_err; see documentation further up */
#define asdf_ndarray_at_err(ndarray, type, err, ...) \
    ASDF__READ_AT_FN(type)((ndarray), ASDF__AT_INDICES((ndarray), __VA_ARGS__), (err))
#endif /* __cplusplus */


ASDF_END_DECLS

#endif /* ASDF_CORE_NDARRAY_H */