C API Reference#

group geoarrow C library

Except where noted, objects are not thread-safe and clients should take care to serialize accesses to methods.

Because this library is intended to be vendored, it provides full type definitions and encourages clients to stack or statically allocate where convenient.

Data type creation and inspection#

group Data type creation and inspection

The ArrowSchema is the ABI-stable way to communicate type information using the Arrow C Data interface. These functions export ArrowSchema objects or parse their content into a more easily inspectable object. All unique memory layouts have a GeoArrowType identifier, most of which can be decomposed into GeoArrowGeometryType, GeoArrowDimensions, and GeoArrowCoordType.

In addition to memory layout, these functions provide a mechanism to serialize and deserialize Arrow extension type information. The serialization format is a JSON object and three keys are currently encoded: crs_type, crs, and edge_type. The embedded parser is not a complete JSON parser and in some circumstances will accept or transport invalid JSON without erroring.

Serializing extension type information into an ArrowSchema and parsing an ArrowSchema is expensive and should be avoided where possible.

Enums

enum GeoArrowType#

Type identifier for types supported by this library.

It is occasionally useful to represent each unique memory layout with a single type identifier. These types include both the serialized representations and the GeoArrow-native representations. Type identifiers for GeoArrow-native representations can be decomposed into or reconstructed from GeoArrowGeometryType, GeoArrowDimensions, and GeoArrowCoordType.

The values of this enum are chosen to support efficient decomposition and/or reconstruction into the components that make up this value; however, these values are not guaranteed to be stable.

Values:

enumerator GEOARROW_TYPE_UNINITIALIZED#

enumerator GEOARROW_TYPE_WKB#

enumerator GEOARROW_TYPE_LARGE_WKB#

enumerator GEOARROW_TYPE_WKT#

enumerator GEOARROW_TYPE_LARGE_WKT#

enumerator GEOARROW_TYPE_WKB_VIEW#

enumerator GEOARROW_TYPE_WKT_VIEW#

enumerator GEOARROW_TYPE_BOX#

enumerator GEOARROW_TYPE_BOX_Z#

enumerator GEOARROW_TYPE_BOX_M#

enumerator GEOARROW_TYPE_BOX_ZM#

enumerator GEOARROW_TYPE_POINT#

enumerator GEOARROW_TYPE_LINESTRING#

enumerator GEOARROW_TYPE_POLYGON#

enumerator GEOARROW_TYPE_MULTIPOINT#

enumerator GEOARROW_TYPE_MULTILINESTRING#

enumerator GEOARROW_TYPE_MULTIPOLYGON#

enumerator GEOARROW_TYPE_POINT_Z#

enumerator GEOARROW_TYPE_LINESTRING_Z#

enumerator GEOARROW_TYPE_POLYGON_Z#

enumerator GEOARROW_TYPE_MULTIPOINT_Z#

enumerator GEOARROW_TYPE_MULTILINESTRING_Z#

enumerator GEOARROW_TYPE_MULTIPOLYGON_Z#

enumerator GEOARROW_TYPE_POINT_M#

enumerator GEOARROW_TYPE_LINESTRING_M#

enumerator GEOARROW_TYPE_POLYGON_M#

enumerator GEOARROW_TYPE_MULTIPOINT_M#

enumerator GEOARROW_TYPE_MULTILINESTRING_M#

enumerator GEOARROW_TYPE_MULTIPOLYGON_M#

enumerator GEOARROW_TYPE_POINT_ZM#

enumerator GEOARROW_TYPE_LINESTRING_ZM#

enumerator GEOARROW_TYPE_POLYGON_ZM#

enumerator GEOARROW_TYPE_MULTIPOINT_ZM#

enumerator GEOARROW_TYPE_MULTILINESTRING_ZM#

enumerator GEOARROW_TYPE_MULTIPOLYGON_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_POINT#

enumerator GEOARROW_TYPE_INTERLEAVED_LINESTRING#

enumerator GEOARROW_TYPE_INTERLEAVED_POLYGON#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOINT#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTILINESTRING#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOLYGON#

enumerator GEOARROW_TYPE_INTERLEAVED_POINT_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_LINESTRING_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_POLYGON_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOINT_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTILINESTRING_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOLYGON_Z#

enumerator GEOARROW_TYPE_INTERLEAVED_POINT_M#

enumerator GEOARROW_TYPE_INTERLEAVED_LINESTRING_M#

enumerator GEOARROW_TYPE_INTERLEAVED_POLYGON_M#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOINT_M#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTILINESTRING_M#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOLYGON_M#

enumerator GEOARROW_TYPE_INTERLEAVED_POINT_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_LINESTRING_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_POLYGON_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOINT_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTILINESTRING_ZM#

enumerator GEOARROW_TYPE_INTERLEAVED_MULTIPOLYGON_ZM#

