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}