| 1 |
path: filesystem path normalization and manipulation |
| 2 |
|
| 3 |
Note that Hare expects paths to be valid UTF-8 strings. If you require the use |
| 4 |
of non-UTF-8 paths (ideally for only as long as it takes to delete or rename |
| 5 |
those files), see the low-level functions available from [[rt::]]. |
| 6 |
|
| 7 |
Use of the [[buffer]] type is recommended for efficient and consistent |
| 8 |
manipulation of filesystem paths. The path will always be |
| 9 |
normalized, which is to say that it will not include any of the following: |
| 10 |
|
| 11 |
- Redundant ".." components |
| 12 |
- Redundant path separators |
| 13 |
- Any "." components, except in the case of "." |
| 14 |
|
| 15 |
Assuming that [[SEP]] is '/', "/usr//bin/../bin/./hare/" becomes "/usr/bin/hare" |
| 16 |
and "../../foo/bar" is unchanged. |
| 17 |
|
| 18 |
Different [[fs::fs]] implementations may have different rules for normalizing |
| 19 |
paths. For use-cases in which this is relevant, [[fs::resolve]] should be used |
| 20 |
instead. |
| 21 |
|
| 22 |
The buffer object includes an array of length [[MAX]], which can be somewhat |
| 23 |
large; on Linux it's 4095 bytes. You can allocate this on the stack in most |
| 24 |
cases, but you may prefer to allocate it elsewhere depending on your needs. |
| 25 |
Functions in this module return [[too_long]] if the buffer's capacity would be |
| 26 |
exceeded. |
| 27 |
|
| 28 |
// Stack allocated |
| 29 |
let buf = path::init()!; |
| 30 |
|
| 31 |
// Statically allocated |
| 32 |
static let buf = path::buffer { ... }; |
| 33 |
path::set(&buf)!; |
| 34 |
|
| 35 |
// Heap allocated |
| 36 |
let buf = alloc(path::init()!); |
| 37 |
defer free(buf); |