enum GeoArrowGeometryType#

Geometry type identifiers supported by GeoArrow.

The values of this enum are intentionally chosen to be equivalent to well-known binary type identifiers.

Values:

enumerator GEOARROW_GEOMETRY_TYPE_GEOMETRY#

enumerator GEOARROW_GEOMETRY_TYPE_POINT#

enumerator GEOARROW_GEOMETRY_TYPE_LINESTRING#

enumerator GEOARROW_GEOMETRY_TYPE_POLYGON#

enumerator GEOARROW_GEOMETRY_TYPE_MULTIPOINT#

enumerator GEOARROW_GEOMETRY_TYPE_MULTILINESTRING#

enumerator GEOARROW_GEOMETRY_TYPE_MULTIPOLYGON#

enumerator GEOARROW_GEOMETRY_TYPE_GEOMETRYCOLLECTION#

enumerator GEOARROW_GEOMETRY_TYPE_BOX#

enum GeoArrowDimensions#

Dimension combinations supported by GeoArrow.

Values:

enumerator GEOARROW_DIMENSIONS_UNKNOWN#

enumerator GEOARROW_DIMENSIONS_XY#

enumerator GEOARROW_DIMENSIONS_XYZ#

enumerator GEOARROW_DIMENSIONS_XYM#

enumerator GEOARROW_DIMENSIONS_XYZM#

enum GeoArrowCoordType#

Coordinate types supported by GeoArrow.

Values:

enumerator GEOARROW_COORD_TYPE_UNKNOWN#

enumerator GEOARROW_COORD_TYPE_SEPARATE#

enumerator GEOARROW_COORD_TYPE_INTERLEAVED#

enum GeoArrowEdgeType#

Edge types/interpolations supported by GeoArrow.

Values:

enumerator GEOARROW_EDGE_TYPE_PLANAR#

enumerator GEOARROW_EDGE_TYPE_SPHERICAL#

enumerator GEOARROW_EDGE_TYPE_VINCENTY#

enumerator GEOARROW_EDGE_TYPE_THOMAS#

enumerator GEOARROW_EDGE_TYPE_ANDOYER#

enumerator GEOARROW_EDGE_TYPE_KARNEY#

enum GeoArrowCrsType#

Coordinate reference system types supported by GeoArrow.

Values:

enumerator GEOARROW_CRS_TYPE_NONE#

enumerator GEOARROW_CRS_TYPE_UNKNOWN#

enumerator GEOARROW_CRS_TYPE_PROJJSON#

enumerator GEOARROW_CRS_TYPE_WKT2_2019#

enumerator GEOARROW_CRS_TYPE_AUTHORITY_CODE#

enumerator GEOARROW_CRS_TYPE_SRID#

Functions

GeoArrowErrorCode GeoArrowSchemaInit(struct ArrowSchema *schema, enum GeoArrowType type)#: Initialize an ArrowSchema with a geoarrow storage type.

GeoArrowErrorCode GeoArrowSchemaInitExtension(struct ArrowSchema *schema, enum GeoArrowType type)#: Initialize an ArrowSchema with a geoarrow extension type.

GeoArrowErrorCode GeoArrowSchemaViewInit(struct GeoArrowSchemaView *schema_view, const struct ArrowSchema *schema, struct GeoArrowError *error)#: Parse an ArrowSchema extension type into a GeoArrowSchemaView.

GeoArrowErrorCode GeoArrowSchemaViewInitFromStorage(struct GeoArrowSchemaView *schema_view, const struct ArrowSchema *schema, struct GeoArrowStringView extension_name, struct GeoArrowError *error)#: Parse an ArrowSchema storage type into a GeoArrowSchemaView.

GeoArrowErrorCode GeoArrowSchemaViewInitFromType(struct GeoArrowSchemaView *schema_view, enum GeoArrowType type)#: Initialize a GeoArrowSchemaView directly from a GeoArrowType identifier.

GeoArrowErrorCode GeoArrowMetadataViewInit(struct GeoArrowMetadataView *metadata_view, struct GeoArrowStringView metadata, struct GeoArrowError *error)#: Initialize a GeoArrowSchemaView directly from a GeoArrowType identifier.

int64_t GeoArrowMetadataSerialize(const struct GeoArrowMetadataView *metadata_view, char *out, int64_t n)#: Serialize parsed metadata into JSON.

GeoArrowErrorCode GeoArrowSchemaSetMetadata(struct ArrowSchema *schema, const struct GeoArrowMetadataView *metadata_view)#: Update extension metadata associated with an existing ArrowSchema.

GeoArrowErrorCode GeoArrowSchemaSetMetadataFrom(struct ArrowSchema *schema, const struct ArrowSchema *schema_src)#: Update extension metadata associated with an existing ArrowSchema based on the extension metadata of another.

