You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by pa...@apache.org on 2022/10/07 18:50:11 UTC
[arrow-nanoarrow] branch main updated: [Documentation] Improve documentation (#58)
This is an automated email from the ASF dual-hosted git repository.
paleolimbot pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-nanoarrow.git
The following commit(s) were added to refs/heads/main by this push:
new b321e51 [Documentation] Improve documentation (#58)
b321e51 is described below
commit b321e518bda39fa99bbec5c02d464012e6d258b2
Author: Dewey Dunnington <de...@fishandwhistle.net>
AuthorDate: Fri Oct 7 15:50:06 2022 -0300
[Documentation] Improve documentation (#58)
* start on better docs
* document inline types
* better ordering
* even more doc stuff
* maybe don't commit back to a non-main repo
* a few tweaks
---
.github/workflows/docs.yaml | 10 ++-
README.md | 4 +-
docs/.gitignore | 3 +-
docs/README.md | 3 +
docs/source/c.rst | 59 ++++++++++++++--
docs/source/conf.py | 4 +-
docs/source/index.rst | 12 ++--
src/nanoarrow/nanoarrow.h | 111 +++++++++++++++++++-----------
src/nanoarrow/nanoarrow_types.h | 147 ++++++++++++++++++++++++++++------------
9 files changed, 250 insertions(+), 103 deletions(-)
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index affd065..8439e5e 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -45,6 +45,11 @@ jobs:
cd src/apidoc
doxygen
+ - name: Regenerate index content from README
+ run: |
+ cd docs
+ pandoc ../README.md --from markdown --to rst -s -o source/README_generated.rst
+
- name: Run sphinx
run: |
cd docs
@@ -55,21 +60,20 @@ jobs:
shell: Rscript {0}
- name: Upload built documentation
- if: success() && github.ref != 'refs/heads/main'
uses: actions/upload-artifact@main
with:
name: nanarrow-docs
path: docs/_build/html
- name: Clone gh-pages branch
- if: success() && github.ref == 'refs/heads/main'
+ if: success() && github.repository == 'apache/arrow-nanoarrow' && github.ref == 'refs/heads/main'
uses: actions/checkout@v2
with:
ref: gh-pages
path: pages-clone
- name: Update development documentation
- if: success() && github.ref == 'refs/heads/main'
+ if: success() && github.repository == 'apache/arrow-nanoarrow' && github.ref == 'refs/heads/main'
env:
DOC_TAG: "dev"
run: |
diff --git a/README.md b/README.md
index 5cc909e..2643609 100644
--- a/README.md
+++ b/README.md
@@ -17,9 +17,11 @@
under the License.
-->
-# arrow-nanoarrow
+# nanoarrow
[](https://app.codecov.io/gh/apache/arrow-nanoarrow?branch=main)
+[](https://apache.github.io/arrow-nanoarrow/dev)
+[](https://github.com/apache/arrow-nanoarrow)
The nanoarrow library is a set of helper functions to interpret and generate
[Arrow C Data Interface](https://arrow.apache.org/docs/format/CDataInterface.html)
diff --git a/docs/.gitignore b/docs/.gitignore
index a5909a1..43dc75f 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -15,4 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-_build
+_build/
+README_generated.rst
diff --git a/docs/README.md b/docs/README.md
index 9a4855a..97d7fd0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,6 +30,9 @@ pushd ../src/apidoc
doxygen
popd
+# copy the readme into rst so that we can include it from sphinx
+pandoc ../README.md --from markdown --to rst -s -o source/README_generated.rst
+
# Run sphinx to generate the main site
sphinx-build source _build/html
diff --git a/docs/source/c.rst b/docs/source/c.rst
index 6981169..9bed1c8 100644
--- a/docs/source/c.rst
+++ b/docs/source/c.rst
@@ -15,11 +15,62 @@
.. specific language governing permissions and limitations
.. under the License.
-C API
+C API Reference
==================
-nanoarrow.h
+Creating schemas
------------------
+.. doxygengroup:: nanoarrow-schema
+ :members:
-.. doxygenfile:: nanoarrow.h
- :project: nanoarrow_c
+Reading schemas
+------------------
+.. doxygengroup:: nanoarrow-schema-view
+ :members:
+
+Creating arrays
+------------------
+.. doxygengroup:: nanoarrow-array
+ :members:
+
+Reading arrays
+------------------
+.. doxygengroup:: nanoarrow-array-view
+ :members:
+
+Owning, growable buffers
+------------------------
+.. doxygengroup:: nanoarrow-buffer
+ :members:
+
+Bitmap utilities
+------------------
+.. doxygengroup:: nanoarrow-bitmap
+ :members:
+
+Create, read, and modify schema metadata
+----------------------------------------
+.. doxygengroup:: nanoarrow-metadata
+ :members:
+
+Memory management
+------------------
+.. doxygengroup:: nanoarrow-malloc
+ :members:
+
+Error handling
+------------------
+.. doxygengroup:: nanoarrow-errors
+ :members:
+
+Utility data structures
+-----------------------
+.. doxygengroup:: nanoarrow-utils
+ :members:
+
+Arrow C Data Interface
+----------------------
+
+.. doxygengroup:: nanoarrow-arrow-cdata
+ :members:
+ :undoc-members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 14ac742..879460c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -59,7 +59,7 @@ templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['README_generated.rst']
# -- Options for HTML output -------------------------------------------------
@@ -73,7 +73,7 @@ html_theme_options = {
"show_toc_level": 2,
"use_edit_page_button": True,
"external_links": [
- {"name": "R API", "url": "r/index.html"},
+ {"name": "R Package", "url": "r/index.html"},
],
}
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fb369f8..567d0e9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,16 +15,12 @@
.. specific language governing permissions and limitations
.. under the License.
-nanoarrow
-============
+.. include:: README_generated.rst
-The nanoarrow library is a C library providing helpers to generate and
-interpret `Arrow C Data interface <https://arrow.apache.org/docs/format/CDataInterface.html>`_
-and `Arrow C Array Stream interface <https://arrow.apache.org/docs/format/CStreamInterface.html>`_
-structures to facilitate producing and consuming data using `Apache Arrow <https://arrow.apache.org>`_.
+Contents
+--------
.. toctree::
:maxdepth: 2
- :caption: Contents:
- C API <c>
+ C API Reference <c>
diff --git a/src/nanoarrow/nanoarrow.h b/src/nanoarrow/nanoarrow.h
index 51e4292..9ec7bed 100644
--- a/src/nanoarrow/nanoarrow.h
+++ b/src/nanoarrow/nanoarrow.h
@@ -109,11 +109,7 @@
extern "C" {
#endif
-/// \file Arrow C Implementation
-///
-/// EXPERIMENTAL. Interface subject to change.
-
-/// \page object-model Object Model
+/// \defgroup nanoarrow
///
/// Except where noted, objects are not thread-safe and clients should
/// take care to serialize accesses to methods.
@@ -126,8 +122,10 @@ extern "C" {
///
/// Non-buffer members of a struct ArrowSchema and struct ArrowArray
/// must be allocated using ArrowMalloc() or ArrowRealloc() and freed
-/// using ArrowFree for schemas and arrays allocated here. Buffer members
+/// using ArrowFree() for schemas and arrays allocated here. Buffer members
/// are allocated using an ArrowBufferAllocator.
+///
+/// @{
/// \brief Allocate like malloc()
void* ArrowMalloc(int64_t size);
@@ -155,17 +153,21 @@ struct ArrowBufferAllocator ArrowBufferDeallocator(
int64_t size),
void* private_data);
-/// }@
+/// @}
-/// \defgroup nanoarrow-errors Error handling primitives
+/// \defgroup nanoarrow-errors Error handling
+///
/// Functions generally return an errno-compatible error code; functions that
/// need to communicate more verbose error information accept a pointer
/// to an ArrowError. This can be stack or statically allocated. The
/// content of the message is undefined unless an error code has been
/// returned.
+///
+/// @{
/// \brief Error type containing a UTF-8 encoded message.
struct ArrowError {
+ /// \brief A character buffer with space for an error message.
char message[1024];
};
@@ -175,9 +177,11 @@ ArrowErrorCode ArrowErrorSet(struct ArrowError* error, const char* fmt, ...);
/// \brief Get the contents of an error
const char* ArrowErrorMessage(struct ArrowError* error);
-/// }@
+/// @}
/// \defgroup nanoarrow-utils Utility data structures
+///
+/// @{
/// \brief Return the build id against which the library was compiled
const char* ArrowNanoarrowBuildId();
@@ -188,10 +192,13 @@ void ArrowLayoutInit(struct ArrowLayout* layout, enum ArrowType storage_type);
/// \brief Create a string view from a null-terminated string
static inline struct ArrowStringView ArrowCharView(const char* value);
-/// }@
+/// @}
-/// \defgroup nanoarrow-schema Schema producer helpers
+/// \defgroup nanoarrow-schema Creating schemas
+///
/// These functions allocate, copy, and destroy ArrowSchema structures
+///
+/// @{
/// \brief Initialize the fields of a schema
///
@@ -243,40 +250,54 @@ ArrowErrorCode ArrowSchemaDeepCopy(struct ArrowSchema* schema,
/// \brief Copy format into schema->format
///
-/// schema must have been allocated using ArrowSchemaInit or
-/// ArrowSchemaDeepCopy.
+/// schema must have been allocated using ArrowSchemaInit() or
+/// ArrowSchemaDeepCopy().
ArrowErrorCode ArrowSchemaSetFormat(struct ArrowSchema* schema, const char* format);
/// \brief Copy name into schema->name
///
-/// schema must have been allocated using ArrowSchemaInit or
-/// ArrowSchemaDeepCopy.
+/// schema must have been allocated using ArrowSchemaInit() or
+/// ArrowSchemaDeepCopy().
ArrowErrorCode ArrowSchemaSetName(struct ArrowSchema* schema, const char* name);
/// \brief Copy metadata into schema->metadata
///
-/// schema must have been allocated using ArrowSchemaInit or
+/// schema must have been allocated using ArrowSchemaInit() or
/// ArrowSchemaDeepCopy.
ArrowErrorCode ArrowSchemaSetMetadata(struct ArrowSchema* schema, const char* metadata);
/// \brief Allocate the schema->children array
///
/// Includes the memory for each child struct ArrowSchema.
-/// schema must have been allocated using ArrowSchemaInit or
-/// ArrowSchemaDeepCopy.
+/// schema must have been allocated using ArrowSchemaInit() or
+/// ArrowSchemaDeepCopy().
ArrowErrorCode ArrowSchemaAllocateChildren(struct ArrowSchema* schema,
int64_t n_children);
/// \brief Allocate the schema->dictionary member
///
-/// schema must have been allocated using ArrowSchemaInit or
-/// ArrowSchemaDeepCopy.
+/// schema must have been allocated using ArrowSchemaInit() or
+/// ArrowSchemaDeepCopy().
ArrowErrorCode ArrowSchemaAllocateDictionary(struct ArrowSchema* schema);
+/// @}
+
+/// \defgroup nanoarrow-metadata Create, read, and modify schema metadata
+///
+/// @{
+
/// \brief Reader for key/value pairs in schema metadata
+///
+/// The ArrowMetadataReader does not own any data and is only valid
+/// for the lifetime of the underlying metadata pointer.
struct ArrowMetadataReader {
+ /// \brief A metadata string from a schema->metadata field.
const char* metadata;
+
+ /// \brief The current offset into the metadata string
int64_t offset;
+
+ /// \brief The number of remaining keys
int32_t remaining_keys;
};
@@ -325,9 +346,11 @@ ArrowErrorCode ArrowMetadataBuilderSet(struct ArrowBuffer* buffer,
ArrowErrorCode ArrowMetadataBuilderRemove(struct ArrowBuffer* buffer,
struct ArrowStringView key);
-/// }@
+/// @}
-/// \defgroup nanoarrow-schema-view Schema consumer helpers
+/// \defgroup nanoarrow-schema-view Reading schemas
+///
+/// @{
/// \brief A non-owning view of a parsed ArrowSchema
///
@@ -422,9 +445,11 @@ struct ArrowSchemaView {
ArrowErrorCode ArrowSchemaViewInit(struct ArrowSchemaView* schema_view,
struct ArrowSchema* schema, struct ArrowError* error);
-/// }@
+/// @}
/// \defgroup nanoarrow-buffer Owning, growable buffers
+///
+/// @{
/// \brief Initialize an ArrowBuffer
///
@@ -530,9 +555,11 @@ static inline ArrowErrorCode ArrowBufferAppendDouble(struct ArrowBuffer* buffer,
static inline ArrowErrorCode ArrowBufferAppendFloat(struct ArrowBuffer* buffer,
float value);
-/// }@
+/// @}
/// \defgroup nanoarrow-bitmap Bitmap utilities
+///
+/// @{
/// \brief Extract a boolean value from a bitmap
static inline int8_t ArrowBitGet(const uint8_t* bits, int64_t i);
@@ -600,10 +627,13 @@ static inline void ArrowBitmapAppendInt32Unsafe(struct ArrowBitmap* bitmap,
/// Releases any memory held by buffer, empties the cache, and resets the size to zero
static inline void ArrowBitmapReset(struct ArrowBitmap* bitmap);
-/// }@
+/// @}
-/// \defgroup nanoarrow-array Array producer helpers
+/// \defgroup nanoarrow-array Creating arrays
+///
/// These functions allocate, copy, and destroy ArrowArray structures
+///
+/// @{
/// \brief Initialize the fields of an array
///
@@ -624,37 +654,37 @@ ArrowErrorCode ArrowArrayInitFromSchema(struct ArrowArray* array,
///
/// Includes the memory for each child struct ArrowArray,
/// whose members are marked as released and may be subsequently initialized
-/// with ArrowArrayInit or moved from an existing ArrowArray.
-/// schema must have been allocated using ArrowArrayInit.
+/// with ArrowArrayInit() or moved from an existing ArrowArray.
+/// schema must have been allocated using ArrowArrayInit().
ArrowErrorCode ArrowArrayAllocateChildren(struct ArrowArray* array, int64_t n_children);
/// \brief Allocate the array->dictionary member
///
/// Includes the memory for the struct ArrowArray, whose contents
/// is marked as released and may be subsequently initialized
-/// with ArrowArrayInit or moved from an existing ArrowArray.
-/// array must have been allocated using ArrowArrayInit
+/// with ArrowArrayInit() or moved from an existing ArrowArray.
+/// array must have been allocated using ArrowArrayInit()
ArrowErrorCode ArrowArrayAllocateDictionary(struct ArrowArray* array);
/// \brief Set the validity bitmap of an ArrowArray
///
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
void ArrowArraySetValidityBitmap(struct ArrowArray* array, struct ArrowBitmap* bitmap);
/// \brief Set a buffer of an ArrowArray
///
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
ArrowErrorCode ArrowArraySetBuffer(struct ArrowArray* array, int64_t i,
struct ArrowBuffer* buffer);
/// \brief Get the validity bitmap of an ArrowArray
///
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
static inline struct ArrowBitmap* ArrowArrayValidityBitmap(struct ArrowArray* array);
/// \brief Get a buffer of an ArrowArray
///
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
static inline struct ArrowBuffer* ArrowArrayBuffer(struct ArrowArray* array, int64_t i);
/// \brief Start element-wise appending to an ArrowArray
@@ -662,7 +692,7 @@ static inline struct ArrowBuffer* ArrowArrayBuffer(struct ArrowArray* array, int
/// Initializes any values needed to use ArrowArrayAppend*() functions.
/// All element-wise appenders append by value and return EINVAL if the exact value
/// cannot be represented by the underlying storage type.
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
static inline ArrowErrorCode ArrowArrayStartAppending(struct ArrowArray* array);
/// \brief Reserve space for future appends
@@ -738,14 +768,17 @@ static inline ArrowErrorCode ArrowArrayShrinkToFit(struct ArrowArray* array);
/// Flushes any pointers from internal buffers that may have been reallocated
/// into the array->buffers array and checks the actual size of the buffers
/// against the expected size based on the final length.
-/// array must have been allocated using ArrowArrayInit
+/// array must have been allocated using ArrowArrayInit()
ArrowErrorCode ArrowArrayFinishBuilding(struct ArrowArray* array,
struct ArrowError* error);
-/// }@
+/// @}
-/// \defgroup nanoarrow-array Array consumer helpers
+/// \defgroup nanoarrow-array-view Reading arrays
+///
/// These functions read and validate the contents ArrowArray structures
+///
+/// @{
/// \brief Initialize the contents of an ArrowArrayView
void ArrowArrayViewInit(struct ArrowArrayView* array_view, enum ArrowType storage_type);
@@ -807,7 +840,7 @@ static inline struct ArrowStringView ArrowArrayViewGetStringUnsafe(
static inline struct ArrowBufferView ArrowArrayViewGetBytesUnsafe(
struct ArrowArrayView* array_view, int64_t i);
-/// }@
+/// @}
// Inline function definitions
#include "array_inline.h"
diff --git a/src/nanoarrow/nanoarrow_types.h b/src/nanoarrow/nanoarrow_types.h
index 910b365..cb463b3 100644
--- a/src/nanoarrow/nanoarrow_types.h
+++ b/src/nanoarrow/nanoarrow_types.h
@@ -27,11 +27,20 @@
extern "C" {
#endif
-/// \defgroup nanoarrow-inline-typedef Type definitions used in inlined implementations
-
// Extra guard for versions of Arrow without the canonical guard
#ifndef ARROW_FLAG_DICTIONARY_ORDERED
+/// \defgroup nanoarrow-arrow-cdata
+///
+/// The Arrow C Data (https://arrow.apache.org/docs/format/CDataInterface.html)
+/// and Arrow C Stream (https://arrow.apache.org/docs/format/CStreamInterface.html)
+/// interfaces are part of the
+/// Arrow Columnar Format specification
+/// (https://arrow.apache.org/docs/format/Columnar.html). See the Arrow documentation for
+/// documentation of these structures.
+///
+/// @{
+
#ifndef ARROW_C_DATA_INTERFACE
#define ARROW_C_DATA_INTERFACE
@@ -116,13 +125,36 @@ struct ArrowArrayStream {
#endif // ARROW_C_STREAM_INTERFACE
#endif // ARROW_FLAG_DICTIONARY_ORDERED
+/// @}
+
+// Utility macros
+#define _NANOARROW_CONCAT(x, y) x##y
+#define _NANOARROW_MAKE_NAME(x, y) _NANOARROW_CONCAT(x, y)
+
+#define _NANOARROW_RETURN_NOT_OK_IMPL(NAME, EXPR) \
+ do { \
+ const int NAME = (EXPR); \
+ if (NAME) return NAME; \
+ } while (0)
+
+#define _NANOARROW_CHECK_RANGE(x_, min_, max_) \
+ NANOARROW_RETURN_NOT_OK((x_ >= min_ && x_ <= max_) ? NANOARROW_OK : EINVAL)
+
/// \brief Return code for success.
+/// \ingroup nanoarrow-errors
#define NANOARROW_OK 0
/// \brief Represents an errno-compatible error code
+/// \ingroup nanoarrow-errors
typedef int ArrowErrorCode;
+/// \brief Check the result of an expression and return it if not NANOARROW_OK
+/// \ingroup nanoarrow-errors
+#define NANOARROW_RETURN_NOT_OK(EXPR) \
+ _NANOARROW_RETURN_NOT_OK_IMPL(_NANOARROW_MAKE_NAME(errno_status_, __COUNTER__), EXPR)
+
/// \brief Arrow type enumerator
+/// \ingroup nanoarrow-utils
///
/// These names are intended to map to the corresponding arrow::Type::type
/// enumerator; however, the numeric values are specifically not equal
@@ -169,6 +201,10 @@ enum ArrowType {
NANOARROW_TYPE_INTERVAL_MONTH_DAY_NANO
};
+/// \brief Get a string value of an enum ArrowType value
+/// \ingroup nanoarrow-utils
+///
+/// Returns NULL for invalid values for type
static inline const char* ArrowTypeString(enum ArrowType type) {
switch (type) {
case NANOARROW_TYPE_NA:
@@ -253,6 +289,7 @@ static inline const char* ArrowTypeString(enum ArrowType type) {
}
/// \brief Arrow time unit enumerator
+/// \ingroup nanoarrow-utils
///
/// These names and values map to the corresponding arrow::TimeUnit::type
/// enumerator.
@@ -263,6 +300,10 @@ enum ArrowTimeUnit {
NANOARROW_TIME_UNIT_NANO = 3
};
+/// \brief Get a string value of an enum ArrowTimeUnit value
+/// \ingroup nanoarrow-utils
+///
+/// Returns NULL for invalid values for time_unit
static inline const char* ArrowTimeUnitString(enum ArrowTimeUnit time_unit) {
switch (time_unit) {
case NANOARROW_TIME_UNIT_SECOND:
@@ -279,6 +320,7 @@ static inline const char* ArrowTimeUnitString(enum ArrowTimeUnit time_unit) {
}
/// \brief Functional types of buffers as described in the Arrow Columnar Specification
+/// \ingroup nanoarrow-array-view
enum ArrowBufferType {
NANOARROW_BUFFER_TYPE_NONE,
NANOARROW_BUFFER_TYPE_VALIDITY,
@@ -288,39 +330,8 @@ enum ArrowBufferType {
NANOARROW_BUFFER_TYPE_DATA
};
-#define _NANOARROW_CONCAT(x, y) x##y
-#define _NANOARROW_MAKE_NAME(x, y) _NANOARROW_CONCAT(x, y)
-
-#define _NANOARROW_RETURN_NOT_OK_IMPL(NAME, EXPR) \
- do { \
- const int NAME = (EXPR); \
- if (NAME) return NAME; \
- } while (0)
-
-#define NANOARROW_RETURN_NOT_OK(EXPR) \
- _NANOARROW_RETURN_NOT_OK_IMPL(_NANOARROW_MAKE_NAME(errno_status_, __COUNTER__), EXPR)
-
-#define _NANOARROW_CHECK_RANGE(x_, min_, max_) \
- NANOARROW_RETURN_NOT_OK((x_ >= min_ && x_ <= max_) ? NANOARROW_OK : EINVAL)
-
-/// \brief A description of an arrangement of buffers
-///
-/// Contains the minimum amount of information required to
-/// calculate the size of each buffer in an ArrowArray knowing only
-/// the length and offset of the array.
-struct ArrowLayout {
- /// \brief The function of each buffer
- enum ArrowBufferType buffer_type[3];
-
- /// \brief The size of an element each buffer or 0 if this size is variable or unknown
- int64_t element_size_bits[3];
-
- /// \brief The number of elements in the child array per element in this array for a
- /// fixed-size list
- int64_t child_size_elements;
-};
-
/// \brief An non-owning view of a string
+/// \ingroup nanoarrow-utils
struct ArrowStringView {
/// \brief A pointer to the start of the string
///
@@ -333,6 +344,8 @@ struct ArrowStringView {
int64_t n_bytes;
};
+/// \brief Return a view of a const C string
+/// \ingroup nanoarrow-utils
static inline struct ArrowStringView ArrowCharView(const char* value) {
struct ArrowStringView out;
@@ -347,6 +360,7 @@ static inline struct ArrowStringView ArrowCharView(const char* value) {
}
/// \brief An non-owning view of a buffer
+/// \ingroup nanoarrow-utils
struct ArrowBufferView {
/// \brief A pointer to the start of the buffer
///
@@ -371,6 +385,7 @@ struct ArrowBufferView {
};
/// \brief Array buffer allocation and deallocation
+/// \ingroup nanoarrow-buffer
///
/// Container for allocate, reallocate, and free methods that can be used
/// to customize allocation and deallocation of buffers when constructing
@@ -388,6 +403,7 @@ struct ArrowBufferAllocator {
};
/// \brief An owning mutable view of a buffer
+/// \ingroup nanoarrow-buffer
struct ArrowBuffer {
/// \brief A pointer to the start of the buffer
///
@@ -405,6 +421,7 @@ struct ArrowBuffer {
};
/// \brief An owning mutable view of a bitmap
+/// \ingroup nanoarrow-bitmap
struct ArrowBitmap {
/// \brief An ArrowBuffer to hold the allocated memory
struct ArrowBuffer buffer;
@@ -413,6 +430,57 @@ struct ArrowBitmap {
int64_t size_bits;
};
+/// \brief A description of an arrangement of buffers
+/// \ingroup nanoarrow-utils
+///
+/// Contains the minimum amount of information required to
+/// calculate the size of each buffer in an ArrowArray knowing only
+/// the length and offset of the array.
+struct ArrowLayout {
+ /// \brief The function of each buffer
+ enum ArrowBufferType buffer_type[3];
+
+ /// \brief The size of an element each buffer or 0 if this size is variable or unknown
+ int64_t element_size_bits[3];
+
+ /// \brief The number of elements in the child array per element in this array for a
+ /// fixed-size list
+ int64_t child_size_elements;
+};
+
+/// \brief A non-owning view of an ArrowArray
+/// \ingroup nanoarrow-array-view
+///
+/// This data structure provides access to the values contained within
+/// an ArrowArray with fields provided in a more readily-extractible
+/// form. You can re-use an ArrowArrayView for multiple ArrowArrays
+/// with the same storage type, or use it to represent a hypothetical
+/// ArrowArray that does not exist yet.
+struct ArrowArrayView {
+ /// \brief The underlying ArrowArray or NULL if it has not been set
+ struct ArrowArray* array;
+
+ /// \brief The type used to store values in this array
+ ///
+ /// This type represents only the minimum required information to
+ /// extract values from the array buffers (e.g., for a Date32 array,
+ /// this value will be NANOARROW_TYPE_INT32). For dictionary-encoded
+ /// arrays, this will be the index type.
+ enum ArrowType storage_type;
+
+ /// \brief The buffer types, strides, and sizes of this Array's buffers
+ struct ArrowLayout layout;
+
+ /// \brief This Array's buffers as ArrowBufferView objects
+ struct ArrowBufferView buffer_views[3];
+
+ /// \brief The number of children of this view
+ int64_t n_children;
+
+ /// \brief Pointers to views of this array's children
+ struct ArrowArrayView** children;
+};
+
// Used as the private data member for ArrowArrays allocated here and accessed
// internally within inline ArrowArray* helpers.
struct ArrowArrayPrivateData {
@@ -435,17 +503,6 @@ struct ArrowArrayPrivateData {
struct ArrowLayout layout;
};
-struct ArrowArrayView {
- struct ArrowArray* array;
- enum ArrowType storage_type;
- struct ArrowLayout layout;
- struct ArrowBufferView buffer_views[3];
- int64_t n_children;
- struct ArrowArrayView** children;
-};
-
-/// }@
-
#ifdef __cplusplus
}
#endif