Dynamically typed array encapsulating an Arrow layout. More...

#include <array_api.hpp>

Public Types
using	size_type = std::size_t

using	value_type = array_traits::value_type

using	const_reference = array_traits::const_reference

using	const_iterator = array_const_iterator

using	iterator = const_iterator

template<class F>
using	visit_result_t = std::invoke_result_t<F, null_array>

Public Member Functions
	array ()=default
	Constructs an empty array.

template<layout A> requires (not std::is_lvalue_reference_v<A>)
constexpr	array (A &&a)
	Constructs an Array from the given typed layout.

template<layout A>
constexpr	array (A *a)
	Constructs an Array from the given typed layout.

template<layout A>
constexpr	array (std::shared_ptr< A > a)
	Constructs an Array from the given typed layout.

SPARROW_API	array (ArrowArray &&array, ArrowSchema &&schema)
	Constructs an Array from the given Arrow C structures, whose ownership is transferred to the Array.

SPARROW_API	array (ArrowArray &&array, ArrowSchema *schema)
	Constructs an Array from the given Arrow C structures.

SPARROW_API	array (ArrowArray array, ArrowSchema schema)
	Constructs an array from the given Arrow C structures.

constexpr	array (const array &rhs)=default
	Performs a deep copy of the given array, even if it does not have the ownership of its internal data.

array &	operator= (const array &rhs)=default
	Overwrites the content of the array with a deep copy of the given array, even if it does not have the ownership of its internal data.

	array (array &&rhs)=default
	The move constructor.

array &	operator= (array &&rhs)=default
	The move assignment operator.

SPARROW_API enum data_type	data_type () const

SPARROW_API std::optional< array >	dictionary () const
	Retrieves the dictionary array associated with this array, if it exists.

auto	children () const

SPARROW_API std::optional< std::string_view >	name () const

SPARROW_API void	set_name (std::optional< std::string_view > name)
	Sets the name of the array to name.

SPARROW_API std::optional< key_value_view >	metadata () const

template<input_metadata_container R = std::vector<metadata_pair>>
constexpr void	set_metadata (std::optional< R > metadata)
	Sets the metadata of the array to metadata.

SPARROW_API bool	empty () const
	Checks if the array has no element, i.e.

SPARROW_API size_type	size () const

SPARROW_API size_type	offset () const

SPARROW_API std::int64_t	null_count () const

SPARROW_API const_reference	at (size_type index) const

SPARROW_API const_reference	operator[] (size_type index) const

SPARROW_API const_reference	front () const
	Returns a constant reference to the first element in the container.

SPARROW_API const_reference	back () const
	Returns a constant reference to the last element in the container.

SPARROW_API iterator	begin () const
	Returns an iterator to the beginning of the array.

SPARROW_API iterator	end () const
	Returns an iterator to the end of the array.

SPARROW_API const_iterator	cbegin () const
	Returns a constant iterator to the beginning of the array.

SPARROW_API const_iterator	cend () const
	Returns a constant iterator to the end of the array.

template<class F>
constexpr visit_result_t< F >	visit (F &&func) const
	Returns the result of calling the given functor `func` on the layout internally held by the array.

SPARROW_API array	view () const
	Returns a view of the array.

SPARROW_API bool	is_view () const
	Checks if the array is a view.

SPARROW_API bool	is_dictionary () const

SPARROW_API array	slice (size_type start, size_type end) const
	Returns a deep-copy of the array restricted to the elements in the half-open range [`start`, `end`).

SPARROW_API array	slice_view (size_type start, size_type end) const
	Returns a zero-copy view of the array restricted to the elements in the half-open range [`start`, `end`).

SPARROW_API void	slice_inplace (size_type start, size_type end)
	Restricts `*this` to the elements in the half-open range [`start`, `end`) in place.

SPARROW_API iterator	insert (const_iterator pos, const_iterator first, const_iterator last)
	Inserts elements from the range [first, last) before the element at the specified position.