void GeoArrowMetadataSetLonLat(struct GeoArrowMetadataView *metadata_view)#: Set a GeoArrowMetadatView with the Crs definition of OGC:CRS84, the most commonly used CRS definition for longitude/latitude.

int64_t GeoArrowUnescapeCrs(struct GeoArrowStringView crs, char *out, int64_t n)#

Unescape a coordinate reference system value.

The crs member of the GeoArrowMetadataView is a view into the extension metadata; however, in some cases this will be a quoted string (i.e., "OGC:CRS84") and in others it will be a JSON object (i.e., PROJJSON like {"some key": "some value", ..}). When passing this string elsewhere, you will almost always want the quoted value to be unescaped (i.e., the JSON string value), but the JSON object to remain as-is. GeoArrowUnescapeCrs() performs this logic based on the value of the first character.

static inline enum GeoArrowGeometryType GeoArrowGeometryTypeFromType(enum GeoArrowType type)#: Extract GeometryType from a GeoArrowType.

static inline const char *GeoArrowExtensionNameFromType(enum GeoArrowType type)#: Returns the Arrow extension name for a given GeoArrowType.

static inline const char *GeoArrowDimensionsString(enum GeoArrowDimensions dimensions)#: Returns a string representation of a GeoArrowDimensions.

static inline const char *GeoArrowCoordTypeString(enum GeoArrowCoordType dimensions)#: Returns a string representation of a GeoArrowCoordType.

static inline const char *GeoArrowEdgeTypeString(enum GeoArrowEdgeType edge_type)#: Returns a string representation of a GeoArrowEdgeType.

static inline const char *GeoArrowCrsTypeString(enum GeoArrowCrsType crs_type)#: Returns a string representation of a GeoArrowCrsType.

static inline enum GeoArrowDimensions GeoArrowDimensionsFromType(enum GeoArrowType type)#: Extract GeoArrowDimensions from a GeoArrowType.

static inline enum GeoArrowCoordType GeoArrowCoordTypeFromType(enum GeoArrowType type)#: Extract GeoArrowCoordType from a GeoArrowType.

static inline enum GeoArrowType GeoArrowMakeType(enum GeoArrowGeometryType geometry_type, enum GeoArrowDimensions dimensions, enum GeoArrowCoordType coord_type)#: Construct a GeometryType from a GeoArrowGeometryType, GeoArrowDimensions, and GeoArrowCoordType.

static inline const char *GeoArrowGeometryTypeString(enum GeoArrowGeometryType geometry_type)#: The all-caps string associated with a given GeometryType (e.g., POINT)

Array inspection#

group Array inspection

The GeoArrowArrayView is the primary means by which an ArrowArray of a valid type can be inspected. The GeoArrowArrayView is intended to be initialized once for a given type and re-used for multiple arrays (e.g., in a stream).

Defines

GEOARROW_COORD_VIEW_VALUE(coords_, row_, col_)#: Generically get or set an ordinate from a GeoArrowWritableCoordView or a GeoArrowCoordView.

Functions

GeoArrowErrorCode GeoArrowArrayViewInitFromType(struct GeoArrowArrayView *array_view, enum GeoArrowType type)#: Initialize a GeoArrowArrayView from a GeoArrowType identifier.

GeoArrowErrorCode GeoArrowArrayViewInitFromSchema(struct GeoArrowArrayView *array_view, const struct ArrowSchema *schema, struct GeoArrowError *error)#: Initialize a GeoArrowArrayView from an ArrowSchema.

GeoArrowErrorCode GeoArrowArrayViewSetArray(struct GeoArrowArrayView *array_view, const struct ArrowArray *array, struct GeoArrowError *error)#: Populate the members of the GeoArrowArrayView from an ArrowArray.

struct GeoArrowCoordView#

#include <geoarrow_type.h>

A generic view of coordinates from a GeoArrow array.

This view is capable of representing both struct and interleaved coordinates. Use GEOARROW_COORD_VIEW_VALUE() to generically access an ordinate.

Public Members

const double *values[8]#

Pointers to the beginning of each coordinate buffer.

May be NULL if n_coords is 0. For interleaved coordinates, these will point to the first n_values elements of the same buffer.

int64_t n_coords#: The number of coordinates in this view.

int32_t n_values#: The number of pointers in the values array (i.e., number of dimensions)

int32_t coords_stride#

The number of elements to advance a given value pointer to the next ordinate.

For interleaved coordinates, coords_stride will equal n_values; for struct coordinates, coords_stride will be 1.

struct GeoArrowArrayView#

#include <geoarrow_type.h>

A parsed view of memory from a GeoArrow-encoded array.

This definition may change to more closely match the GeoArrowWritableArrayView in the future.

Public Members

struct GeoArrowSchemaView schema_view#: Type information for the array represented by this view.

