Array implementation for storing timestamp values with timezone information. More...

#include <timestamp_array.hpp>

Inheritance diagram for sparrow::timestamp_array< T >:

Collaboration diagram for sparrow::timestamp_array< T >:

Public Types
using	self_type = timestamp_array

using	base_type = mutable_array_bitmap_base<self_type>

using	inner_types = array_inner_types<self_type>

using	inner_value_type = typename inner_types::inner_value_type

using	inner_reference = typename inner_types::inner_reference

using	inner_const_reference = typename inner_types::inner_const_reference

using	bitmap_type = typename base_type::bitmap_type

using	bitmap_reference = typename base_type::bitmap_reference

using	bitmap_const_reference = typename base_type::bitmap_const_reference

using	bitmap_iterator = typename base_type::bitmap_iterator

using	const_bitmap_iterator = typename base_type::const_bitmap_iterator

using	bitmap_range = typename base_type::bitmap_range

using	const_bitmap_range = typename base_type::const_bitmap_range

using	value_type = nullable<inner_value_type>

using	reference = nullable<inner_reference, bitmap_reference>

using	const_reference = nullable<inner_const_reference, bitmap_const_reference>

using	size_type = typename base_type::size_type

using	difference_type = typename base_type::difference_type

using	iterator_tag = typename base_type::iterator_tag

using	value_iterator = typename base_type::value_iterator

using	const_value_iterator = typename base_type::const_value_iterator

using	iterator = typename base_type::iterator

using	const_iterator = typename base_type::const_iterator

using	functor_type = typename inner_types::functor_type

using	const_functor_type = typename inner_types::const_functor_type

using	inner_value_type_duration = inner_value_type::duration

using	buffer_inner_value_type = inner_value_type_duration::rep

using	buffer_inner_value_iterator = pointer_iterator<buffer_inner_value_type*>

using	buffer_inner_const_value_iterator = pointer_iterator<const buffer_inner_value_type*>

Public Types inherited from sparrow::array_bitmap_base_impl< D, true >
using	base_type

using	size_type

using	bitmap_type

using	bitmap_iterator

using	const_bitmap_iterator

using	bitmap_const_reference

using	difference_type

using	const_bitmap_range

using	iterator_tag

Public Member Functions
	timestamp_array (arrow_proxy)
	Constructs timestamp array from Arrow proxy.

template<class... Args> requires (mpl::excludes_copy_and_move_ctor_v<timestamp_array, Args...>)
constexpr	timestamp_array (Args &&... args)
	Generic constructor for creating timestamp arrays from various inputs.

template<input_metadata_container METADATA_RANGE = std::vector<metadata_pair>>
constexpr	timestamp_array (const date::time_zone *timezone, std::initializer_list< inner_value_type > init, std::optional< std::string_view > name=std::nullopt, std::optional< METADATA_RANGE > metadata=std::nullopt)
	Constructs timestamp array from initializer list.

constexpr	timestamp_array (const timestamp_array &rhs)
	Copy constructor.

constexpr timestamp_array &	operator= (const timestamp_array &rhs)
	Copy assignment operator.

constexpr	timestamp_array (timestamp_array &&rhs)
	Move constructor.

constexpr timestamp_array &	operator= (timestamp_array &&rhs)
	Move assignment operator.

template<std::ranges::input_range R, input_metadata_container METADATA_RANGE> requires std::convertible_to<std::ranges::range_value_t<R>, T>
arrow_proxy	create_proxy (const date::time_zone *timezone, R &&range, bool nullable, std::optional< std::string_view > name, std::optional< METADATA_RANGE > metadata)

Public Member Functions inherited from sparrow::array_bitmap_base_impl< D, true >
constexpr auto	insert_bitmap (const_bitmap_iterator pos, InputIt first, InputIt last) -> bitmap_iterator is_mutable

constexpr auto	insert_bitmap (const_bitmap_iterator pos, InputIt first, InputIt last) -> bitmap_iterator is_mutable

Friends
class	timestamp_reference< self_type >

