CRTP base class providing shared functionality for union array implementations. More...

#include <union_array.hpp>

Inheritance diagram for sparrow::union_array_crtp_base< DERIVED >:

Collaboration diagram for sparrow::union_array_crtp_base< DERIVED >:

Classes
struct	union_child_schema
	Schema of one child of a rebuilt union array. More...

Public Types
using	self_type = union_array_crtp_base<DERIVED>
using	derived_type = DERIVED
using	inner_value_type = array_traits::inner_value_type
using	value_type = array_traits::const_reference
using	const_reference = array_traits::const_reference
using	functor_type = detail::layout_bracket_functor<derived_type, value_type>
using	const_functor_type = detail::layout_bracket_functor<const derived_type, value_type>
using	iterator = functor_index_iterator<functor_type>
using	const_iterator = functor_index_iterator<const_functor_type>
using	const_reverse_iterator = std::reverse_iterator<const_iterator>
using	size_type = std::size_t
using	type_id_buffer_type = u8_buffer<std::uint8_t>

Public Member Functions
constexpr std::optional< std::string_view >	name () const
	Gets the optional name of the union array.
SPARROW_CONSTEXPR_CLANG std::optional< key_value_view >	metadata () const
	Gets the metadata associated with the union array.
SPARROW_CONSTEXPR_CLANG value_type	at (size_type i) const
	Gets element at specified position with bounds checking.
SPARROW_CONSTEXPR_CLANG value_type	operator[] (size_type i) const
	Gets element at specified position without bounds checking.
SPARROW_CONSTEXPR_CLANG value_type	operator[] (size_type i)
	Gets mutable element at specified position.
SPARROW_CONSTEXPR_CLANG value_type	front () const
	Gets reference to the first element.
SPARROW_CONSTEXPR_CLANG value_type	back () const
	Gets reference to the last element.
constexpr bool	empty () const
	Checks if the union array is empty.
constexpr size_type	size () const
	Gets the number of elements in the union array.
constexpr iterator	begin ()
	Gets iterator to the beginning of the array.
constexpr iterator	end ()
	Gets iterator to the end of the array.
constexpr const_iterator	begin () const
	Gets const iterator to the beginning of the array.
constexpr const_iterator	end () const
	Gets const iterator to the end of the array.
constexpr const_iterator	cbegin () const
	Gets const iterator to the beginning of the array.
constexpr const_iterator	cend () const
	Gets const iterator to the end of the array.
constexpr const_reverse_iterator	rbegin () const
	Gets reverse iterator to the beginning of reversed array.
constexpr const_reverse_iterator	rend () const
	Gets reverse iterator to the end of reversed array.
constexpr const_reverse_iterator	crbegin () const
	Gets const reverse iterator to the beginning of reversed array.
constexpr const_reverse_iterator	crend () const
	Gets const reverse iterator to the end of reversed array.
iterator	insert (const_iterator pos, const_reference value, size_type count=1)
	Inserts copies of a value before pos.
iterator	insert (const_iterator pos, const array_traits::value_type &value, size_type count=1)
	Inserts copies of an owned value before pos.
template<std::input_iterator InputIt>
iterator	insert (const_iterator pos, InputIt first, InputIt last, size_type count=1)
	Inserts a range before pos, repeated count times.
iterator	erase (const_iterator pos)
	Erases the value at pos.
iterator	erase (const_iterator first, const_iterator last)
	Erases the half-open range [first, last).
void	push_back (const_reference value)
	Appends a borrowed value.
void	push_back (const array_traits::value_type &value)
	Appends an owned value.
void	resize (size_type new_length)
	Resizes the array, default-inserting any appended values.
void	resize (size_type new_length, const_reference value)
	Resizes the array, inserting value when it grows.
void	resize (size_type new_length, const array_traits::value_type &value)
	Resizes the array, inserting value when it grows.
constexpr void	zero_null_values (const inner_value_type &value)
	Replaces stored values at null positions.
template<std::ranges::input_range R>
constexpr auto	type_id_map_from_child_to_type_id (const std::optional< R > &child_index_to_type_id) -> type_id_map

Protected Types
using	type_id_map = std::array<std::uint8_t, TYPE_ID_MAP_SIZE>
using	children_type = std::vector<cloning_ptr<array_wrapper>>
Protected Types inherited from sparrow::crtp_base< DERIVED >
using	derived_type

Protected Member Functions
constexpr children_type	make_children (arrow_proxy &proxy)
	Creates child array wrappers from Arrow proxy.
	union_array_crtp_base (arrow_proxy proxy)
	Protected constructor from Arrow proxy.
constexpr	union_array_crtp_base (const self_type &rhs)
	Copy constructor.