int64_t offset[4]#: The logical offset to apply into each level of nesting.

int64_t length[4]#: The number of elements in each level of nesting.

const uint8_t *validity_bitmap#: The validity bitmap for this array.

int32_t n_offsets#: The number of offset buffers for the type represented by this array.

const int32_t *offsets[3]#: Pointers to the beginning of each offset buffer.

int32_t first_offset[3]#: The first offset value in each offset buffer.

int32_t last_offset[3]#: The last offset value in each offset buffer.

const uint8_t *data#: For serialized types, a pointer to the start of the data buffer.

struct GeoArrowCoordView coords#: Generic view of the coordinates in this array.

Array creation#

group Array creation

The GeoArrowBuilder supports creating GeoArrow-encoded arrays. There are three ways to do so:

Build the individual buffers yourself and transfer ownership to the array for each using GeoArrowBuilderSetOwnedBuffer()
Append the appropriate values to each buffer in-place using GeoArrowBuilderAppendBuffer()
Use GeoArrowBuilderInitVisitor() and let the visitor build the buffers for you.

For all methods you can re-use the builder object for multiple batches and call GeoArrowBuilderFinish() multiple times. You should use the same mechanism for building an array when reusing a builder object.

The GeoArrowBuilder models GeoArrow arrays as a sequence of buffers numbered from the outer array inwards. The 0th buffer is always the validity buffer and can be omitted for arrays that contain no null features. This is followed by between 0 (point) and 3 (multipolygon) int32 offset buffers and between 1 (interleaved) and 4 (xyzm struct) double buffers representing coordinate values. The GeoArrowBuilder omits validity buffers for inner arrays since the GeoArrow specification states that these arrays must contain zero nulls.

Functions

GeoArrowErrorCode GeoArrowBuilderInitFromType(struct GeoArrowBuilder *builder, enum GeoArrowType type)#: Initialize memory for a GeoArrowBuilder based on a GeoArrowType identifier.

GeoArrowErrorCode GeoArrowBuilderInitFromSchema(struct GeoArrowBuilder *builder, const struct ArrowSchema *schema, struct GeoArrowError *error)#: Initialize memory for a GeoArrowBuilder based on an ArrowSchema.

GeoArrowErrorCode GeoArrowBuilderReserveBuffer(struct GeoArrowBuilder *builder, int64_t i, int64_t additional_size_bytes)#: Reserve additional space for a buffer in a GeoArrowBuilder.

static inline void GeoArrowBuilderAppendBufferUnsafe(struct GeoArrowBuilder *builder, int64_t i, struct GeoArrowBufferView value)#: Append data to a buffer in a GeoArrowBuilder without checking if a reserve is needed.

static inline GeoArrowErrorCode GeoArrowBuilderAppendBuffer(struct GeoArrowBuilder *builder, int64_t i, struct GeoArrowBufferView value)#: Append data to a buffer in a GeoArrowBuilder.

GeoArrowErrorCode GeoArrowBuilderSetOwnedBuffer(struct GeoArrowBuilder *builder, int64_t i, struct GeoArrowBufferView value, void (*custom_free)(uint8_t *ptr, int64_t size, void *private_data), void *private_data)#: Replace a buffer with one whose lifecycle is externally managed.

GeoArrowErrorCode GeoArrowBuilderFinish(struct GeoArrowBuilder *builder, struct ArrowArray *array, struct GeoArrowError *error)#

Finish an ArrowArray containing the built input.

This function can be called more than once to support multiple batches.

void GeoArrowBuilderReset(struct GeoArrowBuilder *builder)#: Free resources held by a GeoArrowBuilder.

union GeoArrowWritableBufferViewData#

#include <geoarrow_type.h>

Union type representing a pointer to modifiable data.

Public Members

void *data#

char *as_char#

uint8_t *as_uint8#

int32_t *as_int32#

double *as_double#

struct GeoArrowWritableBufferView#

#include <geoarrow_type.h>

A view of a modifiable buffer.

Public Members

union GeoArrowWritableBufferViewData data#: Pointer to the beginning of the data. May be NULL if capacity_bytes is 0.

int64_t size_bytes#: The size of the buffer in bytes.

int64_t capacity_bytes#: The modifiable capacity of the buffer in bytes.

struct GeoArrowWritableArrayView#

#include <geoarrow_type.h>

Structured view of writable memory managed by the GeoArrowBuilder.

Public Members

struct GeoArrowSchemaView schema_view#: Type information for the array being built.

int64_t length#: The number of elements that have been added to this array.

int64_t n_buffers#: The number of buffers required to represent this type.

int32_t n_offsets#: The number of offset buffers for the array being built.

struct GeoArrowWritableBufferView buffers[9]#: Views into writable memory managed by the GeoArrowBuilder.