SPARROW_API iterator	insert (const_iterator pos, const_iterator first, const_iterator last, size_type count)
	Inserts elements from the range [first, last) before the element at the specified position, repeating the insertion count times.

SPARROW_API iterator	erase (const_iterator pos)
	Inserts a copy of `value` before `pos` in the array, repeating the insertion count times.

SPARROW_API iterator	erase (const_iterator first, const_iterator last)
	Removes the elements in the range [ `first` , `last` ) from the array.

Friends
class	detail::array_access

Detailed Description

Dynamically typed array encapsulating an Arrow layout.

The array class is a dynamically typed container that encapsulates a typed Arrow layout. It provides accessors returning a variant of the suported data types, and supports the visitor pattern.

This class is designed to easily manipulate data from Arrow C structures and to easily extract Arrow C structures from layouts allocated with sparrow. It supports different models of ownership.

Examples: record_batch_example.cpp.

Definition at line 49 of file array_api.hpp.

Member Typedef Documentation

◆ const_iterator

using sparrow::array::const_iterator = array_const_iterator

Definition at line 57 of file array_api.hpp.

◆ const_reference

using sparrow::array::const_reference = array_traits::const_reference

Definition at line 55 of file array_api.hpp.

◆ iterator

using sparrow::array::iterator = const_iterator

Definition at line 58 of file array_api.hpp.

◆ size_type

using sparrow::array::size_type = std::size_t

Definition at line 53 of file array_api.hpp.

◆ value_type

using sparrow::array::value_type = array_traits::value_type

Definition at line 54 of file array_api.hpp.

◆ visit_result_t

template<class F>

using sparrow::array::visit_result_t = std::invoke_result_t<F, null_array>

Definition at line 299 of file array_api.hpp.

Constructor & Destructor Documentation

◆ array() [1/9]

sparrow::array::array ( )

default

Constructs an empty array.

Here is the caller graph for this function:

◆ array() [2/9]

template<layout A>
requires (not std::is_lvalue_reference_v<A>)

sparrow::array::array ( A && a )

explicitconstexpr

Constructs an Array from the given typed layout.

The ownership of the layout is transferred to the Array.

Template Parameters

A	The layout type.

Parameters

a	An rvalue reference to the typed layout.

Definition at line 24 of file array.hpp.

Here is the call graph for this function:

◆ array() [3/9]

template<layout A>

sparrow::array::array ( A * a )

explicitconstexpr

Constructs an Array from the given typed layout.

The ownership of the layout is not transferred to the Array and the layout's lifetime must be longer than that of the Array.

Template Parameters

A	The layout type.

Parameters

a	A pointer to the typed layout.

Definition at line 30 of file array.hpp.

◆ array() [4/9]

template<layout A>

sparrow::array::array ( std::shared_ptr< A > a )

explicitconstexpr

Constructs an Array from the given typed layout.

The ownership of the layout is shared by this Array and any other shared pointer referencing it.

Template Parameters

A	The layout type.

Parameters

a	A shared pointer holding the layout.

Definition at line 36 of file array.hpp.

◆ array() [5/9]

SPARROW_API sparrow::array::array	(	ArrowArray &&	array,
		ArrowSchema &&	schema )

Constructs an Array from the given Arrow C structures, whose ownership is transferred to the Array.

The user should not use array nor schema after calling this constructor.

Parameters

array	The ArrowArray structure to transfer into the Array.
schema	The ArrowSchema structure to transfer into the Array.

Here is the call graph for this function:

◆ array() [6/9]

SPARROW_API sparrow::array::array	(	ArrowArray &&	array,
		ArrowSchema *	schema )

Constructs an Array from the given Arrow C structures.

The Array takes the ownership of the ArrowArray only. The user should not use array after calling this constructor. schema can still be used normally.

Parameters

array	The ArrowArray structure to transfer into the Array.
schema	The ArrowSchema to reference in the Array.