constexpr self_type &	operator= (const self_type &rhs)
	Copy assignment operator.
constexpr	union_array_crtp_base (self_type &&rhs)=default
constexpr self_type &	operator= (self_type &&rhs)=default
template<class VALUE>
void	resize_impl (size_type new_length, VALUE &&value)
iterator	iterator_at (size_type index)
void	append_rebuild_entries (std::vector< detail::union_rebuild_value > &entries, size_type from, size_type to) const
	Appends one rebuild entry per element in [from, to), each referring to its current child slot.
iterator	insert_materialized (const_iterator pos, std::vector< array_traits::value_type > inserted, size_type count)
	Rebuilds the array with the owned `inserted` values repeated `count` times before `pos`.
iterator	erase_values (size_type first, size_type count)
std::vector< union_child_schema >	make_child_schemas (std::vector< std::uint8_t > &child_type_ids, std::array< bool, TYPE_ID_MAP_SIZE > &used_type_ids) const
	Initializes the schema bookkeeping of a rebuild from the current children.
std::vector< detail::union_rebuild_value >	make_union_fillers (size_type old_child_count, const std::vector< union_child_schema > &child_schemas, std::vector< std::size_t > &inserted_children, std::vector< array_traits::value_type > &inserted) const
	Builds the row padding the output rows a child is not selected for.
detail::union_rebuild_payload	make_rebuild_payload (std::span< const detail::union_rebuild_value > values, std::span< const std::size_t > inserted_children, std::span< const std::uint8_t > child_type_ids, std::span< const detail::union_rebuild_value > fillers) const
	Plans the rebuilt data from the row plan and the inserted-value resolution.
std::vector< array >	build_rebuilt_children (const detail::union_rebuild_payload &payload, std::span< const array_traits::value_type > inserted, std::span< const std::size_t > inserted_children, const children_type &old_children, std::vector< array > &new_child_templates) const
	Rebuilds each child array from the payload rows planned for it.
arrow_proxy	create_rebuild_proxy (std::vector< array > children, detail::union_rebuild_payload &&payload, std::span< const std::uint8_t > child_type_ids) const
	Creates the Arrow proxy of a rebuilt array from its children and buffers.
iterator	adopt_rebuilt_array (arrow_proxy replacement, std::vector< std::uint8_t > child_type_ids, size_type return_index)
	Replaces this array's data with the rebuilt `replacement`.
iterator	rebuild_values (std::vector< detail::union_rebuild_value > values, std::vector< array_traits::value_type > inserted, size_type return_index)
	Rebuilds this array from `values`, the inserted values they reference, and.
constexpr arrow_proxy &	get_arrow_proxy ()
	Gets mutable reference to the Arrow proxy.
constexpr const arrow_proxy &	get_arrow_proxy () const
	Gets const reference to the Arrow proxy.
Protected Member Functions inherited from sparrow::crtp_base< DERIVED >
constexpr derived_type &	derived_cast ()

Static Protected Member Functions
static std::vector< std::uint8_t >	child_type_ids_from_format (std::string_view format_string)
	Extracts child type IDs from an Arrow union format string.
static constexpr type_id_map	make_type_id_map (std::span< const std::uint8_t > child_type_ids)
	Creates a type-ID lookup table from child type IDs.
template<std::ranges::input_range R>
static constexpr type_id_map	type_id_map_from_child_to_type_id (const std::optional< R > &child_index_to_type_id)
	Creates type ID mapping from child index to type ID mapping.
template<std::ranges::input_range R> requires (std::convertible_to<std::ranges::range_value_t<R>, std::uint8_t>)
static constexpr std::string	make_format_string (bool dense, std::size_t n, const std::optional< R > &child_index_to_type_id)
	Creates Arrow format string for union arrays.
static std::vector< std::size_t >	resolve_inserted_children (std::span< const array_traits::value_type > inserted, std::vector< union_child_schema > &child_schemas, std::vector< std::uint8_t > &child_type_ids, std::array< bool, TYPE_ID_MAP_SIZE > &used_type_ids, std::vector< array > &new_child_templates)
	Maps each inserted value to the child it belongs to.

Protected Attributes
arrow_proxy	m_proxy
	Internal Arrow proxy.
const std::uint8_t *	p_type_ids
	Pointer to type ID buffer.
children_type	m_children
	Child array wrappers.
std::vector< std::uint8_t >	m_child_type_ids
	Type IDs in child order.
std::array< std::uint8_t, TYPE_ID_MAP_SIZE >	m_type_id_map
	Type ID to child index mapping.

Static Protected Attributes
static constexpr size_t	TYPE_ID_MAP_SIZE = 256

