pub struct TimeIndex { /* private fields */ }Expand description
Sorted union of the timestamps of all series, with stable logical indices.
The slot of times()[k] has logical index first_index() + k. A new index
starts at logical index 0; prepend moves first_index() down so that the
existing timestamps keep their indices.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::from_times(vec![100, 200, 300])?;
index.append(&[400])?;
index.prepend(&[0, 50])?;
// Existing timestamps keep their logical index; history gets negative ones.
assert_eq!(index.index_of(100), Some(0));
assert_eq!(index.index_of(0), Some(-2));
assert_eq!(index.time_at(3), Some(400));
assert_eq!((index.first_index(), index.end_index()), (-2, 4));Implementations§
Source§impl TimeIndex
impl TimeIndex
Sourcepub const fn new() -> Self
pub const fn new() -> Self
Creates an empty index. Its first slot will get logical index 0.
§Examples
use ferrochart_core::data::TimeIndex;
assert!(TimeIndex::new().is_empty());Sourcepub fn from_times(times: Vec<Timestamp>) -> Result<Self>
pub fn from_times(times: Vec<Timestamp>) -> Result<Self>
Builds an index from timestamps without copying them. Logical indices start at 0.
§Errors
Error::TimeNotIncreasing if times is not strictly increasing.
§Examples
use ferrochart_core::{Error, data::TimeIndex};
assert_eq!(TimeIndex::from_times(vec![1, 2, 2]), Err(Error::TimeNotIncreasing { index: 2 }));
assert_eq!(TimeIndex::from_times(vec![1, 2, 3])?.len(), 3);Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Number of slots.
§Examples
use ferrochart_core::data::TimeIndex;
assert_eq!(TimeIndex::from_times(vec![5, 6])?.len(), 2);Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Whether there are no slots.
§Examples
use ferrochart_core::data::TimeIndex;
assert!(TimeIndex::default().is_empty());Sourcepub fn times(&self) -> &[Timestamp]
pub fn times(&self) -> &[Timestamp]
All timestamps, sorted, as one slice. times()[k] has logical index
first_index() + k.
§Examples
use ferrochart_core::data::TimeIndex;
let index = TimeIndex::from_times(vec![5, 6])?;
assert_eq!(index.times(), &[5, 6]);Sourcepub fn first_index(&self) -> i64
pub fn first_index(&self) -> i64
Logical index of the first slot.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::from_times(vec![5, 6])?;
index.prepend(&[1, 2, 3])?;
assert_eq!(index.first_index(), -3);Sourcepub fn end_index(&self) -> i64
pub fn end_index(&self) -> i64
Logical index one past the last slot (first_index() + len()).
§Examples
use ferrochart_core::data::TimeIndex;
assert_eq!(TimeIndex::from_times(vec![5, 6])?.end_index(), 2);Sourcepub fn time_at(&self, index: i64) -> Option<Timestamp>
pub fn time_at(&self, index: i64) -> Option<Timestamp>
Timestamp of the slot with logical index index, or None outside the data.
§Examples
use ferrochart_core::data::TimeIndex;
let index = TimeIndex::from_times(vec![5, 6])?;
assert_eq!(index.time_at(1), Some(6));
assert_eq!(index.time_at(2), None);
assert_eq!(index.time_at(-1), None);Sourcepub fn index_of(&self, time: Timestamp) -> Option<i64>
pub fn index_of(&self, time: Timestamp) -> Option<i64>
Logical index of time if it is in the index. O(log n).
§Examples
use ferrochart_core::data::TimeIndex;
let index = TimeIndex::from_times(vec![5, 6])?;
assert_eq!(index.index_of(6), Some(1));
assert_eq!(index.index_of(7), None);Sourcepub fn lower_bound(&self, time: Timestamp) -> i64
pub fn lower_bound(&self, time: Timestamp) -> i64
Logical index of the first slot whose time is >= time; end_index() if
there is none. O(log n).
§Examples
use ferrochart_core::data::TimeIndex;
let index = TimeIndex::from_times(vec![10, 20, 30])?;
assert_eq!(index.lower_bound(20), 1);
assert_eq!(index.lower_bound(21), 2);
assert_eq!(index.lower_bound(99), 3);Sourcepub fn append(&mut self, times: &[Timestamp]) -> Result<()>
pub fn append(&mut self, times: &[Timestamp]) -> Result<()>
Appends new slots after the last one. Existing logical indices are unchanged.
§Errors
Error::TimeNotIncreasingiftimesis not strictly increasing or its first element is not after the current last timestamp (indexrefers totimes);Error::OutOfMemoryif the allocation fails.
The index is unchanged on error.
§Examples
use ferrochart_core::{Error, data::TimeIndex};
let mut index = TimeIndex::from_times(vec![10, 20])?;
assert_eq!(index.append(&[20]), Err(Error::TimeNotIncreasing { index: 0 }));
index.append(&[30, 40])?;
assert_eq!(index.times(), &[10, 20, 30, 40]);Sourcepub fn prepend(&mut self, times: &[Timestamp]) -> Result<()>
pub fn prepend(&mut self, times: &[Timestamp]) -> Result<()>
Inserts older slots before the first one (loading history). Existing
timestamps keep their logical indices; the new ones get the indices just
below first_index().
§Errors
Error::TimeNotIncreasingiftimesis not strictly increasing or its last element is not before the current first timestamp (indexrefers totimes);Error::InvalidArgumentif the logical index would overflowi64;Error::OutOfMemoryif the allocation fails.
The index is unchanged on error.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::from_times(vec![30, 40])?;
index.prepend(&[10, 20])?;
assert_eq!(index.times(), &[10, 20, 30, 40]);
assert_eq!(index.index_of(30), Some(0));
assert_eq!(index.index_of(10), Some(-2));Sourcepub fn map_series(&self, times: &[Timestamp]) -> Result<Option<SeriesMapping>>
pub fn map_series(&self, times: &[Timestamp]) -> Result<Option<SeriesMapping>>
Maps a series’ timestamps onto the index.
Returns Some(Aligned) if times equals a contiguous run of the index,
Some(Mapped) if it is a sparse subset, and None if it contains a
timestamp that is not in the index or is not strictly increasing (the
caller then has to merge). An empty
series maps to Aligned { first: end_index() }.
Cost: O(m) when aligned, O(m log n) otherwise (m = times.len()).
§Errors
Error::InvalidArgumentif a mapped series spans more thanu32::MAXslots;Error::OutOfMemoryif the offset table cannot be allocated.
§Examples
use ferrochart_core::data::{SeriesMapping, TimeIndex};
let index = TimeIndex::from_times(vec![10, 20, 30])?;
assert_eq!(index.map_series(&[10, 20, 30])?, Some(SeriesMapping::Aligned { first: 0 }));
assert_eq!(
index.map_series(&[10, 30])?,
Some(SeriesMapping::Mapped { first: 0, offsets: vec![0, 2] }),
);
assert_eq!(index.map_series(&[30, 10])?, None); // not increasingSourcepub fn merge(&mut self, times: &[Timestamp]) -> Result<usize>
pub fn merge(&mut self, times: &[Timestamp]) -> Result<usize>
Merges timestamps that are not yet in the index, keeping it sorted, and returns how many slots were inserted.
Timestamps before the current first one get logical indices below
first_index(), so those slots behave like a prepend. Any timestamp
inserted between existing ones shifts the logical index of every later
slot: the caller must then rebuild everything that stores logical indices
(series mappings, LOD, GPU buffers) and report a warning. O(n + m).
§Errors
Error::TimeNotIncreasingiftimesis not strictly increasing;Error::InvalidArgumentif the logical index would overflowi64;Error::OutOfMemoryif the allocation fails.
The index is unchanged on error.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::from_times(vec![10, 20, 30])?;
assert_eq!(index.merge(&[5, 20, 25])?, 2);
assert_eq!(index.times(), &[5, 10, 20, 25, 30]);
assert_eq!(index.index_of(10), Some(0)); // before the first insertion: unchanged
assert_eq!(index.index_of(30), Some(3)); // after an inner insertion: shiftedSourcepub fn reserve_back(&mut self, additional: usize) -> Result<()>
pub fn reserve_back(&mut self, additional: usize) -> Result<()>
Reserves room for additional slots after the last one, so that a later
append of that many cannot fail with OutOfMemory.
§Errors
Error::OutOfMemory if the allocation fails.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::new();
index.reserve_back(10)?;Sourcepub fn reserve_front(&mut self, additional: usize) -> Result<()>
pub fn reserve_front(&mut self, additional: usize) -> Result<()>
Reserves room for additional slots before the first one, so that a later
prepend of that many cannot fail with OutOfMemory.
§Errors
Error::OutOfMemory if the allocation fails.
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::new();
index.reserve_front(10)?;Sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Releases growth slack (called after set_data).
§Examples
use ferrochart_core::data::TimeIndex;
let mut index = TimeIndex::new();
index.append(&[1, 2, 3])?;
index.shrink_to_fit();
assert_eq!(index.len(), 3);