qubit-fs 0.2.1

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Stable configured filesystem identity.

use std::fmt::Display;
use std::fmt::Formatter;
use std::fmt::Result as FmtResult;

use crate::error::FsError;
use crate::error::FsErrorKind;
use crate::error::FsOperation;
use crate::error::FsResult;

/// Stable identity of one configured filesystem object.
///
/// # Examples
///
/// ```rust
/// use qubit_fs::metadata::FileSystemId;
///
/// let id = FileSystemId::new("local-instance")?;
/// assert_eq!("local-instance", id.as_str());
/// # Ok::<(), qubit_fs::FsError>(())
/// ```
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct FileSystemId(
    /// Validated provider-supplied identity text.
    Box<str>,
);

impl FileSystemId {
    /// Validates a filesystem identity supplied by a provider.
    ///
    /// # Errors
    ///
    /// Returns [`FsErrorKind::InvalidOptions`] for empty identities or control
    /// characters.
    pub fn new(id: &str) -> FsResult<Self> {
        if id.is_empty() || id.chars().any(char::is_control) {
            return Err(FsError::new(
                FsErrorKind::InvalidOptions,
                FsOperation::Provider,
                "filesystem id must be non-empty and contain no controls",
            ));
        }
        Ok(Self(id.into()))
    }

    /// Returns the provider-supplied stable identity.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl Display for FileSystemId {
    #[inline]
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        formatter.write_str(self.as_str())
    }
}