Rename specificity to priority

Author: CathalMullan

CHANGELOG.md

@@ -29,7 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Improved detection of structural conflicts.
-- Correcting routing specificity for inline parameters.
+- Correcting routing priority for inline parameters.
 
 ## [0.8.1] - 2025-01-07
 

src/lib.rs

@@ -119,20 +119,12 @@
 //!
 //! Templates are matched using a hierarchical priority system.
 //!
-//! ### 1. Kind
-//!
 //! From highest priority to lowest, we walk the current nodes children in this order:
 //! - statics
 //! - dynamics
 //! - wildcards
 //! - end wildcards
 //!
-//! In the event of multiple children of the same type, we walk them in alphabetical order, to ensure order remains predictable.
-//!
-//! ### 2. Structure
-//!
-//! When comparing templates at the same node level and of the same kind, we prefer the "more specific" template.
-//!
 //! ## Display
 //!
 //! The router can be printed as a tree, via a [`Display`](std::fmt::Display) implementation.
@@ -156,5 +148,5 @@ mod parser;
 mod router;
 pub use router::{Match, Router};
 
-mod specificity;
+mod priority;
 mod state;

src/node.rs

@@ -2,7 +2,7 @@ use alloc::{boxed::Box, string::String, vec::Vec};
 use core::cmp::Ordering;
 
 use crate::{
-    specificity::Specificity,
+    priority::Priority,
     state::{DynamicState, EndWildcardState, StaticState, WildcardState},
 };
 
@@ -22,8 +22,8 @@ pub struct NodeData {
     /// This nodes template.
     pub template: String,
 
-    /// The specificity of the template.
-    pub specificity: Specificity,
+    /// The priority of the template.
+    pub priority: Priority,
 }
 
 /// Represents a node in the tree structure.
@@ -46,7 +46,7 @@ pub struct Node<S> {
     pub wildcard_segment_only: bool,
 
     /// Flag indicating whether this node need optimization.
-    /// During optimization, the shortcut flags are updated, specificity calculated, and nodes sorted.
+    /// During optimization, the shortcut flags are updated, priority calculated, and nodes sorted.
     pub needs_optimization: bool,
 }
 

src/node/optimize.rs

@@ -1,40 +1,40 @@
-use crate::{node::Node, specificity::Specificity};
+use crate::{node::Node, priority::Priority};
 
 impl<S> Node<S> {
     /// Optimizes the tree structure.
     pub(crate) fn optimize(&mut self) {
-        self.optimize_inner(Specificity::default());
+        self.optimize_inner(Priority::default());
     }
 
     /// Recursively optimizes nodes from root to leaf.
     /// We can skip optimization if the current node hasn't changed.
-    fn optimize_inner(&mut self, parent: Specificity) {
+    fn optimize_inner(&mut self, parent: Priority) {
         if !self.needs_optimization {
             return;
         }
 
         if let Some(data) = &mut self.data {
-            data.specificity = parent.clone();
+            data.priority = parent.clone();
         }
 
         for child in &mut self.static_children {
-            let child_specificity = parent.clone().with_static(child.state.prefix.len());
-            child.optimize_inner(child_specificity);
+            let child_priority = parent.clone().with_static(child.state.prefix.len());
+            child.optimize_inner(child_priority);
         }
 
         for child in &mut self.dynamic_children {
-            let child_specificity = parent.clone().with_dynamic();
-            child.optimize_inner(child_specificity);
+            let child_priority = parent.clone().with_dynamic();
+            child.optimize_inner(child_priority);
         }
 
         for child in &mut self.wildcard_children {
-            let child_specificity = parent.clone().with_wildcard();
-            child.optimize_inner(child_specificity);
+            let child_priority = parent.clone().with_wildcard();
+            child.optimize_inner(child_priority);
         }
 
         if let Some(child) = &mut self.end_wildcard {
-            let child_specificity = parent.with_wildcard();
-            child.optimize_inner(child_specificity);
+            let child_priority = parent.with_wildcard();
+            child.optimize_inner(child_priority);
         }
 
         self.static_children.sort();

src/node/search.rs

@@ -99,7 +99,7 @@ impl<S> Node<S> {
 
     /// Slower dynamic path for complex templates like `/<name>.<extension>`.
     /// Must try each byte to consider all possible permutations.
-    /// Prefers the most specific match.
+    /// Prefers the most specific match, via backtracking.
     fn search_dynamic_inline<'r, 'p>(
         &'r self,
         path: &'p [u8],
@@ -127,7 +127,7 @@ impl<S> Node<S> {
                     continue;
                 };
 
-                if best_match.is_none_or(|best| data.specificity >= best.specificity) {
+                if best_match.is_none_or(|best| data.priority >= best.priority) {
                     best_match = Some(data);
                     best_match_parameters = current_parameters;
                 }
@@ -199,7 +199,7 @@ impl<S> Node<S> {
 
     /// Slower wildcard path for complex templates like `/<*name>.txt`.
     /// Must try each byte, since the wildcard ends mid-segment.
-    /// Prefers the most specific match.
+    /// Prefers the most specific match, via backtracking.
     fn search_wildcard_inline<'r, 'p>(
         &'r self,
         path: &'p [u8],
@@ -223,7 +223,7 @@ impl<S> Node<S> {
                     continue;
                 };
 
-                if best_match.is_none_or(|best| data.specificity >= best.specificity) {
+                if best_match.is_none_or(|best| data.priority >= best.priority) {
                     best_match = Some(data);
                     best_match_parameters = current_parameters;
                 }

src/specificity.rs renamed to src/priority.rs

@@ -7,13 +7,13 @@ use core::cmp::Ordering;
 /// 2. Dynamic parameter count: less dynamics, more specific
 /// 3. Wildcard parameter count: less wildcards, more specific
 #[derive(Clone, Eq, PartialEq, Debug, Default)]
-pub struct Specificity {
+pub struct Priority {
     pub static_length: usize,
     pub dynamics_count: usize,
     pub wildcards_count: usize,
 }
 
-impl Specificity {
+impl Priority {
     pub const fn with_static(mut self, length: usize) -> Self {
         self.static_length += length;
         self
@@ -30,13 +30,13 @@ impl Specificity {
     }
 }
 
-impl PartialOrd for Specificity {
+impl PartialOrd for Priority {
     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
         Some(self.cmp(other))
     }
 }
 
-impl Ord for Specificity {
+impl Ord for Priority {
     fn cmp(&self, other: &Self) -> Ordering {
         self.static_length
             .cmp(&other.static_length)

src/router.rs

@@ -8,7 +8,7 @@ use crate::{
     errors::{DeleteError, InsertError},
     node::{Node, NodeData},
     parser::Template,
-    specificity::Specificity,
+    priority::Priority,
     state::RootState,
 };
 
@@ -94,7 +94,7 @@ impl<T> Router<T> {
             NodeData {
                 key,
                 template: template.to_owned(),
-                specificity: Specificity::default(),
+                priority: Priority::default(),
             },
         );