Here is the call graph for this function:

◆ array() [7/9]

SPARROW_API sparrow::array::array	(	ArrowArray *	array,
		ArrowSchema *	schema )

Constructs an array from the given Arrow C structures.

Both structures are referenced from the Array and can still be used normally after calling this constructor.

Parameters

array	The ArrowArray structure to reference in the Array.
schema	The ArrowSchema to reference in the Array.

Here is the call graph for this function:

◆ array() [8/9]

sparrow::array::array ( const array & rhs )

constexprdefault

Performs a deep copy of the given array, even if it does not have the ownership of its internal data.

Parameters

rhs	The array to copy.

Here is the call graph for this function:

◆ array() [9/9]

sparrow::array::array ( array && rhs )

default

The move constructor.

Parameters

rhs	The array to move.

Here is the call graph for this function:

Member Function Documentation

◆ at()

SPARROW_API const_reference sparrow::array::at ( size_type index ) const

nodiscard

Returns: a constant reference to the element at specified index, with bounds checking.

Parameters

index The position of the element in the array.

◆ back()

SPARROW_API const_reference sparrow::array::back ( ) const

nodiscard

Returns a constant reference to the last element in the container.

Calling back on an empty array causes undefined behavior.

Returns: Constant reference to the last element.

◆ begin()

SPARROW_API iterator sparrow::array::begin ( ) const

nodiscard

Returns an iterator to the beginning of the array.

Returns: Iterator to the beginning of the array.

◆ cbegin()

SPARROW_API const_iterator sparrow::array::cbegin ( ) const

nodiscard

Returns a constant iterator to the beginning of the array.

Returns: Constant iterator to the beginning of the array.

Here is the caller graph for this function:

◆ cend()

SPARROW_API const_iterator sparrow::array::cend ( ) const

nodiscard

Returns a constant iterator to the end of the array.

Returns: Constant iterator to the end of the array.

◆ children()

auto sparrow::array::children ( ) const

inlinenodiscard

Returns: a range view of the child arrays of the Array. If the array has no children, an empty range is returned.

Definition at line 180 of file array_api.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ data_type()

SPARROW_API enum data_type sparrow::array::data_type ( ) const

nodiscard

Returns: the data type of the Array.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dictionary()

SPARROW_API std::optional< array > sparrow::array::dictionary ( ) const

nodiscard

Retrieves the dictionary array associated with this array, if it exists.

This method is used for dictionary-encoded arrays to access the dictionary that contains the actual values referenced by the indices in this array.

Returns: std::optional<array> An optional containing the dictionary array if this array is dictionary-encoded, or std::nullopt if no dictionary exists.

Here is the caller graph for this function:

◆ empty()

SPARROW_API bool sparrow::array::empty ( ) const

nodiscard

Checks if the array has no element, i.e.

whether size() == 0.

Returns: true if the array is empty, false otherwise.

◆ end()

SPARROW_API iterator sparrow::array::end ( ) const

nodiscard

Returns an iterator to the end of the array.

Returns: Iterator to the end of the array.

Here is the caller graph for this function:

◆ erase() [1/2]

SPARROW_API iterator sparrow::array::erase	(	const_iterator	first,
		const_iterator	last )

Removes the elements in the range [ first , last ) from the array.

Parameters

first	The iterator to the first element to remove.
last	The iterator to the element following the last element to remove.

Returns: The iterator following the last element removed.

◆ erase() [2/2]

SPARROW_API iterator sparrow::array::erase ( const_iterator pos )

Inserts a copy of value before pos in the array, repeating the insertion count times.

Parameters

pos	The iterator before which the element will be inserted (`pos` may be the end() iterator).
value	The element to insert.
count	The number of times to repeat the insertion.

Returns: An iterator pointing to the first of the inserted values.

Here is the caller graph for this function:

◆ front()

SPARROW_API const_reference sparrow::array::front ( ) const

nodiscard

Returns a constant reference to the first element in the container.

