Skip to main content

qubit_fs/directory/
create_directory_options.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Directory creation options.
9
10use crate::metadata::NonSensitiveMetadata;
11use crate::metadata::UserMetadata;
12
13/// Options controlling directory or collection creation.
14///
15/// # Examples
16///
17/// ```rust
18/// use qubit_fs::directory::CreateDirectoryOptions;
19///
20/// assert!(!CreateDirectoryOptions::default().recursive());
21/// ```
22#[non_exhaustive]
23#[derive(Clone, Debug, PartialEq)]
24pub struct CreateDirectoryOptions {
25    /// Whether missing parent directories should be created.
26    recursive: bool,
27    /// Whether an existing directory should be accepted.
28    exists_ok: bool,
29    /// User-defined metadata with validated non-sensitive structural keys.
30    user_metadata: NonSensitiveMetadata,
31}
32
33impl Default for CreateDirectoryOptions {
34    /// Creates non-recursive options that reject an existing directory.
35    ///
36    /// # Returns
37    /// Options with recursive creation and acceptance of an existing
38    /// directory disabled, and with no user metadata.
39    #[inline]
40    fn default() -> Self {
41        Self {
42            recursive: false,
43            exists_ok: false,
44            user_metadata: NonSensitiveMetadata::new(),
45        }
46    }
47}
48
49impl CreateDirectoryOptions {
50    /// Returns whether missing parent directories should be created.
51    ///
52    /// # Returns
53    /// `true` when missing parent directories should be created.
54    #[inline]
55    #[must_use]
56    pub const fn recursive(&self) -> bool {
57        self.recursive
58    }
59
60    /// Returns whether an existing directory should be accepted.
61    ///
62    /// # Returns
63    /// `true` when creating a directory that already exists is allowed.
64    #[inline]
65    #[must_use]
66    pub const fn exists_ok(&self) -> bool {
67        self.exists_ok
68    }
69
70    /// Returns validated user-defined metadata.
71    ///
72    /// # Returns
73    /// The metadata associated with these creation options.
74    #[inline]
75    #[must_use]
76    pub const fn user_metadata(&self) -> &NonSensitiveMetadata {
77        &self.user_metadata
78    }
79
80    /// Replaces recursive parent creation.
81    ///
82    /// # Parameters
83    /// `recursive` enables creation of missing parent directories when `true`.
84    ///
85    /// # Returns
86    /// These options with recursive parent creation set to `recursive`.
87    #[inline]
88    #[must_use]
89    pub const fn with_recursive(mut self, recursive: bool) -> Self {
90        self.recursive = recursive;
91        self
92    }
93
94    /// Replaces acceptance of an existing directory.
95    ///
96    /// # Parameters
97    /// `exists_ok` enables accepting an already existing directory when `true`.
98    ///
99    /// # Returns
100    /// These options with existing-directory acceptance set to `exists_ok`.
101    #[inline]
102    #[must_use]
103    pub const fn with_exists_ok(mut self, exists_ok: bool) -> Self {
104        self.exists_ok = exists_ok;
105        self
106    }
107
108    /// Replaces user-defined metadata that has already passed key validation.
109    ///
110    /// # Parameters
111    /// `metadata` is the validated metadata to associate with these options.
112    ///
113    /// # Returns
114    /// These options with `metadata` wrapped as non-sensitive metadata.
115    #[inline]
116    #[must_use]
117    pub fn with_user_metadata(mut self, metadata: UserMetadata) -> Self {
118        self.user_metadata = NonSensitiveMetadata::from(metadata);
119        self
120    }
121}