authorgravatar for igor.anic@gmail.comIgor Anić <igor.anic@gmail.com> 2024-03-02 18:08:32+01:00
committergravatar for igor.anic@gmail.comIgor Anić <igor.anic@gmail.com> 2024-03-11 12:24:06+01:00
logf5fd4691e5595e895e935ed76342cb729dc6904a
treecd4359e2429df94f7cd14194971cba6e9b556298
parent614161a7cf65f46cb3e2461ffe2e09d972508a97

std.tar: document iterator interface with example

1 files changed, 28 insertions(+), 2 deletions(-)

lib/std/tar.zig+28-2
...@@ -1,4 +1,3 @@...@@ -1,4 +1,3 @@
1<<<<<<< HEAD
2//! Tar archive is single ordinary file which can contain many files (or1//! Tar archive is single ordinary file which can contain many files (or
3//! directories, symlinks, ...). It's build by series of blocks each size of 5122//! directories, symlinks, ...). It's build by series of blocks each size of 512
4//! bytes. First block of each entry is header which defines type, name, size3//! bytes. First block of each entry is header which defines type, name, size
...@@ -16,7 +15,7 @@...@@ -16,7 +15,7 @@
16//! GNU tar reference: https://www.gnu.org/software/tar/manual/html_node/Standard.html15//! GNU tar reference: https://www.gnu.org/software/tar/manual/html_node/Standard.html
17//! pax reference: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_1316//! pax reference: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13
1817
19const std = @import("std.zig");18const std = @import("std");
20const assert = std.debug.assert;19const assert = std.debug.assert;
2120
22pub const output = @import("tar/output.zig");21pub const output = @import("tar/output.zig");
...@@ -250,6 +249,33 @@ pub const IteratorOptions = struct {...@@ -250,6 +249,33 @@ pub const IteratorOptions = struct {
250249
251/// Iterates over files in tar archive.250/// Iterates over files in tar archive.
252/// `next` returns each file in `reader` tar archive.251/// `next` returns each file in `reader` tar archive.
252///
253/// Init iterator with tar archive reader and provided buffers:
254///
255/// var file_name_buffer: [std.fs.MAX_PATH_BYTES]u8 = undefined;
256/// var link_name_buffer: [std.fs.MAX_PATH_BYTES]u8 = undefined;
257///
258/// var iter = std.tar.iterator(archive.reader(), .{
259/// .file_name_buffer = &file_name_buffer,
260/// .link_name_buffer = &link_name_buffer,
261/// });
262///
263/// Iterate on each tar archive file:
264///
265/// while (try iter.next()) |file| {
266/// switch (file.kind) {
267/// .directory => {
268/// // try dir.makePath(file.name);
269/// },
270/// .file => {
271/// // try file.writeAll(writer);
272/// },
273/// .sym_link => {
274/// // try dir.symLink(file.link_name, file.name, .{});
275/// },
276/// }
277/// }
278///
253pub fn iterator(reader: anytype, options: IteratorOptions) Iterator(@TypeOf(reader)) {279pub fn iterator(reader: anytype, options: IteratorOptions) Iterator(@TypeOf(reader)) {
254 return .{280 return .{
255 .reader = reader,281 .reader = reader,