Friends
class	detail::array_access

Detailed Description

template<class DERIVED>
class sparrow::union_array_crtp_base< DERIVED >

CRTP base class providing shared functionality for union array implementations.

This class implements the common interface and logic shared between dense and sparse union arrays. Union arrays can store values of different types in a single array, with each element having an associated type ID that indicates which child array contains the actual value.

Key features:

Type-safe heterogeneous storage
Efficient type dispatch using type ID mapping
STL-compatible container interface
Support for both dense and sparse union layouts
Arrow format compatibility

The union array consists of:

Type ID buffer: Maps each element to its corresponding child array
Child arrays: Store the actual values for each supported type
Type ID mapping: Translates type IDs to child array indices

Template Parameters

DERIVED The derived union array type (dense_union_array or sparse_union_array)

Precondition: DERIVED must inherit from this class (CRTP pattern); DERIVED must implement element_offset() method

Postcondition: Provides complete union array interface; Maintains Arrow union format compatibility; Thread-safe for read operations

// Union arrays can store different types
dense_union_array union_arr = create_union_with_int_and_string();
 
// Access elements (type is determined at runtime)
auto elem = union_arr[0];
if (elem.has_value()) {
    // elem could be int or string depending on type ID
}
 
// Iteration over heterogeneous elements
for (const auto& element : union_arr) {
    // Process element of unknown type
}

Definition at line 171 of file union_array.hpp.

Member Typedef Documentation

◆ children_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::children_type = std::vector<cloning_ptr<array_wrapper>>

protected

Definition at line 513 of file union_array.hpp.

◆ const_functor_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::const_functor_type = detail::layout_bracket_functor<const derived_type, value_type>

Definition at line 181 of file union_array.hpp.

◆ const_iterator

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::const_iterator = functor_index_iterator<const_functor_type>

Definition at line 183 of file union_array.hpp.

◆ const_reference

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::const_reference = array_traits::const_reference

Definition at line 179 of file union_array.hpp.

◆ const_reverse_iterator

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::const_reverse_iterator = std::reverse_iterator<const_iterator>

Definition at line 184 of file union_array.hpp.

◆ derived_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::derived_type = DERIVED

Definition at line 176 of file union_array.hpp.

◆ functor_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::functor_type = detail::layout_bracket_functor<derived_type, value_type>

Definition at line 180 of file union_array.hpp.

◆ inner_value_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::inner_value_type = array_traits::inner_value_type

Definition at line 177 of file union_array.hpp.

◆ iterator

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::iterator = functor_index_iterator<functor_type>

Definition at line 182 of file union_array.hpp.

◆ self_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::self_type = union_array_crtp_base<DERIVED>

Definition at line 175 of file union_array.hpp.

◆ size_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::size_type = std::size_t

Definition at line 185 of file union_array.hpp.

◆ type_id_buffer_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::type_id_buffer_type = u8_buffer<std::uint8_t>

Definition at line 187 of file union_array.hpp.

◆ type_id_map

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::type_id_map = std::array<std::uint8_t, TYPE_ID_MAP_SIZE>

protected

Definition at line 459 of file union_array.hpp.

◆ value_type

template<class DERIVED>

using sparrow::union_array_crtp_base< DERIVED >::value_type = array_traits::const_reference

Definition at line 178 of file union_array.hpp.

Constructor & Destructor Documentation

◆ union_array_crtp_base() [1/3]

template<class DERIVED>

sparrow::union_array_crtp_base< DERIVED >::union_array_crtp_base ( arrow_proxy proxy )

explicitprotected

Protected constructor from Arrow proxy.

Parameters

proxy Arrow proxy containing union array data and schema

Precondition: proxy must contain valid Arrow union array and schema; proxy format must be valid union format

Postcondition: Array is initialized with data from proxy; Type ID mapping is parsed and cached; Child arrays are created and accessible

Definition at line 1367 of file union_array.hpp.

Here is the call graph for this function:

◆ union_array_crtp_base() [2/3]

template<class DERIVED>

sparrow::union_array_crtp_base< DERIVED >::union_array_crtp_base ( const self_type & rhs )

constexprprotected

Copy constructor.

Parameters

rhs	Source union array to copy from

Precondition: rhs must be in a valid state

Postcondition: This array contains a copy of rhs data; Child arrays and type mapping are reconstructed

Definition at line 1377 of file union_array.hpp.

◆ union_array_crtp_base() [3/3]

template<class DERIVED>

sparrow::union_array_crtp_base< DERIVED >::union_array_crtp_base ( self_type && rhs )

constexprprotecteddefault

Member Function Documentation

