dirbuf 0.1.2

reusable directory buffers
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

# Reusable directory buffers

This library implements a simple [`DirBuf`] type in order to
easily perform a simple optimization: re-using a heap buffer
when opening multiple files in a single dir.

Consider this example:
```ignore
// allocation 1
let data_dir = get_my_app_data_dir();
// allocation 2
let config_a = data_dir.join("a.conf");
// allocation 3
let config_b = data_dir.join("b.conf");
// allocation 3
let config_c = data_dir.join("c.conf");
let config_d = data_dir.join("d.conf");
```

Using `DirBuf` allows you to implement this pattern while only using a single allocation.

The API is designed so it can be a drop-in replacement for `Path`/`PathBuf` in common cases.

It also works when using a subdir within the main directory:
```rust
use dirbuf::DirBuf;

let mut conf_dir = DirBuf::new("/some/config/dir");

let main_config = conf_dir.join("config.toml");
// handle main config here
let mut themes = conf_dir.join("themes");
let light_theme = themes.join("light.toml");
// load light theme here
let dark_theme = themes.join("dark.toml");
// load dark theme here
```

## Limitations

### Trivial Paths
All `join*` methods require "trivial paths", meaning the path does not contain any kind of components other than [`CurDir`](https://doc.rust-lang.org/stable/std/path/enum.Component.html#variant.CurDir) and/or [`Normal`](https://doc.rust-lang.org/stable/std/path/enum.Component.html#variant.Normal).

This means no `..`, no absolute paths, and, on windows, no path prefixes, such as drive letters, verbatim paths, or UNC prefixes.

If you need to append a non-trivial path to a `DirBuf`, you can do so by first converting it to a `Path`:

```rust
use dirbuf::DirBuf;

let mut dir = DirBuf::new("some/dir");
let a = dir.join("a");
let b = dir.as_path().join("../b");
let c = dir.join("c");
```

## Feature flags

### `nightly-safe-impl`
This library relies on the ability to truncate a Path/OsString, which currently requires `unsafe` code.  However, the unstable library feature `os_string_truncate` allows this to be done safely.

Enabling this feature will cause `dirbuf` to use `OsString::truncate` instead of unsafe code to truncate the path.