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	const_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) noexcept
	Move constructor.
constexpr timestamp_array &	operator= (timestamp_array &&rhs) noexcept
	Move assignment operator.
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

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 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)
	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.

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 208 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 213 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 222 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 223 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 225 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 221 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 220 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 248 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 247 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 246 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 224 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 226 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 243 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 240 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 230 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 237 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 233 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 242 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 218 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 217 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 215 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 216 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 245 of file timestamp_array.hpp.

◆ iterator

template<timestamp_type T>

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

Definition at line 239 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 234 of file timestamp_array.hpp.

◆ reference

template<timestamp_type T>

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

Definition at line 229 of file timestamp_array.hpp.

◆ self_type

template<timestamp_type T>

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

Definition at line 212 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 232 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 236 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 228 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 910 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 305 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 327 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 874 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 )

constexprnoexcept

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 893 of file timestamp_array.hpp.

Here is the call graph for this function:

Member Function Documentation

◆ 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 883 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 )

constexprnoexcept

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 901 of file timestamp_array.hpp.

Here is the call graph for this function:

◆ timestamp_reference< self_type >

template<timestamp_type T>

friend class timestamp_reference< self_type >

friend

Definition at line 864 of file timestamp_array.hpp.

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

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

◆ operator=() [1/2]

◆ operator=() [2/2]

Friends And Related Symbol Documentation

◆ timestamp_reference< self_type >