More structured specificity approach

Author: CathalMullan

CHANGELOG.md

@@ -16,8 +16,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Raised MSRV from 1.63 to 1.85.
 - Switch to Rust 2024 edition.
-- Syntax for parameters has changed from `{name}` to `<name>`
-- Parameter characters `<` and `>` can no longer be escaped.
+- Syntax for parameters has changed from `{name}` to `<name>`, to remove ambiguity with formatted strings.
+- Parameter characters `<` and `>` can no longer be escaped, since they aren't valid URL characters anyways.
 - Display no longer shows nodes storing data.
 
 ### Removed
@@ -27,8 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Improved detection for structural conflicts.
-- Improved preference of more specific route matches.
+- Improved detection of structural conflicts.
+- Correcting routing specificity for inline parameters.
 
 ## [0.8.1] - 2025-01-07
 

src/errors/delete.rs

@@ -3,7 +3,7 @@ use core::error::Error;
 
 use crate::errors::TemplateError;
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Eq, PartialEq, Debug)]
 pub enum DeleteError {
     /// A [`TemplateError`] that occurred during the delete.
     Template(TemplateError),

src/errors/insert.rs

@@ -3,7 +3,7 @@ use core::error::Error;
 
 use crate::errors::TemplateError;
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Eq, PartialEq, Debug)]
 pub enum InsertError {
     /// A [`TemplateError`] that occurred during the insert.
     Template(TemplateError),

src/errors/template.rs

@@ -1,7 +1,7 @@
 use alloc::{fmt, string::String};
 use core::error::Error;
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Eq, PartialEq, Debug)]
 pub enum TemplateError {
     /// The template is empty.
     Empty,

src/lib.rs

@@ -156,4 +156,5 @@ mod parser;
 mod router;
 pub use router::{Match, Parameters, Router};
 
+mod specificity;
 mod state;

src/node.rs

@@ -1,7 +1,10 @@
 use alloc::{boxed::Box, string::String, vec::Vec};
 use core::cmp::Ordering;
 
-use crate::state::{DynamicState, EndWildcardState, StaticState, WildcardState};
+use crate::{
+    specificity::Specificity,
+    state::{DynamicState, EndWildcardState, StaticState, WildcardState},
+};
 
 mod conflict;
 mod delete;
@@ -11,7 +14,7 @@ mod insert;
 mod optimize;
 mod search;
 
-#[derive(Clone, Debug, Eq, PartialEq)]
+#[derive(Clone, Eq, PartialEq, Debug)]
 pub struct NodeData {
     /// The key to the stored data.
     pub key: usize,
@@ -20,11 +23,11 @@ pub struct NodeData {
     pub template: String,
 
     /// The specificity of the template.
-    pub specificity: usize,
+    pub specificity: Specificity,
 }
 
 /// Represents a node in the tree structure.
-#[derive(Clone, Debug, Eq, PartialEq)]
+#[derive(Clone, Eq, PartialEq, Debug)]
 pub struct Node<S> {
     /// The type of Node, and associated structure data.
     pub state: S,
@@ -40,7 +43,7 @@ pub struct Node<S> {
     pub end_wildcard: Option<Box<Node<EndWildcardState>>>,
 
     /// Flag indicating whether this node need optimization.
-    /// During optimization, the shortcut flags are updated, and nodes sorted.
+    /// During optimization, the shortcut flags are updated, specificity calculated, and nodes sorted.
     pub needs_optimization: bool,
 }
 

src/node/optimize.rs

@@ -1,25 +1,37 @@
-use crate::node::Node;
+use crate::{node::Node, specificity::Specificity};
 
 impl<S> Node<S> {
     pub(crate) fn optimize(&mut self) {
+        self.optimize_inner(Specificity::default());
+    }
+
+    fn optimize_inner(&mut self, parent: Specificity) {
         if !self.needs_optimization {
             return;
         }
 
+        if let Some(ref mut data) = self.data {
+            data.specificity = parent.clone();
+        }
+
         for child in &mut self.static_children {
-            child.optimize();
+            let child_specificity = parent.clone().count_static(child.state.prefix.len());
+            child.optimize_inner(child_specificity);
         }
 
         for child in &mut self.dynamic_children {
-            child.optimize();
+            let child_specificity = parent.clone().count_dynamic();
+            child.optimize_inner(child_specificity);
         }
 
         for child in &mut self.wildcard_children {
-            child.optimize();
+            let child_specificity = parent.clone().count_wildcard();
+            child.optimize_inner(child_specificity);
         }
 
         if let Some(child) = self.end_wildcard.as_mut() {
-            child.optimize();
+            let child_specificity = parent.count_wildcard();
+            child.optimize_inner(child_specificity);
         }
 
         self.static_children.sort();

src/parser.rs

@@ -11,14 +11,14 @@ use crate::errors::TemplateError;
 /// Characters that are not allowed in parameter names.
 const INVALID_PARAM_CHARS: [u8; 4] = [b'*', b'<', b'>', b'/'];
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Clone, Eq, PartialEq, Debug)]
 pub enum Part {
     Static { prefix: Vec<u8> },
     Dynamic { name: String },
     Wildcard { name: String },
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Clone, Eq, PartialEq, Debug)]
 pub struct Template {
     pub parts: Vec<Part>,
 }
@@ -194,33 +194,6 @@ impl Template {
 
         Ok((part, end + 1))
     }
-
-    /// Calculate a specificity of this template.
-    /// This is not a perfect solution, but appears 'good enough' for now.
-    pub fn specificity(&self) -> usize {
-        let mut static_length = 0;
-        let mut dynamic_count = 0;
-        let mut wildcard_count = 0;
-
-        for part in &self.parts {
-            match part {
-                Part::Static { prefix } => {
-                    static_length += prefix.len();
-                }
-                Part::Dynamic { .. } => {
-                    dynamic_count += 1;
-                }
-                Part::Wildcard { .. } => {
-                    wildcard_count += 1;
-                }
-            }
-        }
-
-        let mut specificity = static_length.saturating_mul(1000);
-        specificity = specificity.saturating_sub(dynamic_count * 10);
-        specificity = specificity.saturating_sub(wildcard_count * 100);
-        specificity
-    }
 }
 
 #[cfg(test)]

src/router.rs

@@ -8,11 +8,12 @@ use crate::{
     errors::{DeleteError, InsertError},
     node::{Node, NodeData},
     parser::Template,
+    specificity::Specificity,
     state::RootState,
 };
 
 /// Stores data from a successful router match.
-#[derive(Debug, Eq, PartialEq)]
+#[derive(Eq, PartialEq, Debug)]
 pub struct Match<'r, 'p, T> {
     /// A reference to the matching template data.
     pub data: &'r T,
@@ -81,24 +82,20 @@ impl<T> Router<T> {
     pub fn insert(&mut self, template: &str, data: T) -> Result<(), InsertError> {
         let mut parsed = Template::new(template.as_bytes())?;
 
-        // Check for any conflicts.
         if let Some(found) = self.root.conflict(&mut parsed.clone()) {
             return Err(InsertError::Conflict {
                 template: template.to_owned(),
                 conflict: found.template.to_string(),
             });
         }
 
-        // All good, proceed with insert.
         let key = self.storage.insert(data);
-
-        let specificity = parsed.specificity();
         self.root.insert(
             &mut parsed,
             NodeData {
                 key,
                 template: template.to_owned(),
-                specificity,
+                specificity: Specificity::default(),
             },
         );
 

src/specificity.rs

@@ -0,0 +1,46 @@
+use core::cmp::Ordering;
+
+/// Measures how specific a template is in terms of matching priority.
+///
+/// The priority is as follows:
+/// 1. Static prefix length: more static segments, more specific
+/// 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 static_length: usize,
+    pub dynamics_count: usize,
+    pub wildcards_count: usize,
+}
+
+impl Specificity {
+    pub const fn count_static(mut self, length: usize) -> Self {
+        self.static_length += length;
+        self
+    }
+
+    pub const fn count_dynamic(mut self) -> Self {
+        self.dynamics_count += 1;
+        self
+    }
+
+    pub const fn count_wildcard(mut self) -> Self {
+        self.wildcards_count += 1;
+        self
+    }
+}
+
+impl PartialOrd for Specificity {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for Specificity {
+    fn cmp(&self, other: &Self) -> Ordering {
+        self.static_length
+            .cmp(&other.static_length)
+            .then(other.dynamics_count.cmp(&self.dynamics_count))
+            .then(other.wildcards_count.cmp(&self.wildcards_count))
+    }
+}