struct GeoArrowWritableCoordView coords#: View of writable coordinate memory managed by the GeoArrowBuilder.

struct GeoArrowBuilder#

#include <geoarrow_type.h>

Builder for GeoArrow-encoded arrays.

Public Members

struct GeoArrowWritableArrayView view#: Structured view of the memory managed privately in private_data.

void *private_data#: Implementation-specific data.

Transform arrays#

group Transform Arrays

The GeoArrow C library provides limited support for transforming arrays. Notably, it provides support for parsing WKT and WKB into GeoArrow native encoding and serializing GeoArrow arrays to WKT and/or WKB.

The GeoArrowKernel is a generalization of the compute operations available in this build of the GeoArrow C library. Two types of kernels are implemented: scalar and aggregate. Scalar kernels always output an ArrowArray of the same length as the input from push_batch() and do not output an ArrowArray from finish(); aggregate kernels do not output an ArrowArray from push_batch() and output a single ArrowArray from finish() with no constraint on the length of the array that is produced. For both kernel types, the ArrowSchema of the output is returned by the start() method, where options (serialized in the same form as the ArrowSchema metadata member) can also be passed. Current implementations do not validate options except to the extent needed to avoid a crash.

This is intended to minimize the number of patterns needed in wrapper code rather than be a perfect abstraction of a compute function. Similarly, these kernels are optimized for type coverage rather than performance.

void: Scalar kernel that outputs a null array of the same length as the input for each batch.
void_agg: Aggregate kernel that outputs a null array of length 1 for any number of inputs.
visit_void_agg: Aggregate kernel that visits every coordinate of every feature of the input, outputting a null array of length 1 for any number of inputs. This is useful for validating well-known text and well-known binary as it will error for input that cannot be visited completely.
as_wkt: Scalar kernel that outputs the well-known text version of the input as faithfully as possible (including transferring metadata from the input). Arrays with valid GeoArrowTypes are supported.
as_wkb: Scalar kernel that outputs the well-known binary version of the input as faithfully as possible (including transferring metadata from the input). Arrays with valid GeoArrowTypes are supported.
as_geoarrow: Scalar kernel that outputs the GeoArrow version of the input as faithfully as possible (including transferring metadata from the input). Arrays with valid GeoArrowTypes are supported. The type of the output is controlled by the type option, specified as a GeoArrowType cast to integer.
format_wkt: A variation on as_wkt that supports options precision and max_element_size_bytes. This kernel is lazy and does not visit an entire feature beyond that required for max_element_size_bytes.
unique_geometry_types_agg: An aggregate kernel that collects unique geometry types in the input. The output is a single int32 array of ISO WKB type codes.
box: A scalar kernel that returns the 2-dimensional bounding box by feature. the output bounding box is represented as a struct array with column order xmin, xmax, ymin, ymax. Null features are recorded as a null item in the output; empty features are recorded as Inf, -Inf, Inf, -Inf.
box_agg: An aggregate kernel that returns the 2-dimensional bounding box containing all features of the input in the same form as the box kernel. the result is always length one and is never null. For the purposes of this kernel, nulls are treated as empty.

Functions

GeoArrowErrorCode GeoArrowKernelInit(struct GeoArrowKernel *kernel, const char *name, const char *options)#

Initialize memory for a GeoArrowKernel.

If GEOARROW_OK is returned, the caller is responsible for calling the embedded release callback to free any resources that were allocated.

Low-level reader/visitor interfaces#

group Low-level reader/visitor interfaces

The GeoArrow specification defines memory layouts for many types. Whereas it is more performant to write dedicated conversions between each source and destination type, the number of conversions required prohibits a compact and maintainable general-purpose library.

Instead, we define the GeoArrowVisitor and provide a means by which to “visit” each feature in an array of geometries for every supported type. Conversely, we provide a GeoArrowVisitor implementation to create arrays of each supported type upon visitation of an arbitrary source. This design also facilitates reusing the readers and writers provided here by other libraries.

Functions

void GeoArrowVisitorInitVoid(struct GeoArrowVisitor *v)#: Initialize a GeoArrowVisitor with a visitor that does nothing.

GeoArrowErrorCode GeoArrowArrayViewVisitNative(const struct GeoArrowArrayView *array_view, int64_t offset, int64_t length, struct GeoArrowVisitor *v)#

Visit the features of a native GeoArrowArrayView.

The caller must have initialized the GeoArrowVisitor with the appropriate writer before calling this function. This only works with GeoArrowArrayView instances pointing to native arrays, even though the GeoArrowArrayView can handle other types of arrays. Use the GeoArrowArrayReader for arbitrary input.

GeoArrowErrorCode GeoArrowNativeWriterInit(struct GeoArrowNativeWriter *writer, enum GeoArrowType type)#