Calling front on an empty array causes undefined behavior.

Returns: Constant reference to the first element.

Here is the caller graph for this function:

◆ insert() [1/2]

SPARROW_API iterator sparrow::array::insert	(	const_iterator	pos,
		const_iterator	first,
		const_iterator	last )

Inserts elements from the range [first, last) before the element at the specified position.

Parameters

pos	The position before which the new elements will be inserted.
first	The beginning of the range of elements to insert.
last	The end of the range of elements to insert.

Returns: An iterator to the first of the newly inserted elements.

Here is the caller graph for this function:

◆ insert() [2/2]

SPARROW_API iterator sparrow::array::insert	(	const_iterator	pos,
		const_iterator	first,
		const_iterator	last,
		size_type	count )

Inserts elements from the range [first, last) before the element at the specified position, repeating the insertion count times.

Parameters

pos	The position before which the new elements will be inserted.
first	The beginning of the range of elements to insert.
last	The end of the range of elements to insert.
count	The number of times to repeat the insertion.

Returns: An iterator to the first of the newly inserted elements.

◆ is_dictionary()

SPARROW_API bool sparrow::array::is_dictionary ( ) const

nodiscard

Returns: true if the array is dictionary-encoded, false otherwise.

◆ is_view()

SPARROW_API bool sparrow::array::is_view ( ) const

nodiscard

Checks if the array is a view.

Returns: True if the array is a view, false otherwise.

◆ metadata()

SPARROW_API std::optional< key_value_view > sparrow::array::metadata ( ) const

nodiscard

Returns: the metadata of the Array. If the metadata is not set, an empty optional is returned.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ name()

SPARROW_API std::optional< std::string_view > sparrow::array::name ( ) const

nodiscard

Returns: the name of the Array. If the name is not set, an empty optional is returned.

Here is the caller graph for this function:

◆ null_count()

SPARROW_API std::int64_t sparrow::array::null_count ( ) const

nodiscard

Returns: the count of null elements in the array, or -1 if unknown.

Here is the caller graph for this function:

◆ offset()

SPARROW_API size_type sparrow::array::offset ( ) const

nodiscard

Returns: the starting offset within the buffers.

Here is the caller graph for this function:

◆ operator=() [1/2]

array & sparrow::array::operator= ( array && rhs )

default

The move assignment operator.

Parameters

rhs	The array to move.

Returns: Reference to this array.

Here is the call graph for this function:

◆ operator=() [2/2]

array & sparrow::array::operator= ( const array & rhs )

default

Overwrites the content of the array with a deep copy of the given array, even if it does not have the ownership of its internal data.

Parameters

rhs	The array to assign.

Returns: Reference to this array.

Here is the call graph for this function:

◆ operator[]()

SPARROW_API const_reference sparrow::array::operator[] ( size_type index ) const

Returns: a constant reference to the element at specified index.

Parameters

index The position of the element in the Array. Must be less than size.

◆ set_metadata()

template<input_metadata_container R>

void sparrow::array::set_metadata ( std::optional< R > metadata )

constexpr

Sets the metadata of the array to metadata.

Template Parameters

R	The metadata container type.

Parameters

metadata The new metadata of the array.

Definition at line 608 of file array_api.hpp.

Here is the call graph for this function:

◆ set_name()

SPARROW_API void sparrow::array::set_name ( std::optional< std::string_view > name )

Sets the name of the array to name.

Parameters

name	The new name of the array.

Here is the call graph for this function:

◆ size()

SPARROW_API size_type sparrow::array::size ( ) const

nodiscard

Returns: the number of elements in the array.

◆ slice()

SPARROW_API array sparrow::array::slice	(	size_type	start,
		size_type	end ) const

nodiscard

Returns a deep-copy of the array restricted to the elements in the half-open range [start, end).

A full copy of the underlying Arrow buffers is made. The new ArrowArray.offset and ArrowArray.length are updated to represent the requested range. The returned array owns its data independently of *this.

