Struct StateSeries 

pub struct StateSeries { /* private fields */ }

A growable homogeneous array of owned, time-ordered system states.

spec remains present even when the collection is empty, so later appends can be checked with constant-time layout identity. Each stored state carries its own cheap handle to the same immutable layout allocation and therefore remains independently valid after removal from the series.

Implementations

impl StateSeries

pub fn new(spec: SystemStateSchema) -> Self

Creates an empty series with no state capacity reserved.

This stores the supplied specification handle but allocates no state or payload storage. Use StateSeries::with_capacity when an analysis or reader already knows an approximate state count.

pub fn with_capacity(spec: SystemStateSchema, capacity: usize) -> Self

Creates an empty series with capacity for at least capacity states.

The reservation covers only SystemState owners in the backing vector. It does not create states, duplicate the shared layout, or allocate any scientific payload.

pub fn schema(&self) -> &SystemStateSchema

Returns the canonical immutable specification for this collection.

pub fn as_view(&self) -> StateSeriesView<'_>

Creates a copyable read-only view over the complete collection.

The view contains only borrowed references to the canonical specification and state slice. Constructing, copying, or cloning it never clones a state, layout, payload, or vector allocation.

pub fn len(&self) -> usize

Returns the number of states currently owned by the collection.

pub fn is_empty(&self) -> bool

Reports whether the collection currently owns no states.

pub fn capacity(&self) -> usize

Returns the backing vector’s current state-owner capacity.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more state owners.

Existing states and their payload allocations remain logically unchanged. As with Vec::reserve, the allocator may reserve more than the exact requested amount.

pub fn state_at(&self, position: usize) -> Option<&SystemState>

Returns one immutable state by zero-based collection position.

This follows slice conventions and returns None when position is outside the collection. The position is distinct from the state’s iteration because sampled iterations may contain gaps.

pub fn payload_mut_at<T>( &mut self, position: usize, key: &str, ) -> Result<&mut T, StateSeriesError>

where T: Any,

Mutably borrows one typed payload in one stored state.

This is the collection’s only mutable analysis boundary. It delegates concrete type validation to SystemState::payload_mut but does not expose the containing SystemState; callers therefore cannot change its time, clear unrelated fields, or replace it with a foreign layout.

Only one payload can be borrowed mutably at a time under ordinary Rust borrowing rules. Applications requiring coupled mutation should group the coupled values into one payload type.

Errors

Returns StateSeriesError::PositionOutOfBounds when no state exists at position. An unknown key, empty field, or concrete type mismatch is returned as StateSeriesError::PayloadAccess with the original crate::system_state::StateError preserved as its source.

pub fn first_state(&self) -> Option<&SystemState>

Returns the earliest stored state, or None when the series is empty.

pub fn last_state(&self) -> Option<&SystemState>

Returns the latest stored state, or None when the series is empty.

pub fn as_state_slice(&self) -> &[SystemState]

Returns every state as one immutable contiguous slice.

No mutable slice is exposed because element replacement could bypass both shared-layout validation and increasing-iteration validation.

pub fn iter(&self) -> Iter<'_, SystemState>

Returns an iterator over immutable states in increasing iteration order.

pub fn push_state( &mut self, state: SystemState, ) -> Result<(), StateSeriesPushError>

Appends one owned state after validating collection invariants.

Success moves state directly into the backing vector without cloning it or any payload. Failure returns StateSeriesPushError containing the complete unchanged state, allowing the caller to recover expensive data without cloning before the operation.

Errors

• StateSeriesError::SchemaMismatch if state does not share the exact canonical layout allocation;
• StateSeriesError::NonIncreasingIteration if its iteration is not greater than the current final iteration.

pub fn pop_state(&mut self) -> Option<SystemState>

Removes and returns the latest state without cloning its payloads.

A later append is compared with the new final state. Once empty, the series accepts any iteration from a state sharing its layout.

pub fn clear_states(&mut self)

Drops every state while retaining specification and vector capacity.

Stored payloads are dropped with their owning states. This method is an explicit analysis working-set operation and has no relationship to writer rollover or persistent chunks.

pub fn into_states(self) -> Vec<SystemState>

Consumes the series and returns its complete state vector.

The vector allocation, states, and payload allocations move unchanged. Dropping the separate canonical specification handle is safe because every returned state retains its own shared handle.

Trait Implementations

impl Clone for StateSeries

fn clone(&self) -> Self

Creates a fully independent deep copy of all states and payloads.

Performance warning

Cost scales with the complete populated payload volume and may involve gigabytes of allocation and copying. This method is appropriate only when analysis requires independent mutable payload ownership. Use StateSeries::as_view or an Arc<StateSeries> for lightweight sharing. The immutable specification allocation remains shared.

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

Performs copy-assignment from source.

impl Debug for StateSeries

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

Formats bounded structural context without traversing payload values.

impl<'a> IntoIterator for &'a StateSeries

fn into_iter(self) -> Self::IntoIter

Iterates over borrowed states without exposing mutable replacement.

type Item = &'a SystemState

The type of the elements being iterated over.

type IntoIter = Iter<'a, SystemState>

Which kind of iterator are we turning this into?

impl IntoIterator for StateSeries

fn into_iter(self) -> Self::IntoIter

Consumes the series and moves each owned state out in iteration order.

type Item = SystemState

The type of the elements being iterated over.

type IntoIter = IntoIter<SystemState>

Which kind of iterator are we turning this into?