hare

commit 5ba3db310014d4e788d51f984fe29b0bbb66e588
parent ce2dbbfe3fb9e05d02cab0a6296a570227c13b95
Author: Drew DeVault <sir@cmpwn.com>
Date:   Sat,  8 Jan 2022 09:47:10 +0100

pathbuf: add README

Signed-off-by: Drew DeVault <sir@cmpwn.com>

Diffstat:
A
pathbuf/README
 | 
23
+++++++++++++++++++++++

1 file changed, 23 insertions(+), 0 deletions(-)
diff --git a/pathbuf/README b/pathbuf/README
@@ -0,0 +1,23 @@
+The pathbuf module provides for the efficient and consistent manipulation of
+filesystem paths through the [[buffer]] type.
+
+	let buf = pathbuf::init();
+	pathbuf::join(&buf, "/", "foo", "bar", "baz.txt");
+	io::println(pathbuf::string()); // "/foo/bar/baz.txt"
+	pathbuf::join(&buf, "../.././hello.txt");
+	io::println(pathbuf::string()); // "/foo/hello.txt"
+
+The buffer object includes an array of length [[path::PATH_MAX]], which can be
+somewhat large - on Linux it's 4096. You can allocate this on the stack in most
+cases, but you may prefer to allocate it elsewhere depending on your needs.
+
+	// Stack allocated
+	let buf = pathbuf::init();
+
+	// Statically allocated
+	static let buf = pathbuf::buffer { ... };
+	pathbuf::init_static(&buf);
+
+	// Heap allocated
+	let buf = alloc(pathbuf::init());
+	defer free(buf);