authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-12-12 16:30:22-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-12-23 22:15:09-08:00
log22b0eea3c0a2d2088ea6823d1de4ea5d9da6260d
treecadf1eb9e91375b662001d22eeb81dd549fe89df
parent6484101f7860988d2147b519c0c53b9fdc23b7c2

std.Io.Dir: improve realPath documentation

1 files changed, 30 insertions(+), 11 deletions(-)

lib/std/Io/Dir.zig+30-11
......@@ -789,21 +789,17 @@ pub const RealPathError = error{
789789 UnrecognizedVolume,
790790} || PathNameError || Io.Cancelable || Io.UnexpectedError;
791791
792/// This function returns the canonicalized absolute pathname of `pathname`
793/// relative to this `Dir`. If `pathname` is absolute, ignores this `Dir`
794/// handle and returns the canonicalized absolute pathname of `pathname`
795/// argument.
792/// This function returns the canonicalized absolute path name of `sub_path`
793/// relative to this `Dir`. If `sub_path` is absolute, ignores this `Dir`
794/// handle and returns the canonicalized absolute pathname of `sub_path`
795/// argument.
796796///
797/// On Windows, `sub_path` should be encoded as [WTF-8](https://wtf-8.codeberg.page/).
798/// On other platforms, `sub_path` is an opaque sequence of bytes with no particular encoding.
799/// On Windows, the result is encoded as [WTF-8](https://wtf-8.codeberg.page/).
800/// On other platforms, the result is an opaque sequence of bytes with no particular encoding.
801///
802/// This function is not universally supported by all platforms. Currently
803/// supported hosts are: Linux, macOS, and Windows.
797/// This function is not universally supported by all platforms, and using this
798/// function can lead to unnecessary failures and race conditions.
804799///
805800/// See also:
806801/// * `realPathAlloc`.
802/// * `realPathAbsolute`.
807803pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPathError!usize {
808804 return io.vtable.dirRealPath(io.userdata, dir, sub_path, out_buffer);
809805}
......@@ -811,18 +807,41 @@ pub fn realPath(dir: Dir, io: Io, sub_path: []const u8, out_buffer: []u8) RealPa
811807pub const RealPathAllocError = RealPathError || Allocator.Error;
812808
813809/// Same as `realPath` except allocates result.
810///
811/// This function is not universally supported by all platforms, and using this
812/// function can lead to unnecessary failures and race conditions.
813///
814/// See also:
815/// * `realPath`.
816/// * `realPathAbsolute`.
814817pub fn realPathAlloc(dir: Dir, io: Io, sub_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {
815818 var buffer: [max_path_bytes]u8 = undefined;
816819 const n = try realPath(dir, io, sub_path, &buffer);
817820 return allocator.dupeZ(u8, buffer[0..n]);
818821}
819822
823/// Same as `realPath` except `absolute_path` is asserted to be an absolute
824/// path.
825///
826/// This function is not universally supported by all platforms, and using this
827/// function can lead to unnecessary failures and race conditions.
828///
829/// See also:
830/// * `realPath`.
831/// * `realPathAlloc`.
820832pub fn realPathAbsolute(io: Io, absolute_path: []const u8, out_buffer: []u8) RealPathError!usize {
821833 assert(path.isAbsolute(absolute_path));
822834 return io.vtable.dirRealPath(io.userdata, .cwd(), absolute_path, out_buffer);
823835}
824836
825837/// Same as `realPathAbsolute` except allocates result.
838///
839/// This function is not universally supported by all platforms, and using this
840/// function can lead to unnecessary failures and race conditions.
841///
842/// See also:
843/// * `realPathAbsolute`.
844/// * `realPath`.
826845pub fn realPathAbsoluteAlloc(io: Io, absolute_path: []const u8, allocator: Allocator) RealPathAllocError![:0]u8 {
827846 var buffer: [max_path_bytes]u8 = undefined;
828847 const n = try realPathAbsolute(io, absolute_path, &buffer);