Initialize the memory of a GeoArrowNativeWriter.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowNativeWriterReset().

GeoArrowErrorCode GeoArrowNativeWriterInitVisitor(struct GeoArrowNativeWriter *writer, struct GeoArrowVisitor *v)#: Populate a GeoArrowVisitor pointing to this writer.

GeoArrowErrorCode GeoArrowNativeWriterFinish(struct GeoArrowNativeWriter *writer, struct ArrowArray *array, struct GeoArrowError *error)#

Finish an ArrowArray containing elements from the visited input.

This function can be called more than once to support multiple batches.

void GeoArrowNativeWriterReset(struct GeoArrowNativeWriter *writer)#: Free resources held by a GeoArrowNativeWriter.

GeoArrowErrorCode GeoArrowWKTWriterInit(struct GeoArrowWKTWriter *writer)#

Initialize the memory of a GeoArrowWKTWriter.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKTWriterReset().

void GeoArrowWKTWriterInitVisitor(struct GeoArrowWKTWriter *writer, struct GeoArrowVisitor *v)#: Populate a GeoArrowVisitor pointing to this writer.

GeoArrowErrorCode GeoArrowWKTWriterFinish(struct GeoArrowWKTWriter *writer, struct ArrowArray *array, struct GeoArrowError *error)#

Finish an ArrowArray containing elements from the visited input.

This function can be called more than once to support multiple batches.

void GeoArrowWKTWriterReset(struct GeoArrowWKTWriter *writer)#: Free resources held by a GeoArrowWKTWriter.

GeoArrowErrorCode GeoArrowWKTReaderInit(struct GeoArrowWKTReader *reader)#

Initialize the memory of a GeoArrowWKTReader.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKTReaderReset().

GeoArrowErrorCode GeoArrowWKTReaderVisit(struct GeoArrowWKTReader *reader, struct GeoArrowStringView s, struct GeoArrowVisitor *v)#

Visit well-known text.

The caller must have initialized the GeoArrowVisitor with the appropriate writer before calling this function.

void GeoArrowWKTReaderReset(struct GeoArrowWKTReader *reader)#: Free resources held by a GeoArrowWKTReader.

GeoArrowErrorCode GeoArrowWKBWriterInit(struct GeoArrowWKBWriter *writer)#

Initialize the memory of a GeoArrowWKBWriter.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKBWriterReset().

void GeoArrowWKBWriterInitVisitor(struct GeoArrowWKBWriter *writer, struct GeoArrowVisitor *v)#: Populate a GeoArrowVisitor pointing to this writer.

GeoArrowErrorCode GeoArrowWKBWriterFinish(struct GeoArrowWKBWriter *writer, struct ArrowArray *array, struct GeoArrowError *error)#

Finish an ArrowArray containing elements from the visited input.

This function can be called more than once to support multiple batches.

void GeoArrowWKBWriterReset(struct GeoArrowWKBWriter *writer)#: Free resources held by a GeoArrowWKBWriter.

GeoArrowErrorCode GeoArrowWKBReaderInit(struct GeoArrowWKBReader *reader)#

Initialize the memory of a GeoArrowWKBReader.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKBReaderReset().

GeoArrowErrorCode GeoArrowWKBReaderVisit(struct GeoArrowWKBReader *reader, struct GeoArrowBufferView src, struct GeoArrowVisitor *v)#

Visit well-known binary.

The caller must have initialized the GeoArrowVisitor with the appropriate writer before calling this function.

GeoArrowErrorCode GeoArrowWKBReaderRead(struct GeoArrowWKBReader *reader, struct GeoArrowBufferView src, struct GeoArrowGeometryView *out, struct GeoArrowError *error)#

void GeoArrowWKBReaderReset(struct GeoArrowWKBReader *reader)#: Free resources held by a GeoArrowWKBWriter.

GeoArrowErrorCode GeoArrowArrayReaderInitFromType(struct GeoArrowArrayReader *reader, enum GeoArrowType type)#

Initialize a GeoArrowArrayReader from a GeoArrowType.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowArrayReaderReset().

GeoArrowErrorCode GeoArrowArrayReaderInitFromSchema(struct GeoArrowArrayReader *reader, const struct ArrowSchema *schema, struct GeoArrowError *error)#

Initialize a GeoArrowArrayReader from an ArrowSchema.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowArrayReaderReset().

GeoArrowErrorCode GeoArrowArrayReaderSetArray(struct GeoArrowArrayReader *reader, const struct ArrowArray *array, struct GeoArrowError *error)#: Set a GeoArrowArray to read.

GeoArrowErrorCode GeoArrowArrayReaderVisit(struct GeoArrowArrayReader *reader, int64_t offset, int64_t length, struct GeoArrowVisitor *v)#

Visit a GeoArrowArray.

The caller must have initialized the GeoArrowVisitor with the appropriate writer before calling this function.

