Clearer errors/warnings when using list_archive_files followed by uncompress_archive_file

[Davey-Hughes]

I'm new to rust so forgive me if this should have been assumed from the use of a mutable reference, but it took me a long time to realize that after using list_archive-files() you must rewind the file pointer in order to use uncompress_archive_file() (and I assume other decompression functions on the same file handle).

I assume calling list_archive_files() before another decompression function would be relatively common, so some documentation, warnings, or automatic seeking/rewinding would be appreciated.

[otavio]

How do you suggest we address this?

[Davey-Hughes]

I think a few things would be nice in order from least to most work:

1. Example in the uncompress_archive_file() doc comment for using list_archive_files() with rewind() usage.
2. Examples of all the basic function use cases for quick reference.
3. A way to traverse and uncompress an archive using an iterator, maybe like this: https://docs.rs/zip/0.6.3/zip/read/struct.ZipArchive.html

Like I said I'm quite new to rust so I don't have a good sense of what's idiomatic or how much effort 3. is, but I think the nice thing is to avoid writing an uncompressed file to disk if you don't actually need that output file (for example my use case is just calculating the sha1 and crc32 of the file inside the archive). So being able to iterate over the files in the archive and uncompress conditionally at each iteration would feel intuitive.

EDIT: I also think potentially on the unrecognized format error in these functions, perhaps a more informative error in such cases of detecting that the file pointer wasn't at 0 might be useful if it doesn't impact performance. Or if it doesn't impact performance, just automatically rewinding the file pointer after calling list_archive_files().

[otavio]

Would you be willing to work on those items? If so I can help.

[Davey-Hughes]

Potentially yes. I have a lot to learn about Rust so I'll see what I can figure out.