Additional Inherited Members
Protected Member Functions inherited from sparrow::array_bitmap_base_impl< D, true >
	array_bitmap_base_impl (arrow_proxy proxy)
	Constructs array bitmap base from Arrow proxy.

constexpr	array_bitmap_base_impl (const array_bitmap_base_impl &)
	Copy constructor.

constexpr array_bitmap_base_impl &	operator= (const array_bitmap_base_impl &)
	Copy assignment operator.

constexpr	array_bitmap_base_impl (array_bitmap_base_impl &&) noexcept=default

constexpr array_bitmap_base_impl &	operator= (array_bitmap_base_impl &&) noexcept=default

constexpr bitmap_type &	get_bitmap ()
	Gets mutable reference to the validity bitmap.

constexpr const bitmap_type &	get_bitmap () const
	Gets const reference to the validity bitmap.

constexpr void	resize_bitmap (size_type new_length, bool value)
	Resizes the validity bitmap to accommodate new array length.

constexpr bitmap_iterator	insert_bitmap (const_bitmap_iterator pos, bool value, size_type count)
	Inserts validity bits at specified position.

constexpr bitmap_iterator	insert_bitmap (const_bitmap_iterator pos, InputIt first, InputIt last) is_mutable
	Inserts range of validity bits at specified position.

constexpr bitmap_iterator	erase_bitmap (const_bitmap_iterator pos, size_type count)
	Erases validity bits starting at specified position.

constexpr void	update ()
	Updates internal bitmap after external modifications to Arrow data.

constexpr non_owning_dynamic_bitset< uint8_t >	get_non_owning_dynamic_bitset ()
	Gets non-owning view of the bitmap as dynamic bitset.

constexpr bitmap_type	make_bitmap ()
	Creates bitmap wrapper from current Arrow validity buffer.

	array_bitmap_base_impl (arrow_proxy proxy)
	Constructs array bitmap base from Arrow proxy.

constexpr	array_bitmap_base_impl (const array_bitmap_base_impl &)
	Copy constructor.

constexpr	array_bitmap_base_impl (array_bitmap_base_impl &&) noexcept=default

constexpr array_bitmap_base_impl &	operator= (const array_bitmap_base_impl &)
	Copy assignment operator.

constexpr array_bitmap_base_impl &	operator= (array_bitmap_base_impl &&) noexcept=default

constexpr bitmap_type &	get_bitmap ()
	Gets mutable reference to the validity bitmap.

constexpr const bitmap_type &	get_bitmap () const
	Gets const reference to the validity bitmap.

constexpr void	resize_bitmap (size_type new_length, bool value)
	Resizes the validity bitmap to accommodate new array length.

constexpr bitmap_iterator	insert_bitmap (const_bitmap_iterator pos, bool value, size_type count)
	Inserts validity bits at specified position.

constexpr bitmap_iterator	insert_bitmap (const_bitmap_iterator pos, InputIt first, InputIt last) is_mutable
	Inserts range of validity bits at specified position.

constexpr bitmap_iterator	erase_bitmap (const_bitmap_iterator pos, size_type count)
	Erases validity bits starting at specified position.

constexpr void	update ()
	Updates internal bitmap after external modifications to Arrow data.

constexpr non_owning_dynamic_bitset< uint8_t >	get_non_owning_dynamic_bitset ()
	Gets non-owning view of the bitmap as dynamic bitset.

constexpr bitmap_type	make_bitmap ()
	Creates bitmap wrapper from current Arrow validity buffer.

Detailed Description

template<timestamp_type T>
class sparrow::timestamp_array< T >

Array implementation for storing timestamp values with timezone information.

The timestamp_array provides efficient storage for datetime values with precise duration types and timezone awareness. It stores timestamps as duration values since the Unix epoch while maintaining timezone information for proper interpretation and conversion.

Key features:

Timezone-aware timestamp storage
Support for multiple precision levels (seconds to nanoseconds)
Efficient columnar memory layout
Arrow format compatibility
Nullable timestamp support via validity bitmap
Mutable operations (insert, erase, resize)

The array internally stores:

A validity bitmap for null/non-null timestamp tracking
A contiguous buffer of duration values since Unix epoch
Timezone pointer for proper timestamp interpretation

