Natord

https://docs.rs/crate/natord/1.0.9
Admin
Natord is a Rust library that provides natural ordering for string comparison, enabling...
Tokens:2,946
Snippets:31
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Test Comprehensive String Ordering

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

A comprehensive test suite for natural string ordering, covering various cases including numbers, letters, spaces, and mixed formats.

```rust
@test
    fn test_longer() {
        check_total_order(&[
            "1-02",
            "1-2",
            "1-20",
            "10-20",
            "fred",
            "jane",
            "pic1",
            "pic2",
            "pic2a",
            "pic3",
            "pic4",
            "pic4   alpha",
            "pic 4 else",
            "pic4  last",
            "pic5",
            "pic5.07",
            "pic5.08",
            "pic5.13",
            "pic5.113",
            "pic 5 something",
            "pic 6",
            "pic   7",
            "pic100",
            "pic100a",
            "pic120",
            "pic121",
            "pic2000",
            "tom",
            "x2-g8",
            "x2-y7",
            "x2-y8",
            "x8-y8",
        ]);
    }
```

--------------------------------

### Sort files naturally using natord::compare

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Sorts a vector of filenames using natural ordering. Requires importing the natord crate.

```rust
let mut files = vec!["rfc2086.txt", "rfc822.txt", "rfc1.txt"];
files.sort_by(|&a, &b| natord::compare(a, b));
assert_eq!(files, ["rfc1.txt", "rfc822.txt", "rfc2086.txt"]);
```

--------------------------------

### Test Leading Zeroes String Ordering

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Tests the natural ordering of strings with leading zeroes in their numeric parts, ensuring '1.002' comes before '1.010'.

```rust
@test
    fn test_leading_zeroes() {
        check_total_order(&["1.001", "1.002", "1.010", "1.02", "1.1", "1.3"]);
    }
```

--------------------------------

### Test Multiple Parts String Ordering

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Tests the natural ordering of strings with multiple alphanumeric parts, such as 'x2-g8' and 'x2-y7'.

```rust
@test
    fn test_multiple_parts() {
        check_total_order(&["x2-g8", "x2-y7", "x2-y8", "x8-y8"]);
    }
```

--------------------------------

### compare(left: &str, right: &str)

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Compares two strings case-sensitively using natural ordering. It skips Unicode whitespaces and handles sequences of decimal digits.

```APIDOC
## compare(left: &str, right: &str)

### Description
Compares two strings case-sensitively. It skips any Unicode whitespaces and handles a series of decimal digits to provide natural ordering.

### Parameters
#### Request Body
- **left** (&str) - Required - The first string to compare.
- **right** (&str) - Required - The second string to compare.

### Response
#### Success Response (200)
- **Ordering** (enum) - Returns Less, Equal, or Greater based on the natural order comparison.
```

--------------------------------

### Test Numeric String Ordering

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Tests the natural ordering of strings containing numeric parts, ensuring correct comparison of sequences like 'a1', 'a2', 'a10'.

```rust
fn check_total_order(strs: &[&str]) {
    fn ordering_to_op(ord: Ordering) -> &'static str {
        match ord {
            Greater => ">",
            Equal => "=",
            Less => "<",
        }
    }

    for (i, &x) in strs.iter().enumerate() {
        for (j, &y) in strs.iter().enumerate() {
            assert!(compare(x, y) == i.cmp(&j),
                    "expected x {} y, returned x {} y (where x = `{}`, y = `{}`)",
                    ordering_to_op(i.cmp(&j)), ordering_to_op(compare(x, y)), x, y);
        }
    }
}

#[test]
fn test_numeric() {
    check_total_order(&["a", "a0", "a1", "a1a", "a1b", "a2", "a10", "a20"]);
}
```

--------------------------------

### Perform natural sort on a vector of strings

Source: https://docs.rs/crate/natord

Use natord::compare within a sort_by closure to order strings naturally rather than lexicographically.

```rust
let mut files = vec!("rfc2086.txt", "rfc822.txt", "rfc1.txt");
files.sort_by(|&a, &b| natord::compare(a, b));
assert_eq!(files, ["rfc1.txt", "rfc822.txt", "rfc2086.txt"]);
```

--------------------------------

### Generic compare_iter function for natural ordering

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Compares two iterators of characters using customizable skip, compare, and to_digit functions. This is the core natural ordering logic.

