Struct RouterState 

pub struct RouterState { /* private fields */ }

Core navigation state that tracks history, registered routes, and match cache.

This struct owns the navigation history stack and provides methods for pushing, replacing, and traversing entries. Route matching results are cached in a HashMap to avoid repeated tree walks within a single path.

Examples

use gpui_navigator::RouterState;

let mut state = RouterState::new();
assert_eq!(state.current_path(), "/");

state.push("/users".to_string());
assert_eq!(state.current_path(), "/users");

state.back();
assert_eq!(state.current_path(), "/");

Implementations

impl RouterState

pub fn new() -> Self

Create a new router state with the initial path set to "/".

pub fn navigation_id(&self) -> usize

Return the current navigation ID.

The value is monotonically increasing and is shared across clones of this state (via Arc<AtomicUsize>).

pub fn start_navigation(&self) -> usize

Start a new navigation and return the new navigation ID

This increments the navigation counter, allowing previous navigations to detect they’ve been superseded and should be cancelled.

pub fn is_navigation_current(&self, nav_id: usize) -> bool

Check if a navigation is still current (not cancelled by newer navigation)

pub fn add_route(&mut self, route: Route)

Register a route and invalidate the match cache.

Routes are stored in registration order. The first route whose pattern matches the current path wins during current_match.

pub fn current_path(&self) -> &str

Return the current path in the history stack.

pub fn routes(&self) -> &[Arc<Route>]

Return a slice of all registered routes (in registration order).

pub const fn current_params(&self) -> &RouteParams

Return the current route parameters (used for parameter inheritance in nested routing).

pub fn set_current_params(&mut self, params: RouteParams)

Update current route parameters

pub fn current_match(&mut self) -> Option<RouteMatch>

Find the RouteMatch for the current path, caching the result.

On a cache miss the registered routes are iterated in order and the first match is stored. Subsequent calls with the same path return the cached value in O(1).

pub fn current_match_immutable(&self) -> Option<RouteMatch>

Get current route match without caching (immutable)

Use this when you need to access the current route from a non-mutable context, such as in a GPUI Render implementation.

pub fn current_route(&self) -> Option<&Arc<Route>>

Get the first top-level Route that matches the current path.

With MatchStack architecture, rendering uses GlobalRouter::match_stack(). This method is kept for compatibility — it returns the first registered route whose pattern matches the current path (exact or prefix).

pub fn push(&mut self, path: String) -> RouteChangeEvent

Push a new path onto the history stack.

Any forward history (entries after the current cursor) is truncated before appending, mirroring browser pushState semantics.

Returns a RouteChangeEvent describing the transition.

pub fn push_with_state( &mut self, path: String, state: HistoryState, ) -> RouteChangeEvent

Push a new path with associated HistoryState data.

Allows attaching arbitrary key-value state (scroll position, form data, etc.) to the history entry.

pub fn replace(&mut self, path: String) -> RouteChangeEvent

Replace the current history entry in-place without adding a new one.

Useful for redirects where the intermediate path should not appear in the back-button history.

pub fn replace_with_state( &mut self, path: String, state: HistoryState, ) -> RouteChangeEvent

Replace the current history entry with associated HistoryState data.

pub fn back(&mut self) -> Option<RouteChangeEvent>

Move the cursor one step back in the history stack.

Returns None if already at the oldest entry.

pub fn forward(&mut self) -> Option<RouteChangeEvent>

Move the cursor one step forward in the history stack.

Returns None if already at the newest entry.

pub const fn can_go_back(&self) -> bool

Return true if back would succeed.

pub fn can_go_forward(&self) -> bool

Return true if forward would succeed.

pub fn peek_back_path(&self) -> Option<&str>

Peek at the path we would navigate to on back(), without actually navigating.

pub fn peek_forward_path(&self) -> Option<&str>

Peek at the path we would navigate to on forward(), without actually navigating.

pub fn current_entry(&self) -> &HistoryEntry

Return a reference to the current HistoryEntry (path + optional state).

pub fn clear(&mut self)

Reset the history stack to a single "/" entry, clearing the match cache.

Trait Implementations

impl Clone for RouterState

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RouterState

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

Formats the value using the given formatter.

impl Default for RouterState

fn default() -> Self

Returns the “default value” for a type.