Debian Codegraph @

path/README

raw
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);