Function iter_join 

pub fn iter_join<'a, I, P>(paths: I) -> Result<PathBuf, Error>
where
    I: Iterator<Item = P>,
    P: TryIntoCowPath<'a>,

Joins a list of file system paths into a single absolute path.

This function takes a list of file system paths and joins them into a single path, normalizing and simplifying them as it goes. The result is returned as a PathBuf.

Implementation Note

This function uses string-based path manipulation rather than Path::components() API. While this approach is less idiomatic, it preserves critical edge-case behaviors tested by 444 lines of test cases in tests/inc/path_join_fn_test.rs:

• Preserves double slashes: ["/aa", "bb//", "cc"] → /aa/bb//cc
• Allows going past root: ["/dir", "../../a/b"] → /../a/b
• Trailing slash semantics: ["/a/b/", ".."] → /a/b (not /a)

Refactoring to Path::components() would normalize these away, breaking existing behavior. Any future refactoring must carefully preserve these non-standard semantics or require a breaking change with extensive test updates.

Examples :

use std ::path ::PathBuf;
use pth ::path;

let paths = vec![ PathBuf ::from( "a/b/c" ), PathBuf ::from( "/d/e" ), PathBuf ::from( "f/g" ) ];
let joined = path ::iter_join( paths.iter().map( | p | p.as_path() ) ).unwrap();
assert_eq!( joined, std ::path ::PathBuf ::from( "/d/e/f/g" ) );

let paths = vec![ PathBuf ::from( "" ), PathBuf ::from( "a/b" ), PathBuf ::from( "" ), PathBuf ::from( "c" ), PathBuf ::from( "" ) ];
let joined = path ::iter_join( paths.iter().map( | p | p.as_path() ) ).unwrap();
assert_eq!( joined, std ::path ::PathBuf ::from( PathBuf ::from( "/a/b/c" ) ) );

Errors

Returns an error if any path cannot be converted to a valid path representation.