args() and args_os()

The functions std::env::args() and std::env::args_os() both iterate over the command-line arguments of the current process, differing in how they handle non-UTF-8 operating system strings. args() yields String and panics if any argument contains invalid Unicode, whereas args_os() yields OsString and never panics regardless of the underlying byte encoding.

Why env::args() Can Panic

On Unix platforms, command-line arguments are arbitrary null-terminated byte sequences (char*) that are not required by the kernel to be valid UTF-8. On Windows, command-line arguments are sequences of 16-bit wide characters (wchar_t) that may contain unpaired UTF-16 surrogates.

If a user passes a filename containing raw non-UTF-8 bytes (for example, ./my_tool $'\xff\xfe.dat') and the program iterates over env::args(), the iterator panics as soon as it reaches that argument—even if the program only wanted to open the file path.

OS argv item: [0xFF, 0xFE, b'.', b'd', b'a', b't']
                       |
        +--------------+--------------+
        |                             |
        v                             v
   env::args()                  env::args_os()
   Attempts UTF-8 decode        Wraps bytes in OsString
   PANICS at runtime!           Converts directly to PathBuf

Using args_os() for Non-Panicking CLI Parsing

By iterating over env::args_os() (typically skipping index 0 with .skip(1)), a program can match UTF-8 flags via OsStr::to_str() while accepting arbitrary file paths directly into PathBuf::from.

use std::env;
use std::ffi::OsString;
use std::path::PathBuf;

#[derive(Debug)]
struct CliOptions {
    dry_run: bool,
    files: Vec<PathBuf>,
}

fn parse_os_args<I>(args: I) -> Result<CliOptions, String>
where
    I: IntoIterator<Item = OsString>,
{
    let mut dry_run = false;
    let mut files = Vec::new();
    let mut treat_as_path = false;

    for os_arg in args {
        if treat_as_path {
            files.push(PathBuf::from(os_arg));
            continue;
        }

        // Attempt to view as UTF-8 for flag matching
        match os_arg.to_str() {
            Some("--dry-run") | Some("-n") => dry_run = true,
            Some("--") => treat_as_path = true,
            Some(flag) if flag.starts_with('-') => {
                return Err(format!("unrecognized option: {flag}"));
            }
            // Either valid UTF-8 positional path OR non-UTF-8 OS path:
            // Both convert losslessly into PathBuf!
            Some(_) | None => files.push(PathBuf::from(os_arg)),
        }
    }

    Ok(CliOptions { dry_run, files })
}

fn main() {
    // Real usage: env::args_os().skip(1)
    let sample_args = vec![
        OsString::from("--dry-run"),
        OsString::from("report.csv"),
        OsString::from("--"),
        OsString::from("-weird-file.bin"),
    ];

    let parsed = parse_os_args(sample_args).unwrap();
    println!("dry_run: {}", parsed.dry_run);
    for path in &parsed.files {
        println!("file: {}", path.display());
    }
}

dry_run: true
file: report.csv
file: -weird-file.bin

Exact-Size Iteration

Both Args and ArgsOs implement ExactSizeIterator and DoubleEndedIterator, meaning .len() returns the remaining argument count in $O(1)$ time and .next_back() consumes arguments from the end of the command line:

use std::env;

fn main() {
    let args_iter = env::args_os();
    println!("Remaining arguments in iterator: {}", args_iter.len());
}

Remaining arguments in iterator: 1