Note: Prefer slice_view when read-only access to the slice is sufficient, to avoid the cost of copying the buffers. Prefer slice_inplace when you want to restrict the current array itself without creating a new object.

Parameters

start	Index of the first element to keep. Must satisfy `start` <= `end`.
end	Index one past the last element to keep. Must be <= size of the buffers.

Returns: A new, independently-owned Array containing the requested elements.

Here is the call graph for this function:

◆ slice_inplace()

SPARROW_API void sparrow::array::slice_inplace	(	size_type	start,
		size_type	end )

Restricts *this to the elements in the half-open range [start, end) in place.

Only the ArrowArray.offset and ArrowArray.length of the current array are updated; no buffer data is copied or reallocated. This is the most efficient slicing variant when the caller does not need to retain the original range.

Note: Prefer slice for an independent copy with the same range, or slice_view for a lightweight non-owning view without modifying the current object.

Parameters

start	Index of the first element to keep. Must satisfy `start` <= `end`.
end	Index one past the last element to keep. Must be <= size of the buffers.

Here is the call graph for this function:

◆ slice_view()

SPARROW_API array sparrow::array::slice_view	(	size_type	start,
		size_type	end ) const

nodiscard

Returns a zero-copy view of the array restricted to the elements in the half-open range [start, end).

No buffer data is copied. The returned Array shares ownership of the underlying Arrow buffers with *this, and only its ArrowArray.offset and ArrowArray.length differ. The returned object is in a view state (i.e. is_view returns true), reflecting that it does not own the data.

Warning: The returned view remains valid only as long as the original array (or any other owner of the shared buffers) is kept alive.

Note: Prefer slice when you need an independent copy. Prefer slice_inplace when you want to restrict the current array in place without creating a new object.

Parameters

start	Index of the first element to keep. Must satisfy `start` <= `end`.
end	Index one past the last element to keep. Must be <= size of the buffers.

Returns: A non-owning Array view over the requested range, sharing the underlying data.

Here is the call graph for this function:

◆ view()

SPARROW_API array sparrow::array::view ( ) const

nodiscard

Returns a view of the array.

The data is not copied.

Returns: A view of the array.

Here is the call graph for this function:

◆ visit()

template<class F>

array::visit_result_t< F > sparrow::array::visit ( F && func ) const

constexpr

Returns the result of calling the given functor func on the layout internally held by the array.

The actual type of the layout is retrieved via a visitor dispatch. func must accept any kind of layout.

Template Parameters

F	The functor type.

Parameters

func	The functor to apply.

Returns: The result of calling the functor on the internal layout.

Definition at line 42 of file array.hpp.

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ detail::array_access

friend class detail::array_access

friend

Definition at line 456 of file array_api.hpp.

The documentation for this class was generated from the following files:

sparrow/array_api.hpp
sparrow/array.hpp

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ const_reference

◆ iterator

◆ size_type

◆ value_type

◆ visit_result_t

Constructor & Destructor Documentation

◆ array() [1/9]

◆ array() [2/9]

◆ array() [3/9]

◆ array() [4/9]

◆ array() [5/9]

◆ array() [6/9]

◆ array() [7/9]

◆ array() [8/9]

◆ array() [9/9]

Member Function Documentation

◆ at()

◆ back()

◆ begin()

◆ cbegin()

◆ cend()

◆ children()

◆ data_type()

◆ dictionary()

◆ empty()

◆ end()

◆ erase() [1/2]

◆ erase() [2/2]

◆ front()

◆ insert() [1/2]

◆ insert() [2/2]

◆ is_dictionary()

◆ is_view()

◆ metadata()

◆ name()

◆ null_count()

◆ offset()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ set_metadata()

◆ set_name()

◆ size()

◆ slice()

◆ slice_inplace()

◆ slice_view()

◆ view()

◆ visit()

Friends And Related Symbol Documentation

◆ detail::array_access