```rust
pub fn compare_iter<T, L, R, Skip, Cmp, ToDigit>(left: L, right: R, mut skip: Skip, mut cmp: Cmp,
                                                 mut to_digit: ToDigit) -> Ordering
        where L: Iterator<Item=T>,
              R: Iterator<Item=T>,
              Skip: for<'a> FnMut(&'a T) -> bool,
              Cmp: for<'a> FnMut(&'a T, &'a T) -> Ordering,
              ToDigit: for<'a> FnMut(&'a T) -> Option<isize> {
    let mut left = left.fuse();
    let mut right = right.fuse();

    let mut l;
    let mut r;
    let mut ll;
    let mut rr;

    macro_rules! read_left {
        () => (({ l = left.next(); ll = l.as_ref().and_then(|v| to_digit(v)); }))
    }

    macro_rules! read_right {
        () => (({ r = right.next(); rr = r.as_ref().and_then(|v| to_digit(v)); }))
    }

    macro_rules! return_unless_equal {
        ($ord:expr) => (match $ord { Equal => {}, lastcmp => return lastcmp })
    }

    read_left!();
    read_right!();
    'nondigits: loop {
        while l.as_ref().map_or(false, |c| skip(c)) { read_left!(); }
        while r.as_ref().map_or(false, |c| skip(c)) { read_right!(); }

        match (l, r) {
            (Some(l_), Some(r_)) => match (ll, rr) {
                (Some(ll_), Some(rr_)) => {
                    if ll_ == 0 || rr_ == 0 {
                        return_unless_equal!(ll_.cmp(&rr_));
                        'digits_left: loop {
                            read_left!();
                            read_right!();
                            match (ll, rr) {
                                (Some(ll_), Some(rr_)) => return_unless_equal!(ll_.cmp(&rr_)),
                                (Some(_), None) => return Greater,
                                (None, Some(_)) => return Less,
                                (None, None) => break 'digits_left,
                            }
                        }
                    } else {
                        let mut lastcmp = ll_.cmp(&rr_);
                        'digits_right: loop {
                            read_left!();
                            read_right!();
                            match (ll, rr) {
                                (Some(ll_), Some(rr_)) => {
                                    if lastcmp == Equal { lastcmp = ll_.cmp(&rr_); }
                                }
                                (Some(_), None) => return Greater,
                                (None, Some(_)) => return Less,
                                (None, None) => break 'digits_right,
                            }
                        }
                        return_unless_equal!(lastcmp);
                    }
                    continue 'nondigits;
                },
                (_, _) => return_unless_equal!(cmp(&l_, &r_)),
            },
            (Some(_), None) => return Greater,
            (None, Some(_)) => return Less,
            (None, None) => return Equal,
        }

        read_left!();
        read_right!();
    }
}
```

--------------------------------

### Compare Strings Ignoring Case

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Compares two strings ignoring Unicode whitespace and case. It handles decimal digits by converting them to lowercase.

```rust
pub fn compare_ignore_case(left: &str, right: &str) -> Ordering {
    // XXX what we really want is a case folding!
    // Unicode case folding can be done iteratively, but currently we don't have them in stdlib.

    let left_iter  =  left.chars().flat_map(|c| c.to_lowercase());
    let right_iter = right.chars().flat_map(|c| c.to_lowercase());

    compare_iter(left_iter, right_iter,
                 |&c| c.is_whitespace(),
                 |&l, &r| l.cmp(&r),
                 |&c| c.to_digit(10).map(|v| v as isize))
}
```

--------------------------------

### compare_iter(left, right, skip, cmp, to_digit)

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

A generic function to compare two iterators of characters, allowing for custom natural ordering logic.

```APIDOC
## compare_iter(left, right, skip, cmp, to_digit)

### Description
Compares two iterators of characters. The natural ordering can be customized via provided closure parameters.

### Parameters
#### Request Body
- **left** (Iterator) - Required - The left iterator.
- **right** (Iterator) - Required - The right iterator.
- **skip** (FnMut) - Required - Returns true if the character does not affect comparison.
- **cmp** (FnMut) - Required - Compares two characters assuming they are not digits.
- **to_digit** (FnMut) - Required - Converts a character into a digit if possible.

### Response
#### Success Response (200)
- **Ordering** (enum) - Returns the result of the comparison.
```

--------------------------------

### Compare strings case-sensitively with natord

Source: https://docs.rs/crate/natord/1.0.9/source/lib.rs

Compares two strings case-sensitively, skipping Unicode whitespaces and handling decimal digits naturally. Uses `compare_iter` internally.

```rust
pub fn compare(left: &str, right: &str) -> Ordering {
    compare_iter(left.chars(), right.chars(),
                 |&c| c.is_whitespace(),
                 |&l, &r| l.cmp(&r),
                 |&c| c.to_digit(10).map(|v| v as isize))
}
```
Tokens:
Raw