◆ adopt_rebuilt_array()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::adopt_rebuilt_array	(	arrow_proxy	replacement,
		std::vector< std::uint8_t >	child_type_ids,
		size_type	return_index )

protected

Replaces this array's data with the rebuilt replacement.

Returns: An iterator to return_index.

Definition at line 2042 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ append_rebuild_entries()

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::append_rebuild_entries	(	std::vector< detail::union_rebuild_value > &	entries,
		size_type	from,
		size_type	to ) const

inlineprotected

Appends one rebuild entry per element in [from, to), each referring to its current child slot.

Definition at line 590 of file union_array.hpp.

Here is the caller graph for this function:

◆ at()

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG value_type sparrow::union_array_crtp_base< DERIVED >::at ( size_type i ) const

nodiscard

Gets element at specified position with bounds checking.

Parameters

i	Index of the element to access

Returns: Value from the appropriate child array

Precondition: i must be < size()

Postcondition: Returns valid value from child array indicated by type ID; Value type depends on the type ID at position i

Exceptions

std::out_of_range if i >= size()

◆ back()

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG auto sparrow::union_array_crtp_base< DERIVED >::back ( ) const

nodiscard

Gets reference to the last element.

Returns: Value from the appropriate child array for last element

Precondition: Array must not be empty (!empty())

Postcondition: Returns valid value from child array; Equivalent to (*this)[size() - 1]

Definition at line 1490 of file union_array.hpp.

Here is the call graph for this function:

