Struct StateStack 

pub struct StateStack { /* private fields */ }

A Vec-based save/restore stack of GraphicsState values.

Replaces the raw-pointer linked list (SplashState *next) in the C++ original.

Stack invariant

The stack always contains at least one entry — the initial state passed to StateStack::new. This invariant is established by the constructor and maintained by every method:

• save only pushes (depth grows).
• restore refuses to pop the last entry and signals this via its bool return value.

Because the invariant holds unconditionally, the .last() / .last_mut() calls in current, current_mut, and save can never return None. The .expect() calls there exist solely to surface a bug if the invariant is ever broken during development.

Implementations

impl StateStack

pub fn new(initial: GraphicsState) -> Self

Create a new stack with initial as the sole (bottom) state.

After construction, depth returns 1.

pub fn current(&self) -> &GraphicsState

Borrow the current (top) state.

Panics

Never panics in correct code — the stack invariant guarantees at least one entry at all times. The expect is a development-time tripwire.

pub fn current_mut(&mut self) -> &mut GraphicsState

Mutably borrow the current state.

Panics

Never panics in correct code — the stack invariant guarantees at least one entry at all times. The expect is a development-time tripwire.

pub fn save(&mut self)

Push a clone of the current state (PDF q operator).

Panics

Never panics in correct code — the stack invariant guarantees at least one entry at all times. The expect is a development-time tripwire.

pub fn restore(&mut self) -> bool

Pop the top state (PDF Q operator).

Returns true on success.

Returns false — without modifying the stack — when the stack is at depth 1 (only the initial state remains). The initial state is never popped; this preserves the stack invariant (depth ≥ 1).

Callers that receive false should treat it as an unmatched Q operator and continue rendering with the current state unchanged.

pub const fn depth(&self) -> usize

Current nesting depth (1 = only the initial state, no saves in progress).