GeoArrowErrorCode GeoArrowArrayReaderArrayView(struct GeoArrowArrayReader *reader, const struct GeoArrowArrayView **out)#

Get a GeoArrowArrayView.

If there is a GeoArrowArrayView underlying this GeoArrowArrayReader, populates out with the internal pointer. Returns an error code if there is no GeoArrowArrayView corresponding to this array.

void GeoArrowArrayReaderReset(struct GeoArrowArrayReader *reader)#: Free resources held by a GeoArrowArrayReader.

GeoArrowErrorCode GeoArrowArrayWriterInitFromType(struct GeoArrowArrayWriter *writer, enum GeoArrowType type)#

Initialize the memory of a GeoArrowArrayWriter from a GeoArrowType.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKTWriterReset().

GeoArrowErrorCode GeoArrowArrayWriterInitFromSchema(struct GeoArrowArrayWriter *writer, const struct ArrowSchema *schema)#

Initialize the memory of a GeoArrowArrayWriter from an ArrowSchema.

If GEOARROW_OK is returned, the caller is responsible for calling GeoArrowWKTWriterReset().

GeoArrowErrorCode GeoArrowArrayWriterSetPrecision(struct GeoArrowArrayWriter *writer, int precision)#

Set the precision to use for array writers writing to WKT.

Returns EINVAL for precision values that are not valid or if the writer is not writing to WKT. Must be called before GeoArrowArrayWriterInitVisitor(). The default precision value is 16. See GeoArrowWKTWriter for details.

GeoArrowErrorCode GeoArrowArrayWriterSetFlatMultipoint(struct GeoArrowArrayWriter *writer, int flat_multipoint)#

Set the MULTIPOINT output mode when writing to WKT.

Returns EINVAL if the writer is not writing to WKT. Must be called before GeoArrowArrayWriterInitVisitor(). The default value is 1. See GeoArrowWKTWriter for details.

GeoArrowErrorCode GeoArrowArrayWriterInitVisitor(struct GeoArrowArrayWriter *writer, struct GeoArrowVisitor *v)#: Populate a GeoArrowVisitor pointing to this writer.

GeoArrowErrorCode GeoArrowArrayWriterFinish(struct GeoArrowArrayWriter *writer, struct ArrowArray *array, struct GeoArrowError *error)#

Finish an ArrowArray containing elements from the visited input.

This function can be called more than once to support multiple batches.

void GeoArrowArrayWriterReset(struct GeoArrowArrayWriter *writer)#: Free resources held by a GeoArrowArrayWriter.

struct GeoArrowNativeWriter#

#include <geoarrow.h>

GeoArrow native array writer.

This writer writes the “native” memory layouts (i.e., nested lists of coordinates) implemented as a visitor.

Public Members

void *private_data#: Implementation-specific details.

struct GeoArrowWKTWriter#

#include <geoarrow.h>

Well-known text writer.

This struct also contains options for well-known text serialization. These options can be modified from the defaults after GeoArrowWKTWriterInit() and before GeoArrowWKTWriterInitVisitor().

Note that whether or not GeoArrow was compiled with ryu has a significant impact on the output: notably, ryu is locale-independent and much faster. GeoArrow can fall back on using snprintf(); however, this will result in invalid WKT for locales other than the C locale.

Public Members

int precision#: The number of significant digits to include in the output (default: 16)

int use_flat_multipoint#: Set to 0 to use the verbose (but more valid) MULTIPOINT representation (i.e., MULTIPOINT((0 1), (2 3)))). Defaults to 1 (because this was the default GEOS behaviour at the time this was written).

int64_t max_element_size_bytes#

Constrain the maximum size of each element in the returned array.

Use -1 to denote an unlimited size for each element. When the limit is reached or shortly after, the called handler method will return EAGAIN, after which it is safe to call feat_end to end the feature. This ensures that a finite amount of input is consumed if this elemtn is set.

void *private_data#: Implementation-specific details.

struct GeoArrowWKTReader#: #include <geoarrow.h>

Well-known text reader.

struct GeoArrowWKBWriter#

#include <geoarrow.h>

ISO well-known binary writer.

Public Members

void *private_data#: Implmentation-specific data.

struct GeoArrowWKBReader#

#include <geoarrow.h>

Well-known binary (ISO or EWKB) reader.

Public Members

void *private_data#: Implmentation-specific data.

struct GeoArrowArrayReader#: #include <geoarrow.h>

Array reader for any geoarrow extension array.

struct GeoArrowArrayWriter#: #include <geoarrow.h>

Generc GeoArrow array writer.

struct GeoArrowVisitor#

#include <geoarrow_type.h>

Visitor for an array of geometries.