◆ begin() [1/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::begin ( )

nodiscardconstexpr

Gets iterator to the beginning of the array.

Returns: Iterator pointing to the first element

Postcondition: Iterator is valid for array traversal; For empty array, equals end()

Definition at line 1424 of file union_array.hpp.

Here is the call graph for this function:

◆ begin() [2/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::begin ( ) const

nodiscardconstexpr

Gets const iterator to the beginning of the array.

Returns: Const iterator pointing to the first element

Postcondition: Iterator is valid for array traversal; For empty array, equals end()

Definition at line 1436 of file union_array.hpp.

Here is the call graph for this function:

◆ build_rebuilt_children()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::build_rebuilt_children	(	const detail::union_rebuild_payload &	payload,
		std::span< const array_traits::value_type >	inserted,
		std::span< const std::size_t >	inserted_children,
		const children_type &	old_children,
		std::vector< array > &	new_child_templates ) const

protected

Rebuilds each child array from the payload rows planned for it.

Parameters

payload	Rebuilt data, holding the row plan of each child
inserted	Inserted values the rows may refer to
inserted_children	Child index of each inserted value
old_children	Children before the rebuild
new_child_templates	Prototypes the rebuilt children of an inserted alternative are taken and left empty

Returns: The rebuilt children, in child order

Definition at line 1969 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cbegin()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::cbegin ( ) const

nodiscardconstexpr

Gets const iterator to the beginning of the array.

Returns: Const iterator pointing to the first element

Postcondition: Iterator is valid for array traversal; Guarantees const iterator even for non-const array

Definition at line 1448 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cend()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::cend ( ) const

nodiscardconstexpr

Gets const iterator to the end of the array.

Returns: Const iterator pointing past the last element

Postcondition: Iterator marks the end of the array range; Guarantees const iterator even for non-const array

Definition at line 1454 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ child_type_ids_from_format()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::child_type_ids_from_format ( std::string_view format_string )

staticprotected

Extracts child type IDs from an Arrow union format string.

Parameters

format_string Arrow format string containing type IDs

Returns: Type ID for each child, in child order

Precondition: format_string must be valid Arrow union format ("+ud:" or "+us:" prefix)

Definition at line 1227 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ crbegin()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::crbegin ( ) const

nodiscardconstexpr

Gets const reverse iterator to the beginning of reversed array.

Returns: Const reverse iterator pointing to the last element

Postcondition: Iterator is valid for reverse traversal; Guarantees const iterator even for non-const array

Definition at line 1472 of file union_array.hpp.

Here is the call graph for this function:

◆ create_rebuild_proxy()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::create_rebuild_proxy	(	std::vector< array >	children,
		detail::union_rebuild_payload &&	payload,
		std::span< const std::uint8_t >	child_type_ids ) const

protected

Creates the Arrow proxy of a rebuilt array from its children and buffers.

payload is consumed: its type-ID and offset buffers are moved into the proxy.

Definition at line 2008 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ crend()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::crend ( ) const

nodiscardconstexpr

Gets const reverse iterator to the end of reversed array.

Returns: Const reverse iterator pointing before the first element

Postcondition: Iterator marks the end of reverse traversal; Guarantees const iterator even for non-const array

Definition at line 1478 of file union_array.hpp.

Here is the call graph for this function:

◆ empty()

template<class DERIVED>

bool sparrow::union_array_crtp_base< DERIVED >::empty ( ) const

nodiscardconstexpr

Checks if the union array is empty.

Returns: true if array contains no elements, false otherwise

Postcondition: Return value equals (size() == 0)

Definition at line 1418 of file union_array.hpp.

Here is the call graph for this function:

◆ end() [1/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::end ( )

nodiscardconstexpr

Gets iterator to the end of the array.

Returns: Iterator pointing past the last element

Postcondition: Iterator marks the end of the array range; Not dereferenceable

Definition at line 1430 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ end() [2/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::end ( ) const

nodiscardconstexpr

Gets const iterator to the end of the array.

Returns: Const iterator pointing past the last element

Postcondition: Iterator marks the end of the array range; Not dereferenceable

Definition at line 1442 of file union_array.hpp.

Here is the call graph for this function:

◆ erase() [1/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::erase	(	const_iterator	first,
		const_iterator	last )

Erases the half-open range [first, last).

Returns: Iterator following the erased range.

Definition at line 1564 of file union_array.hpp.

Here is the call graph for this function:

◆ erase() [2/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::erase ( const_iterator pos )

Erases the value at pos.

Returns: Iterator following the erased value.

Definition at line 1556 of file union_array.hpp.

Here is the call graph for this function:

◆ erase_values()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::erase_values	(	size_type	first,
		size_type	count )

protected

Definition at line 1597 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ front()

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG auto sparrow::union_array_crtp_base< DERIVED >::front ( ) const

nodiscard

Gets reference to the first element.

Returns: Value from the appropriate child array for first element

Precondition: Array must not be empty (!empty())

Postcondition: Returns valid value from child array; Equivalent to (*this)[0]

Definition at line 1484 of file union_array.hpp.

◆ get_arrow_proxy() [1/2]

template<class DERIVED>

arrow_proxy & sparrow::union_array_crtp_base< DERIVED >::get_arrow_proxy ( )

nodiscardconstexprprotected

Gets mutable reference to the Arrow proxy.

Returns: Mutable reference to internal Arrow proxy

Postcondition: Returns valid reference to Arrow proxy

Definition at line 1355 of file union_array.hpp.

Here is the caller graph for this function:

◆ get_arrow_proxy() [2/2]

template<class DERIVED>

const arrow_proxy & sparrow::union_array_crtp_base< DERIVED >::get_arrow_proxy ( ) const

nodiscardconstexprprotected

Gets const reference to the Arrow proxy.

Returns: Const reference to internal Arrow proxy

Postcondition: Returns valid const reference to Arrow proxy

Definition at line 1361 of file union_array.hpp.

◆ insert() [1/3]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::insert	(	const_iterator	pos,
		const array_traits::value_type &	value,
		size_type	count = 1 )

Inserts copies of an owned value before pos.

Returns: Iterator to the first inserted value.

Definition at line 2121 of file union_array.hpp.

Here is the call graph for this function:

◆ insert() [2/3]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::insert	(	const_iterator	pos,
		const_reference	value,
		size_type	count = 1 )

Inserts copies of a value before pos.

Returns: Iterator to the first inserted value.

Definition at line 2109 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ insert() [3/3]

template<class DERIVED>

template<std::input_iterator InputIt>

auto sparrow::union_array_crtp_base< DERIVED >::insert	(	const_iterator	pos,
		InputIt	first,
		InputIt	last,
		size_type	count = 1 ) -> iterator

Inserts a range before pos, repeated count times.

Returns: Iterator to the first inserted value.

Definition at line 1514 of file union_array.hpp.

Here is the call graph for this function:

◆ insert_materialized()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::insert_materialized	(	const_iterator	pos,
		std::vector< array_traits::value_type >	inserted,
		size_type	count )

protected

Rebuilds the array with the owned inserted values repeated count times before pos.

Precondition: count > 0

Definition at line 2136 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ iterator_at()

template<class DERIVED>

iterator sparrow::union_array_crtp_base< DERIVED >::iterator_at ( size_type index )

inlineprotected

Definition at line 581 of file union_array.hpp.

Here is the caller graph for this function:

◆ make_child_schemas()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::make_child_schemas	(	std::vector< std::uint8_t > &	child_type_ids,
		std::array< bool, TYPE_ID_MAP_SIZE > &	used_type_ids ) const

protected

Initializes the schema bookkeeping of a rebuild from the current children.

Copies the current child type IDs into child_type_ids (extended later by the children created for inserted values) and marks them as used in used_type_ids.

Parameters

child_type_ids	Output: type ID of each current child, in child order
used_type_ids	Output: type IDs already assigned, marked with the current ones

Returns: The schema of each current child, in child order

Definition at line 1574 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_children()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::make_children ( arrow_proxy & proxy )

constexprprotected

Creates child array wrappers from Arrow proxy.

Parameters

proxy Arrow proxy containing child array data

Returns: Vector of child array wrappers

Precondition: proxy must contain valid child array data

Postcondition: Returns valid children collection; Each child corresponds to a union member type

Definition at line 1496 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_format_string()

template<class DERIVED>
requires (std::convertible_to<std::ranges::range_value_t<R>, std::uint8_t>)

template<std::ranges::input_range R>
requires (std::convertible_to<std::ranges::range_value_t<R>, std::uint8_t>)

std::string sparrow::union_array_crtp_base< DERIVED >::make_format_string	(	bool	dense,
		std::size_t	n,
		const std::optional< R > &	child_index_to_type_id )

staticconstexprprotected

Creates Arrow format string for union arrays.

Template Parameters

R	Range type for type ID mapping

Parameters

dense	Whether this is a dense union (true) or sparse (false)
n	Number of child arrays
range	Optional type ID mapping range

Returns: Arrow format string for the union

Precondition: If range is provided, its size must equal n or be 0; Range elements must be convertible to std::uint8_t

Postcondition: Returns valid Arrow format string ("+ud:" or "+us:" prefix)

Exceptions

std::invalid_argument if range size doesn't match n

Definition at line 1305 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_rebuild_payload()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::make_rebuild_payload	(	std::span< const detail::union_rebuild_value >	values,
		std::span< const std::size_t >	inserted_children,
		std::span< const std::uint8_t >	child_type_ids,
		std::span< const detail::union_rebuild_value >	fillers ) const

protected

Plans the rebuilt data from the row plan and the inserted-value resolution.

Dense unions build a per-child row plan and a type-ID/offset buffer pair, sparse unions pad every non-selected output row of a child with its filler row.

Parameters

values	The rows to be rebuilt
inserted_children	Child index of each inserted value, in insertion order
child_type_ids	Type IDs of the children after the rebuild
fillers	The row padding the non-selected output rows of each child

Returns: The rebuilt data

Definition at line 1946 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_type_id_map()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::make_type_id_map ( std::span< const std::uint8_t > child_type_ids )

staticconstexprprotected

Creates a type-ID lookup table from child type IDs.

Parameters

child_type_ids Type ID for each child, in child order

Returns: Array mapping type IDs to child indices

Definition at line 1254 of file union_array.hpp.

Here is the caller graph for this function:

◆ make_union_fillers()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::make_union_fillers	(	size_type	old_child_count,
		const std::vector< union_child_schema > &	child_schemas,
		std::vector< std::size_t > &	inserted_children,
		std::vector< array_traits::value_type > &	inserted ) const

protected

Builds the row padding the output rows a child is not selected for.

An old child with rows is padded by reusing its first row, marked null on copy, while a child without rows (empty, or created for an inserted value) is padded with a null of its own type, materialized once as an inserted value.

Parameters

old_child_count	Number of children before the rebuild
child_schemas	Schemas of all children after the rebuild
inserted_children	Child index of each inserted value, kept in sync with `inserted`
inserted	Inserted values, appended with one null per padded child

Returns: One filler row per child, in child order

Definition at line 1903 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ metadata()

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG std::optional< key_value_view > sparrow::union_array_crtp_base< DERIVED >::metadata ( ) const

nodiscard

Gets the metadata associated with the union array.

Returns: Optional view of key-value metadata pairs from Arrow schema

Postcondition: Returns nullopt if no metadata is set; Returned view remains valid while array exists

Definition at line 1349 of file union_array.hpp.

Here is the caller graph for this function:

◆ name()

template<class DERIVED>

std::optional< std::string_view > sparrow::union_array_crtp_base< DERIVED >::name ( ) const

nodiscardconstexpr

Gets the optional name of the union array.

Returns: Optional string view of the array name from Arrow schema

Postcondition: Returns nullopt if no name is set; Returned string view remains valid while array exists

Definition at line 1343 of file union_array.hpp.

◆ operator=() [1/2]

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::operator= ( const self_type & rhs )

constexprprotected

Copy assignment operator.

Parameters

rhs	Source union array to copy from

Returns: Reference to this array

Precondition: rhs must be in a valid state

Postcondition: This array contains a copy of rhs data; Previous data is properly released; Child arrays and type mapping are reconstructed

Definition at line 1383 of file union_array.hpp.

Here is the call graph for this function:

◆ operator=() [2/2]

template<class DERIVED>

self_type & sparrow::union_array_crtp_base< DERIVED >::operator= ( self_type && rhs )

constexprprotecteddefault

◆ operator[]() [1/2]

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG auto sparrow::union_array_crtp_base< DERIVED >::operator[] ( size_type i )

nodiscard

Gets mutable element at specified position.

Parameters

i	Index of the element to access

Returns: Value from the appropriate child array

Precondition: i must be < size()

Postcondition: Returns value from child array indicated by type ID; Value type depends on the type ID at position i

Definition at line 1406 of file union_array.hpp.

◆ operator[]() [2/2]

template<class DERIVED>

SPARROW_CONSTEXPR_CLANG auto sparrow::union_array_crtp_base< DERIVED >::operator[] ( size_type i ) const

nodiscard

Gets element at specified position without bounds checking.

Parameters

i	Index of the element to access

Returns: Value from the appropriate child array

Precondition: i must be < size()

Postcondition: Returns value from child array indicated by type ID; Value type depends on the type ID at position i

Definition at line 1397 of file union_array.hpp.

Here is the call graph for this function:

◆ push_back() [1/2]

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::push_back ( const array_traits::value_type & value )

Appends an owned value.

Definition at line 1532 of file union_array.hpp.

Here is the call graph for this function:

◆ push_back() [2/2]

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::push_back ( const_reference value )

Appends a borrowed value.

Definition at line 1526 of file union_array.hpp.

Here is the call graph for this function:

◆ rbegin()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::rbegin ( ) const

nodiscardconstexpr

Gets reverse iterator to the beginning of reversed array.

Returns: Const reverse iterator pointing to the last element

Postcondition: Iterator is valid for reverse traversal; For empty array, equals rend()

Definition at line 1460 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rebuild_values()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::rebuild_values	(	std::vector< detail::union_rebuild_value >	values,
		std::vector< array_traits::value_type >	inserted,
		size_type	return_index )

protected

Rebuilds this array from values, the inserted values they reference, and.

Returns: returns an iterator to return_index.

Definition at line 2061 of file union_array.hpp.

Here is the call graph for this function:

◆ rend()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::rend ( ) const

nodiscardconstexpr

Gets reverse iterator to the end of reversed array.

Returns: Const reverse iterator pointing before the first element

Postcondition: Iterator marks the end of reverse traversal; Not dereferenceable

Definition at line 1466 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ resize() [1/3]

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::resize ( size_type new_length )

Resizes the array, default-inserting any appended values.

Definition at line 1538 of file union_array.hpp.

Here is the call graph for this function:

◆ resize() [2/3]

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::resize	(	size_type	new_length,
		const array_traits::value_type &	value )

Resizes the array, inserting value when it grows.

Definition at line 1550 of file union_array.hpp.

Here is the call graph for this function:

◆ resize() [3/3]

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::resize	(	size_type	new_length,
		const_reference	value )

Resizes the array, inserting value when it grows.

Definition at line 1544 of file union_array.hpp.

Here is the call graph for this function:

◆ resize_impl()

template<class DERIVED>

template<class VALUE>

void sparrow::union_array_crtp_base< DERIVED >::resize_impl	(	size_type	new_length,
		VALUE &&	value )

inlineprotected

Definition at line 568 of file union_array.hpp.

Here is the caller graph for this function:

◆ resolve_inserted_children()

template<class DERIVED>

auto sparrow::union_array_crtp_base< DERIVED >::resolve_inserted_children	(	std::span< const array_traits::value_type >	inserted,
		std::vector< union_child_schema > &	child_schemas,
		std::vector< std::uint8_t > &	child_type_ids,
		std::array< bool, TYPE_ID_MAP_SIZE > &	used_type_ids,
		std::vector< array > &	new_child_templates )

staticprotected

Maps each inserted value to the child it belongs to.

Alternatives already present in child_schemas reuse that child, others get a new child, appended to child_schemas, child_type_ids and new_child_templates, and a free type ID taken from used_type_ids.

Parameters

inserted	Inserted values to resolve, in insertion order
child_schemas	Schemas of the existing children, extended with the created ones
child_type_ids	Type IDs of the existing children, extended with the created ones
used_type_ids	Type IDs already assigned, updated with the newly assigned ones
new_child_templates	Prototypes of the created children, appended to

Returns: The child index of each inserted value, in insertion order

Definition at line 1865 of file union_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ size()

template<class DERIVED>

std::size_t sparrow::union_array_crtp_base< DERIVED >::size ( ) const

nodiscardconstexpr

Gets the number of elements in the union array.

Returns: Number of elements in the array

Postcondition: Returns non-negative value; Equals the number of type IDs in the type buffer

Definition at line 1412 of file union_array.hpp.

Here is the caller graph for this function:

◆ type_id_map_from_child_to_type_id() [1/2]

template<class DERIVED>

template<std::ranges::input_range R>

constexpr type_id_map sparrow::union_array_crtp_base< DERIVED >::type_id_map_from_child_to_type_id ( const std::optional< R > & child_index_to_type_id )

staticconstexprprotected

Creates type ID mapping from child index to type ID mapping.

Template Parameters

R	Range type containing type IDs

Parameters

child_index_to_type_id Optional mapping from child index to type ID

Returns: Inverse mapping from type ID to child index

Postcondition: If no mapping provided, uses identity mapping (0->0, 1->1, etc.); Returned mapping enables efficient child array lookup

◆ type_id_map_from_child_to_type_id() [2/2]

template<class DERIVED>

template<std::ranges::input_range R>

auto sparrow::union_array_crtp_base< DERIVED >::type_id_map_from_child_to_type_id ( const std::optional< R > & child_index_to_type_id ) -> type_id_map

constexpr

Definition at line 1273 of file union_array.hpp.

◆ zero_null_values()

template<class DERIVED>

void sparrow::union_array_crtp_base< DERIVED >::zero_null_values ( const inner_value_type & value )

inlineconstexpr

Replaces stored values at null positions.

Definition at line 450 of file union_array.hpp.

◆ detail::array_access

template<class DERIVED>

friend class detail::array_access

friend

Definition at line 778 of file union_array.hpp.

Member Data Documentation

◆ m_child_type_ids

template<class DERIVED>

std::vector<std::uint8_t> sparrow::union_array_crtp_base< DERIVED >::m_child_type_ids

protected

Type IDs in child order.

Definition at line 775 of file union_array.hpp.

◆ m_children

template<class DERIVED>

children_type sparrow::union_array_crtp_base< DERIVED >::m_children

protected

Child array wrappers.

Definition at line 774 of file union_array.hpp.

◆ m_proxy

template<class DERIVED>

arrow_proxy sparrow::union_array_crtp_base< DERIVED >::m_proxy

protected

Internal Arrow proxy.

Definition at line 772 of file union_array.hpp.

◆ m_type_id_map

template<class DERIVED>

std::array<std::uint8_t, TYPE_ID_MAP_SIZE> sparrow::union_array_crtp_base< DERIVED >::m_type_id_map

protected

Type ID to child index mapping.

Definition at line 776 of file union_array.hpp.

◆ p_type_ids

template<class DERIVED>

const std::uint8_t* sparrow::union_array_crtp_base< DERIVED >::p_type_ids

protected

Pointer to type ID buffer.

Definition at line 773 of file union_array.hpp.

◆ TYPE_ID_MAP_SIZE

template<class DERIVED>

size_t sparrow::union_array_crtp_base< DERIVED >::TYPE_ID_MAP_SIZE = 256

staticconstexprprotected

Definition at line 457 of file union_array.hpp.

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

sparrow/union_array.hpp

Classes

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ children_type

◆ const_functor_type

◆ const_iterator

◆ const_reference

◆ const_reverse_iterator

◆ derived_type

◆ functor_type

◆ inner_value_type

◆ iterator

◆ self_type

◆ size_type

◆ type_id_buffer_type

◆ type_id_map

◆ value_type

Constructor & Destructor Documentation

◆ union_array_crtp_base() [1/3]

◆ union_array_crtp_base() [2/3]

◆ union_array_crtp_base() [3/3]

Member Function Documentation

◆ adopt_rebuilt_array()

◆ append_rebuild_entries()

◆ at()

◆ back()

◆ begin() [1/2]

◆ begin() [2/2]

◆ build_rebuilt_children()

◆ cbegin()

◆ cend()

◆ child_type_ids_from_format()

◆ crbegin()

◆ create_rebuild_proxy()

◆ crend()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/2]

◆ erase() [2/2]

◆ erase_values()

◆ front()

◆ get_arrow_proxy() [1/2]

◆ get_arrow_proxy() [2/2]

◆ insert() [1/3]

◆ insert() [2/3]

◆ insert() [3/3]

◆ insert_materialized()

◆ iterator_at()

◆ make_child_schemas()

◆ make_children()

◆ make_format_string()

◆ make_rebuild_payload()

◆ make_type_id_map()

◆ make_union_fillers()

◆ metadata()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ rbegin()

◆ rebuild_values()

◆ rend()

◆ resize() [1/3]

◆ resize() [2/3]

◆ resize() [3/3]

◆ resize_impl()

◆ resolve_inserted_children()

◆ size()