path-rs 0.1.0

Cross-platform path expansion, normalization, traversal, searching, and caching
Documentation 
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

//! UTF-8 helpers for paths.
//!
//! Internal filesystem representation remains `Path` / `PathBuf` / `OsStr`.
//! Never round-trip a path through lossy UTF-8 for filesystem operations.

use crate::error::PathError;
use std::borrow::Cow;
use std::path::Path;

/// Convert a path to a UTF-8 string slice, or error if it is not valid UTF-8.
///
/// # Filesystem access
///
/// **No.**
pub fn path_to_utf8(path: &Path) -> Result<&str, PathError> {
    path.to_str().ok_or(PathError::NotUtf8)
}

/// Lossy UTF-8 conversion suitable for logs and UI only.
///
/// **Never** use the result as a filesystem path for further I/O.
///
/// # Filesystem access
///
/// **No.**
pub fn path_to_string_lossy(path: &Path) -> Cow<'_, str> {
    path.to_string_lossy()
}

/// Produce a Unicode-normalized logical key for comparison purposes.
///
/// Requires the `unicode` feature. The result must **not** be used as a filesystem path.
///
/// Normalization form: NFC.
#[cfg(feature = "unicode")]
pub fn logical_path_key(path: &Path) -> String {
    use unicode_normalization::UnicodeNormalization;
    path.to_string_lossy().nfc().collect::<String>()
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::Path;

    #[test]
    fn utf8_ok() {
        assert_eq!(path_to_utf8(Path::new("foo/bar")).unwrap(), "foo/bar");
    }
}