Supported timestamp types:

Template Parameters

T	The timestamp type with specific duration precision

Precondition: T must satisfy the timestamp_type concept; T must be one of the supported timestamp duration types

Postcondition: Maintains Arrow temporal format compatibility; All stored timestamps reference the same timezone; Thread-safe for read operations, requires external synchronization for writes

//Create timestamp array with New York timezone
const auto* ny_tz = date::locate_zone("America/New_York");
std::vector<timestamp_second> timestamps = {
timestamp_second{ny_tz, std::chrono::sys_seconds{std::chrono::seconds{1609459200}}}, // 2021-01-01
timestamp_second{ny_tz, std::chrono::sys_seconds{std::chrono::seconds{1609545600}}}  // 2021-01-02
};
 
timestamp_seconds_array arr(ny_tz, timestamps);
 
//Access timestamps
auto first = arr[0];
if(first.has_value()) {
auto ts = first.value();  // timezone-aware timestamp
}

Examples: timestamp_example.cpp.

Definition at line 197 of file timestamp_array.hpp.

Member Typedef Documentation

◆ base_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::base_type = mutable_array_bitmap_base<self_type>

Definition at line 202 of file timestamp_array.hpp.

◆ bitmap_const_reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::bitmap_const_reference = typename base_type::bitmap_const_reference

Definition at line 211 of file timestamp_array.hpp.

◆ bitmap_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::bitmap_iterator = typename base_type::bitmap_iterator

Definition at line 212 of file timestamp_array.hpp.

◆ bitmap_range

template<timestamp_type T>

using sparrow::timestamp_array< T >::bitmap_range = typename base_type::bitmap_range

Definition at line 214 of file timestamp_array.hpp.

◆ bitmap_reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::bitmap_reference = typename base_type::bitmap_reference

Definition at line 210 of file timestamp_array.hpp.

◆ bitmap_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::bitmap_type = typename base_type::bitmap_type

Definition at line 209 of file timestamp_array.hpp.

◆ buffer_inner_const_value_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::buffer_inner_const_value_iterator = pointer_iterator<const buffer_inner_value_type*>

Definition at line 237 of file timestamp_array.hpp.

◆ buffer_inner_value_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::buffer_inner_value_iterator = pointer_iterator<buffer_inner_value_type*>

Definition at line 236 of file timestamp_array.hpp.

◆ buffer_inner_value_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::buffer_inner_value_type = inner_value_type_duration::rep

Definition at line 235 of file timestamp_array.hpp.

◆ const_bitmap_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_bitmap_iterator = typename base_type::const_bitmap_iterator

Definition at line 213 of file timestamp_array.hpp.

◆ const_bitmap_range

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_bitmap_range = typename base_type::const_bitmap_range

Definition at line 215 of file timestamp_array.hpp.

◆ const_functor_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_functor_type = typename inner_types::const_functor_type

Definition at line 232 of file timestamp_array.hpp.

◆ const_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_iterator = typename base_type::const_iterator

Definition at line 229 of file timestamp_array.hpp.

◆ const_reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_reference = nullable<inner_const_reference, bitmap_const_reference>

Definition at line 219 of file timestamp_array.hpp.

◆ const_value_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::const_value_iterator = typename base_type::const_value_iterator

Definition at line 226 of file timestamp_array.hpp.

◆ difference_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::difference_type = typename base_type::difference_type

Definition at line 222 of file timestamp_array.hpp.

◆ functor_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::functor_type = typename inner_types::functor_type

Definition at line 231 of file timestamp_array.hpp.

◆ inner_const_reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::inner_const_reference = typename inner_types::inner_const_reference

Definition at line 207 of file timestamp_array.hpp.

◆ inner_reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::inner_reference = typename inner_types::inner_reference

Definition at line 206 of file timestamp_array.hpp.

◆ inner_types

template<timestamp_type T>

using sparrow::timestamp_array< T >::inner_types = array_inner_types<self_type>

Definition at line 204 of file timestamp_array.hpp.

◆ inner_value_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::inner_value_type = typename inner_types::inner_value_type

