Struct camino_tempfile::Utf8TempDir
source · pub struct Utf8TempDir { /* private fields */ }
Expand description
A directory in the filesystem that is automatically deleted when it goes out of scope.
The Utf8TempDir
type creates a directory on the file system that is deleted once it goes out
of scope. At construction, the Utf8TempDir
creates a new directory with a randomly generated
name.
The default constructor, Utf8TempDir::new()
, creates directories in the location returned by
std::env::temp_dir()
, but Utf8TempDir
can be configured to manage a temporary directory in
any location by constructing with a Builder
.
After creating a Utf8TempDir
, work with the file system by doing standard std::fs
file
system operations on its Utf8Path
, which can be retrieved with Utf8TempDir::path()
. Once
the Utf8TempDir
value is dropped, the directory at the path will be deleted, along with any
files and directories it contains. It is your responsibility to ensure that no further file
system operations are attempted inside the temporary directory once it has been deleted.
Resource Leaking
Various platform-specific conditions may cause Utf8TempDir
to fail to delete the underlying
directory. It’s important to ensure that handles (like File
and
ReadDir
) to files inside the directory are dropped before the TempDir
goes out of scope. The Utf8TempDir
destructor will silently ignore any errors in deleting the
directory; to instead handle errors call Utf8TempDir::close()
.
Note that if the program exits before the Utf8TempDir
destructor is run, such as via
std::process::exit()
, by segfaulting, or by receiving a signal like SIGINT
, then the
temporary directory will not be deleted.
Examples
Create a temporary directory with a generated name:
use std::fs::File;
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of `std::env::temp_dir()`
let tmp_dir = Utf8TempDir::new()?;
Create a temporary directory with a prefix in its name:
use std::fs::File;
use std::io::Write;
use camino_tempfile::Builder;
// Create a directory inside of `std::env::temp_dir()`,
// whose name will begin with 'example'.
let tmp_dir = Builder::new().prefix("example").tempdir()?;
Implementations§
source§impl Utf8TempDir
impl Utf8TempDir
sourcepub fn new() -> Result<Utf8TempDir>
pub fn new() -> Result<Utf8TempDir>
Attempts to make a temporary directory inside of env::temp_dir()
.
See Builder
for more configuration.
The directory and everything inside it will be automatically deleted once the returned
Utf8TempDir
is destroyed.
Errors
If the directory can not be created, or if env::temp_dir
is a non-UTF-8 path, Err
is
returned.
Examples
use std::fs::File;
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of `std::env::temp_dir()`
let tmp_dir = Utf8TempDir::new()?;
let file_path = tmp_dir.path().join("my-temporary-note.txt");
let mut tmp_file = File::create(file_path)?;
writeln!(tmp_file, "Brian was here. Briefly.")?;
// `tmp_dir` goes out of scope, the directory as well as
// `tmp_file` will be deleted here.
sourcepub fn new_in<P: AsRef<Utf8Path>>(dir: P) -> Result<Utf8TempDir>
pub fn new_in<P: AsRef<Utf8Path>>(dir: P) -> Result<Utf8TempDir>
Attempts to make a temporary directory inside of dir
. The directory and everything inside
it will be automatically deleted once the returned Utf8TempDir
is destroyed.
Errors
If the directory can not be created, Err
is returned.
Examples
use std::fs::{self, File};
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of the current directory
let tmp_dir = Utf8TempDir::new_in(".")?;
let file_path = tmp_dir.path().join("my-temporary-note.txt");
let mut tmp_file = File::create(file_path)?;
writeln!(tmp_file, "Brian was here. Briefly.")?;
sourcepub fn with_prefix<S: AsRef<str>>(prefix: S) -> Result<Utf8TempDir>
pub fn with_prefix<S: AsRef<str>>(prefix: S) -> Result<Utf8TempDir>
Attempts to make a temporary directory with the specified prefix inside of
env::temp_dir()
. The directory and everything inside it will be automatically
deleted once the returned Utf8TempDir
is destroyed.
Errors
If the directory can not be created, Err
is returned.
Examples
use std::fs::{self, File};
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of the current directory
let tmp_dir = Utf8TempDir::with_prefix("foo-")?;
let tmp_name = tmp_dir.path().file_name().unwrap();
assert!(tmp_name.starts_with("foo-"));
sourcepub fn with_prefix_in<S: AsRef<str>, P: AsRef<Utf8Path>>(
prefix: S,
dir: P
) -> Result<Utf8TempDir>
pub fn with_prefix_in<S: AsRef<str>, P: AsRef<Utf8Path>>( prefix: S, dir: P ) -> Result<Utf8TempDir>
Attempts to make a temporary directory with the specified prefix inside
the specified directory. The directory and everything inside it will be
automatically deleted once the returned Utf8TempDir
is destroyed.
Errors
If the directory can not be created, Err
is returned.
Examples
use std::fs::{self, File};
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of the current directory
let tmp_dir = Utf8TempDir::with_prefix_in("foo-", ".")?;
let tmp_name = tmp_dir.path().file_name().unwrap();
assert!(tmp_name.starts_with("foo-"));
sourcepub fn path(&self) -> &Utf8Path
pub fn path(&self) -> &Utf8Path
Accesses the Utf8Path
to the temporary directory.
Examples
use camino_tempfile::Utf8TempDir;
let tmp_path;
{
let tmp_dir = Utf8TempDir::new()?;
tmp_path = tmp_dir.path().to_owned();
// Check that the temp directory actually exists.
assert!(tmp_path.exists());
// End of `tmp_dir` scope, directory will be deleted
}
// Temp directory should be deleted by now
assert_eq!(tmp_path.exists(), false);
sourcepub fn into_path(self) -> Utf8PathBuf
pub fn into_path(self) -> Utf8PathBuf
Persist the temporary directory to disk, returning the Utf8PathBuf
where it is located.
This consumes the Utf8TempDir
without deleting directory on the filesystem, meaning that
the directory will no longer be automatically deleted.
Examples
use std::fs;
use camino_tempfile::Utf8TempDir;
let tmp_dir = Utf8TempDir::new()?;
// Persist the temporary directory to disk,
// getting the path where it is.
let tmp_path = tmp_dir.into_path();
// Delete the temporary directory ourselves.
fs::remove_dir_all(tmp_path)?;
sourcepub fn close(self) -> Result<()>
pub fn close(self) -> Result<()>
Closes and removes the temporary directory, returning a Result
.
Although Utf8TempDir
removes the directory on drop, in the destructor any errors are
ignored. To detect errors cleaning up the temporary directory, call close
instead.
Errors
This function may return a variety of std::io::Error
s that result from deleting the
files and directories contained with the temporary directory, as well as from deleting the
temporary directory itself. These errors may be platform specific.
Examples
use std::fs::File;
use std::io::Write;
use camino_tempfile::Utf8TempDir;
// Create a directory inside of `std::env::temp_dir()`.
let tmp_dir = Utf8TempDir::new()?;
let file_path = tmp_dir.path().join("my-temporary-note.txt");
let mut tmp_file = File::create(file_path)?;
writeln!(tmp_file, "Brian was here. Briefly.")?;
// By closing the `Utf8TempDir` explicitly we can check that it has
// been deleted successfully. If we don't close it explicitly,
// the directory will still be deleted when `tmp_dir` goes out
// of scope, but we won't know whether deleting the directory
// succeeded.
drop(tmp_file);
tmp_dir.close()?;