A structure of function pointers and implementation-specific data used to allow geometry input from an abstract source. The visitor itself does not have a release callback and is not responsible for the lifecycle of any of its members. The order of method calls is essentially the same as the order these pieces of information would be encountered when parsing well-known text or well-known binary.

Implementations should perform enough checks to ensure that they do not crash if a reader calls its methods in an unexpected order; however, they are free to generate non-sensical output in this case.

For example: visiting the well-known text “MULTIPOINT (0 1, 2 3)” would result in the following visitor calls:

feat_start
geom_start(GEOARROW_GEOMETRY_TYPE_MULTIPOINT, GEOARROW_DIMENSIONS_XY)
geom_start(GEOARROW_GEOMETRY_TYPE_POINT, GEOARROW_DIMENSIONS_XY)
coords(0 1)
geom_end()
geom_start(GEOARROW_GEOMETRY_TYPE_POINT, GEOARROW_DIMENSIONS_XY)
coords(2 3)
geom_end()
geom_end()
feat_end()

Most visitor implementations consume the entire input; however, some return early once they have all the information they need to compute a value for a given feature. In this case, visitors return EAGAIN and readers must pass this value back to the caller who in turn must provide a call to feat_end() to finish the feature.

Public Members

int (*feat_start)(struct GeoArrowVisitor *v)#: Called when starting to iterate over a new feature.

int (*null_feat)(struct GeoArrowVisitor *v)#: Called after feat_start for a null_feature.

int (*geom_start)(struct GeoArrowVisitor *v, enum GeoArrowGeometryType geometry_type, enum GeoArrowDimensions dimensions)#

Called after feat_start for a new geometry.

Every non-null feature will have at least one call to geom_start. Collections (including multi-geometry types) will have nested calls to geom_start.

int (*ring_start)(struct GeoArrowVisitor *v)#: For polygon geometries, called after geom_start at the beginning of a ring.

int (*coords)(struct GeoArrowVisitor *v, const struct GeoArrowCoordView *coords)#

Called when a sequence of coordinates is encountered.

This callback may be called more than once (i.e., readers are free to chunk coordinates however they see fit). The GeoArrowCoordView may represent either interleaved of struct coordinates depending on the reader implementation.

int (*ring_end)(struct GeoArrowVisitor *v)#

For polygon geometries, called at the end of a ring.

Every call to ring_start must have a matching call to ring_end

int (*geom_end)(struct GeoArrowVisitor *v)#

Called at the end of a geometry.

Every call to geom_start must have a matching call to geom_end.

int (*feat_end)(struct GeoArrowVisitor *v)#

Called at the end of a feature, including null features.

Every call to feat_start must have a matching call to feat_end.

void *private_data#: Opaque visitor-specific data.

struct GeoArrowError *error#

The error into which the reader and/or visitor can place a detailed message.

When a visitor is initializing callbacks and private_data it should take care to not change the value of error. This value can be NULL.

Utilities and error handling#

group Utilities and error handling

The geoarrow C library follows the same error idioms as the nanoarrow C library: GEOARROW_OK is returned on success, and a GeoArrowError is populated with a null-terminated error message otherwise if there is an opportunity to provide one. The provided GeoArrowError can always be NULL if a detailed message is not important to the caller. Pointer output arguments are not modified unless GEOARROW_OK is returned.

Defines

GEOARROW_OK#: Return code for success.

GEOARROW_RETURN_NOT_OK(EXPR)#: Macro helper for error handling.

Typedefs

typedef int GeoArrowErrorCode#: Represents an errno-compatible error code.

Functions

const char *GeoArrowVersion(void)#: Return a version string in the form “major.minor.patch”.

int GeoArrowVersionInt(void)#: Return an integer that can be used to compare versions sequentially.

GeoArrowErrorCode GeoArrowErrorSet(struct GeoArrowError *error, const char *fmt, ...)#: Populate a GeoArrowError using a printf-style format string.

GeoArrowErrorCode GeoArrowFromChars(const char *first, const char *last, double *out)#: Parse a string into a double.

int64_t GeoArrowPrintDouble(double f, uint32_t precision, char *result)#: Print a double to a buffer.

struct GeoArrowStringView#

#include <geoarrow_type.h>

A read-only view of a string.

Public Members

const char *data#: Pointer to the beginning of the string. May be NULL if size_bytes is 0. there is no requirement that the string is null-terminated.

int64_t size_bytes#: The size of the string in bytes.

struct GeoArrowBufferView#

#include <geoarrow_type.h>

A read-only view of a buffer.

Public Members

const uint8_t *data#: Pointer to the beginning of the string. May be NULL if size_bytes is 0.

int64_t size_bytes#: The size of the buffer in bytes.

C API Reference#

Data type creation and inspection#

Array inspection#

Array creation#

Transform arrays#

Low-level reader/visitor interfaces#

Utilities and error handling#

This Page