Definition at line 205 of file timestamp_array.hpp.

◆ inner_value_type_duration

template<timestamp_type T>

using sparrow::timestamp_array< T >::inner_value_type_duration = inner_value_type::duration

Definition at line 234 of file timestamp_array.hpp.

◆ iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::iterator = typename base_type::iterator

Definition at line 228 of file timestamp_array.hpp.

◆ iterator_tag

template<timestamp_type T>

using sparrow::timestamp_array< T >::iterator_tag = typename base_type::iterator_tag

Definition at line 223 of file timestamp_array.hpp.

◆ reference

template<timestamp_type T>

using sparrow::timestamp_array< T >::reference = nullable<inner_reference, bitmap_reference>

Definition at line 218 of file timestamp_array.hpp.

◆ self_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::self_type = timestamp_array

Definition at line 201 of file timestamp_array.hpp.

◆ size_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::size_type = typename base_type::size_type

Definition at line 221 of file timestamp_array.hpp.

◆ value_iterator

template<timestamp_type T>

using sparrow::timestamp_array< T >::value_iterator = typename base_type::value_iterator

Definition at line 225 of file timestamp_array.hpp.

◆ value_type

template<timestamp_type T>

using sparrow::timestamp_array< T >::value_type = nullable<inner_value_type>

Definition at line 217 of file timestamp_array.hpp.

Constructor & Destructor Documentation

◆ timestamp_array() [1/5]

template<timestamp_type T>

sparrow::timestamp_array< T >::timestamp_array ( arrow_proxy proxy )

explicit

Constructs timestamp array from Arrow proxy.

Parameters

proxy Arrow proxy containing timestamp array data and schema

Precondition: proxy must contain valid Arrow timestamp array and schema; proxy format must match expected timestamp format for T; proxy schema must include valid timezone information

Postcondition: Array is initialized with data from proxy; Timezone is extracted from schema metadata; Data access is properly configured for duration type

Definition at line 674 of file timestamp_array.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ timestamp_array() [2/5]

template<timestamp_type T>

template<class... Args>
requires (mpl::excludes_copy_and_move_ctor_v<timestamp_array, Args...>)

sparrow::timestamp_array< T >::timestamp_array ( Args &&... args )

inlineexplicitconstexpr

Generic constructor for creating timestamp arrays from various inputs.

Creates a timestamp array from different input combinations including timezone, values, validity information, and metadata. Arguments are forwarded to compatible create_proxy() functions.

The first argument must always be a const date::time_zone* pointer. Subsequent arguments can include:

Range of timestamp values
Validity bitmap or boolean range
Individual count and fill value
Array name and metadata

Template Parameters

Args	Parameter pack for constructor arguments

Parameters

args	Constructor arguments starting with timezone

Precondition: First argument must be valid date::time_zone pointer; Remaining arguments must match one of the create_proxy() signatures; Args must exclude copy and move constructor signatures

Postcondition: Array is created with specified timezone and data; All timestamps reference the provided timezone

//Various construction patterns
const auto* utc = date::locate_zone("UTC");
 
//From range with validity
std::vector<timestamp_second> values = {...};
std::vector<bool> validity = {...};
timestamp_seconds_array arr1(utc, values, validity);
 
//From range, nullable
timestamp_seconds_array arr2(utc, values, true);
 
//From count and fill value
timestamp_seconds_array arr3(utc, 100, timestamp_second{...});

Definition at line 294 of file timestamp_array.hpp.

◆ timestamp_array() [3/5]

template<timestamp_type T>

template<input_metadata_container METADATA_RANGE = std::vector<metadata_pair>>

sparrow::timestamp_array< T >::timestamp_array	(	const date::time_zone *	timezone,
		std::initializer_list< inner_value_type >	init,
		std::optional< std::string_view >	name = std::nullopt,
		std::optional< METADATA_RANGE >	metadata = std::nullopt )

inlineconstexpr

Constructs timestamp array from initializer list.

Template Parameters

METADATA_RANGE Type of metadata container

Parameters

timezone	Timezone for all timestamps in the array
init	Initializer list of timestamp values
name	Optional name for the array
metadata	Optional metadata key-value pairs

