Skip to main content

TimeIndex

Struct TimeIndex 

Source
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

Source

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());
Source

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);
Source

pub fn len(&self) -> usize

Number of slots.

§Examples
use ferrochart_core::data::TimeIndex;

assert_eq!(TimeIndex::from_times(vec![5, 6])?.len(), 2);
Source

pub fn is_empty(&self) -> bool

Whether there are no slots.

§Examples
use ferrochart_core::data::TimeIndex;

assert!(TimeIndex::default().is_empty());
Source

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]);
Source

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);
Source

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);
Source

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);
Source

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);
Source

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);
Source

pub fn append(&mut self, times: &[Timestamp]) -> Result<()>

Appends new slots after the last one. Existing logical indices are unchanged.

§Errors

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]);
Source

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

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));
Source

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
§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 increasing
Source

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

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: shifted
Source

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)?;
Source

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)?;
Source

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

Trait Implementations§

Source§

impl Clone for TimeIndex

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for TimeIndex

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for TimeIndex

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Eq for TimeIndex

Source§

impl PartialEq for TimeIndex

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for TimeIndex

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.