1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! This is a library to sort strings (or file paths) **lexically**. This means that non-ASCII
//! characters such as `á` or `ß` are treated like their closest ASCII character: `á` is treated
//! as `a`, `ß` is treated as `ss`.
//!
//! The sort is case-insensitive. Alphanumeric characters are sorted after all other characters
//! (punctuation, whitespace, special characters, emojis, ...).
//!
//! It is possible to enable **natural sorting**, which also handles ASCII numbers. For example,
//! `50` is sorted before `100` with natural sorting turned on.
//!
//! If different strings have the same ASCII representation (e.g. `"Foo"` and `"fóò"`), we fall
//! back to the default implementation, which just compares Unicode code points.
//!
//! ## Usage
//!
//! To sort strings or paths, use the `LexicalSort` trait:
//!
//! ```rust
//! use lexical_sort::LexicalSort;
//!
//! let mut strings = vec!["ß", "é", "100", "hello", "world", "50", ".", "B!"];
//! strings.lexical_sort(/* enable natural sorting: */ true);
//!
//! assert_eq!(&strings, &[".", "50", "100", "B!", "é", "hello", "ß", "world"]);
//! ```
//!
//! To just compare two strings, use the `lexical_cmp` or `lexical_natural_cmp` function.

mod cmp;
pub mod iter;

pub use cmp::{lexical_cmp, lexical_natural_cmp};

use std::{
    borrow::Cow,
    path::{Path, PathBuf},
};

/// This trait adds functionality to slices containing strings or file paths
/// for sorting them lexically.
///
/// See the [module-level documentation](./index.html) for more information.
pub trait LexicalSort {
    /// Sorts the values lexically. If `natural` is set to `true`, numbers are sorted naturally.
    fn lexical_sort(&mut self, natural: bool);

    /// Sorts the values lexically. If `natural` is set to `true`, numbers are sorted naturally.
    /// This sort is unstable.
    fn unstable_lexical_sort(&mut self, natural: bool);
}

macro_rules! impl_for_str {
    ($t:ty) => {
        impl LexicalSort for $t {
            #[inline]
            fn lexical_sort(&mut self, natural: bool) {
                if natural {
                    self.sort_by(|lhs, rhs| lexical_natural_cmp(lhs, rhs));
                } else {
                    self.sort_by(|lhs, rhs| lexical_cmp(lhs, rhs));
                }
            }

            #[inline]
            fn unstable_lexical_sort(&mut self, natural: bool) {
                if natural {
                    self.sort_unstable_by(|lhs, rhs| lexical_natural_cmp(lhs, rhs));
                } else {
                    self.sort_unstable_by(|lhs, rhs| lexical_cmp(lhs, rhs));
                }
            }
        }
    };
}

impl_for_str!([&'_ str]);
impl_for_str!([String]);
impl_for_str!([Cow<'_, str>]);
impl_for_str!([Box<str>]);

macro_rules! impl_for_path {
    ($t:ty) => {
        impl LexicalSort for $t {
            #[inline]
            fn lexical_sort(&mut self, natural: bool) {
                if natural {
                    self.sort_by(|lhs, rhs| {
                        lexical_natural_cmp(&lhs.to_string_lossy(), &rhs.to_string_lossy())
                    });
                } else {
                    self.sort_by(|lhs, rhs| {
                        lexical_cmp(&lhs.to_string_lossy(), &rhs.to_string_lossy())
                    });
                }
            }

            #[inline]
            fn unstable_lexical_sort(&mut self, natural: bool) {
                if natural {
                    self.sort_unstable_by(|lhs, rhs| {
                        lexical_natural_cmp(&lhs.to_string_lossy(), &rhs.to_string_lossy())
                    });
                } else {
                    self.sort_unstable_by(|lhs, rhs| {
                        lexical_cmp(&lhs.to_string_lossy(), &rhs.to_string_lossy())
                    });
                }
            }
        }
    };
}

impl_for_path!([&'_ Path]);
impl_for_path!([PathBuf]);
impl_for_path!([Cow<'_, Path>]);
impl_for_path!([Box<Path>]);

#[test]
fn test_sort() {
    macro_rules! assert_lexically_sorted {
        ($array:expr, natural = $natural:expr) => {{
            let mut sorted = $array.clone();
            sorted.lexical_sort($natural);

            assert_eq!($array, sorted);
        }};
    }

    let strings = vec![
        "-", "-$", "-a", "100", "50", "a", "ä", "aa", "áa", "AB", "Ab", "ab", "AE", "ae", "æ", "af",
    ];
    let strings_nat = vec![
        "-", "-$", "-a", "50", "100", "a", "ä", "aa", "áa", "AB", "Ab", "ab", "AE", "ae", "æ", "af",
    ];

    assert_lexically_sorted!(strings, natural = false);
    assert_lexically_sorted!(strings_nat, natural = true);

    let paths: Vec<&Path> = strings.iter().map(|s| Path::new(s)).collect();
    let paths_nat: Vec<&Path> = strings_nat.iter().map(|s| Path::new(s)).collect();

    assert_lexically_sorted!(paths, natural = false);
    assert_lexically_sorted!(paths_nat, natural = true);
}