Precondition: timezone must be a valid date::time_zone pointer; All timestamps in init should reference the same timezone

Postcondition: Array contains timestamps from initializer list; All timestamps use the specified timezone

Definition at line 316 of file timestamp_array.hpp.

◆ timestamp_array() [4/5]

template<timestamp_type T>

sparrow::timestamp_array< T >::timestamp_array ( const timestamp_array< T > & rhs )

constexpr

Copy constructor.

Parameters

rhs	Source timestamp array to copy from

Precondition: rhs must be in a valid state

Postcondition: This array contains a deep copy of rhs data; Timezone pointer is copied (shared reference); Data access is reinitialized for this array

Definition at line 640 of file timestamp_array.hpp.

Here is the call graph for this function:

◆ timestamp_array() [5/5]

template<timestamp_type T>

sparrow::timestamp_array< T >::timestamp_array ( timestamp_array< T > && rhs )

constexpr

Move constructor.

Parameters

rhs	Source timestamp array to move from

Postcondition: This array takes ownership of rhs data; rhs is left in a valid but unspecified state; Timezone and data access are properly transferred

Definition at line 657 of file timestamp_array.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ create_proxy()

template<timestamp_type T>

template<std::ranges::input_range R, input_metadata_container METADATA_RANGE>
requires std::convertible_to<std::ranges::range_value_t<R>, T>

arrow_proxy sparrow::timestamp_array< T >::create_proxy	(	const date::time_zone *	timezone,
		R &&	range,
		bool	nullable,
		std::optional< std::string_view >	name,
		std::optional< METADATA_RANGE >	metadata )

Definition at line 751 of file timestamp_array.hpp.

◆ operator=() [1/2]

template<timestamp_type T>

timestamp_array< T > & sparrow::timestamp_array< T >::operator= ( const timestamp_array< T > & rhs )

constexpr

Copy assignment operator.

Parameters

rhs	Source timestamp array to copy from

Returns: Reference to this array

Precondition: rhs must be in a valid state

Postcondition: This array contains a deep copy of rhs data; Previous data is properly released; Timezone and data access are updated

Definition at line 648 of file timestamp_array.hpp.

Here is the call graph for this function:

◆ operator=() [2/2]

template<timestamp_type T>

timestamp_array< T > & sparrow::timestamp_array< T >::operator= ( timestamp_array< T > && rhs )

constexpr

Move assignment operator.

Parameters

rhs	Source timestamp array to move from

Returns: Reference to this array

Postcondition: This array takes ownership of rhs data; Previous data is properly released; rhs is left in a valid but unspecified state

Definition at line 665 of file timestamp_array.hpp.

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ timestamp_reference< self_type >

template<timestamp_type T>

friend class timestamp_reference< self_type >

friend

Definition at line 630 of file timestamp_array.hpp.

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

/home/runner/work/sparrow/sparrow/include/sparrow/timestamp_array.hpp

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ base_type

◆ bitmap_const_reference

◆ bitmap_iterator

◆ bitmap_range

◆ bitmap_reference

◆ bitmap_type

◆ buffer_inner_const_value_iterator

◆ buffer_inner_value_iterator

◆ buffer_inner_value_type

◆ const_bitmap_iterator

◆ const_bitmap_range

◆ const_functor_type

◆ const_iterator

◆ const_reference

◆ const_value_iterator

◆ difference_type

◆ functor_type

◆ inner_const_reference

◆ inner_reference

◆ inner_types

◆ inner_value_type

◆ inner_value_type_duration

◆ iterator

◆ iterator_tag

◆ reference

◆ self_type

◆ size_type

◆ value_iterator

◆ value_type

Constructor & Destructor Documentation

◆ timestamp_array() [1/5]

◆ timestamp_array() [2/5]

◆ timestamp_array() [3/5]

◆ timestamp_array() [4/5]

◆ timestamp_array() [5/5]

Member Function Documentation

◆ create_proxy()

◆ operator=() [1/2]

◆ operator=() [2/2]

Friends And Related Symbol Documentation

◆ timestamp_reference< self_type >