//! File system operations module for C API

//!

//! Provides C-compatible wrappers around Rust's std::fs API.

//! This allows C code to use Rust's file operations without importing stdio.h.

use alloc::string::String;

use alloc::vec::Vec;

use core::fmt;

use azul_css::{AzString, U8Vec, EmptyStruct, impl_result, impl_result_inner, impl_vec, impl_vec_clone, impl_vec_debug, impl_vec_mut, impl_option, impl_option_inner};

#[cfg(feature = "std")]

use std::path::Path;

#[cfg(feature = "std")]

// ============================================================================

// Error types

// ============================================================================

/// Error when performing file operations

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct FileError {

    /// Error message

    pub message: AzString,

    /// Error kind

    pub kind: FileErrorKind,

}

/// Kind of file error

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum FileErrorKind {

    /// File or directory not found

    NotFound,

    /// Permission denied

    PermissionDenied,

    /// File already exists

    AlreadyExists,

    /// Invalid path

    InvalidPath,

    /// I/O error

    IoError,

    /// Directory not empty

    DirectoryNotEmpty,

    /// Is a directory (expected file)

    IsDirectory,

    /// Is a file (expected directory)

    IsFile,

    /// Other error

    Other,

}

impl FileError {

    #[cfg(feature = "std")]

    // taken by value so it can be used directly as `.map_err(FileError::from_io_error)`

    // (map_err yields an owned io::Error); a &-param would break every such call site.

    #[allow(clippy::needless_pass_by_value)]

        use std::io::ErrorKind;

        };

}

impl fmt::Display for FileError {

}

#[cfg(feature = "std")]

impl std::error::Error for FileError {}

// FFI-safe Result types for file operations

impl_result!(

    EmptyStruct,

    FileError,

    ResultEmptyStructFileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

impl_result!(

    U8Vec,

    FileError,

    ResultU8VecFileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

impl_result!(

    AzString,

    FileError,

    ResultStringFileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

impl_result!(

    u64,

    FileError,

    Resultu64FileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

// Forward declarations for result types that need later-defined types

// (FilePath, FileMetadata, DirEntryVec are defined below)

// ============================================================================

// File metadata

// ============================================================================

/// File type (file, directory, symlink)

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

#[repr(C)]

pub enum FileType {

    /// Regular file

    File,

    /// Directory

    Directory,

    /// Symbolic link

    Symlink,

    /// Other (device, socket, etc.)

    Other,

}

/// Metadata about a file

#[derive(Copy, Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct FileMetadata {

    /// File size in bytes

    pub size: u64,

    /// File type

    pub file_type: FileType,

    /// Is read-only

    pub is_readonly: bool,

    /// Last modification time (Unix timestamp in seconds)

    pub modified_secs: u64,

    /// Creation time (Unix timestamp in seconds, 0 if unavailable)

    pub created_secs: u64,

}

/// A directory entry

#[derive(Debug, Clone)]

#[repr(C)]

pub struct DirEntry {

    /// File name (not full path)

    pub name: AzString,

    /// Full path

    pub path: AzString,

    /// File type

    pub file_type: FileType,

}

/// Vec of DirEntry

impl_option!(DirEntry, OptionDirEntry, copy = false, [Debug, Clone]);

impl_vec!(DirEntry, DirEntryVec, DirEntryVecDestructor, DirEntryVecDestructorType, DirEntryVecSlice, OptionDirEntry);

impl_vec_clone!(DirEntry, DirEntryVec, DirEntryVecDestructor);

impl_vec_debug!(DirEntry, DirEntryVec);

impl_vec_mut!(DirEntry, DirEntryVec);

// Additional FFI-safe Result types for complex types

impl_result!(

    FileMetadata,

    FileError,

    ResultFileMetadataFileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

impl_result!(

    DirEntryVec,

    FileError,

    ResultDirEntryVecFileError,

    copy = false,

    clone = false,

    [Debug, Clone]

);

// ============================================================================

// File operations

// ============================================================================

/// Read a file to bytes

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Read a file to string (UTF-8)

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Write bytes to a file (creates or overwrites)

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Write string to a file (creates or overwrites)

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Append bytes to a file

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    use std::fs::OpenOptions;

    use std::io::Write;

/// Copy a file

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Rename/move a file

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Delete a file

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Check if a file or directory exists

#[cfg(feature = "std")]

/// Check if path is a file

#[cfg(feature = "std")]

/// Check if path is a directory

#[cfg(feature = "std")]

/// Get file metadata

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    } else {

    };

// ----------------------------------------------------------------------------

// no_std stubs: keep the file API surface present without std::fs.

// ----------------------------------------------------------------------------

/// Error returned by file stubs when the `std` feature is disabled.

#[cfg(not(feature = "std"))]

fn no_std_file_error() -> FileError {

    FileError::new(FileErrorKind::Other, "file IO requires the `std` feature")

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_read(_path: &str) -> Result<U8Vec, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_read_string(_path: &str) -> Result<AzString, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_write(_path: &str, _data: &[u8]) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_write_string(_path: &str, _data: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_append(_path: &str, _data: &[u8]) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_copy(_from: &str, _to: &str) -> Result<u64, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_rename(_from: &str, _to: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_delete(_path: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_exists(_path: &str) -> bool {

    false

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_is_file(_path: &str) -> bool {

    false

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_is_dir(_path: &str) -> bool {

    false

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn file_metadata(_path: &str) -> Result<FileMetadata, FileError> {

    Err(no_std_file_error())

}

// ============================================================================

// Directory operations

// ============================================================================

/// Create a directory

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Create a directory and all parent directories

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Delete an empty directory

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// Delete a directory and all its contents

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

/// List directory contents

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

                } else {

                }

    }

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn dir_create(_path: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn dir_create_all(_path: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn dir_delete(_path: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn dir_delete_all(_path: &str) -> Result<EmptyStruct, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn dir_list(_path: &str) -> Result<DirEntryVec, FileError> {

    Err(no_std_file_error())

}

// ============================================================================

// Path operations

// ============================================================================

/// Join two paths

#[cfg(feature = "std")]

/// Get the parent directory of a path

#[cfg(feature = "std")]

/// Get the file name from a path

#[cfg(feature = "std")]

/// Get the file extension from a path

#[cfg(feature = "std")]

/// Canonicalize a path (resolve symlinks, make absolute)

#[cfg(feature = "std")]

/// # Errors

///

/// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

// ============================================================================

// Temporary files

// ============================================================================

/// Get the system temporary directory

#[cfg(feature = "std")]

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_join(_base: &str, _path: &str) -> AzString {

    AzString::from_const_str("")

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_parent(_path: &str) -> Option<AzString> {

    None

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_file_name(_path: &str) -> Option<AzString> {

    None

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_extension(_path: &str) -> Option<AzString> {

    None

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn path_canonicalize(_path: &str) -> Result<AzString, FileError> {

    Err(no_std_file_error())

}

/// Stub: `std` feature disabled.

#[cfg(not(feature = "std"))]

pub fn temp_dir() -> AzString {

    AzString::from_const_str("")

}

// ============================================================================

// OOP-style Path wrapper

// ============================================================================

/// FFI-safe path type with OOP-style methods

/// 

/// This wraps a string path and provides method-based access to file operations.

#[derive(Debug, Clone, PartialEq, Eq, Hash)]

#[repr(C)]

pub struct FilePath {

    pub inner: AzString,

}

// Result type for FilePath operations (must be after FilePath definition)

impl_result!(

    FilePath,

    FileError,

    ResultFilePathFileError,

    copy = false,

    [Debug, Clone, PartialEq, Eq]

);

// Option type for FilePath

impl_option!(FilePath, OptionFilePath, copy = false, [Clone, Debug, PartialEq, Eq]);

impl Default for FilePath {

}

impl FilePath {

    /// Creates a new path from a string

    /// Creates an empty path

    /// Creates a path from a string slice

    /// Returns the system temporary directory

    #[cfg(feature = "std")]

    /// Returns the current working directory

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

        }

    /// Returns the user's home directory (e.g., /home/username on Linux, C:\Users\username on Windows)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's cache directory (e.g., ~/.cache on Linux, ~/Library/Caches on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's config directory (e.g., ~/.config on Linux, ~/Library/Application Support on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's local config directory (e.g., ~/.config on Linux, ~/Library/Application Support on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's data directory (e.g., ~/.local/share on Linux, ~/Library/Application Support on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's local data directory (e.g., ~/.local/share on Linux, ~/Library/Application Support on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's desktop directory (e.g., ~/Desktop)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's documents directory (e.g., ~/Documents)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's downloads directory (e.g., ~/Downloads)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's executable directory (e.g., ~/.local/bin on Linux)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's font directory (e.g., ~/.local/share/fonts on Linux, ~/Library/Fonts on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's pictures directory (e.g., ~/Pictures)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's preference directory (e.g., ~/.config on Linux, ~/Library/Preferences on macOS)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's public directory (e.g., ~/Public)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's runtime directory (e.g., /run/user/1000 on Linux)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's state directory (e.g., ~/.local/state on Linux)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's audio directory (e.g., ~/Music)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's video directory (e.g., ~/Videos)

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Returns the user's templates directory

    #[cfg(all(feature = "std", feature = "extra"))]

    /// Joins this path with another path component

    #[cfg(feature = "std")]

    /// Joins this path with a string component

    #[cfg(feature = "std")]

    /// Returns the parent directory of this path

    #[cfg(feature = "std")]

    /// Returns the file name component of this path

    #[cfg(feature = "std")]

    /// Returns the file extension of this path

    #[cfg(feature = "std")]

    /// Checks if the path exists on the filesystem

    #[cfg(feature = "std")]

    /// Checks if the path is a file

    #[cfg(feature = "std")]

    /// Checks if the path is a directory

    #[cfg(feature = "std")]

    /// Checks if the path is absolute

    #[cfg(feature = "std")]

    /// Creates this directory and all parent directories

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Creates this directory (parent must exist)

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Removes this file

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Removes this directory (must be empty)

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Removes this directory and all contents

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Reads the entire file at this path as bytes

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Reads the entire file at this path as a string

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Writes bytes to the file at this path

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Writes a string to the file at this path

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Copies a file from this path to another path

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Renames/moves a file from this path to another path

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Returns the path as a string reference

    /// Returns the path as an `AzString`

    /// Lists directory contents

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Returns metadata about the file/directory

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

    /// Makes the path canonical (absolute, with no `.` or `..` components)

    #[cfg(feature = "std")]

    /// # Errors

    ///

    /// Returns a `FileError` if the filesystem operation fails (e.g. path not found, permission denied, or an I/O error).

}

impl From<String> for FilePath {

}

impl From<&str> for FilePath {

}

impl From<AzString> for FilePath {

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    #[cfg(feature = "std")]

    #[test]

    #[cfg(feature = "std")]

}

#[cfg(test)]

#[allow(

    clippy::too_many_lines,

    clippy::cast_possible_truncation,

    clippy::redundant_clone,

    clippy::similar_names,

    clippy::case_sensitive_file_extension_comparisons

)]

mod autotest_generated {

    use alloc::string::ToString;

    use super::*;

    // ------------------------------------------------------------------

    // Harness: every test gets its own directory under the system temp dir,

    // removed on drop. Tests run in parallel in one process, so names must

    // not collide.

    // ------------------------------------------------------------------

    #[cfg(feature = "std")]

    #[derive(Debug)]

    struct CaseDir(String);

    #[cfg(feature = "std")]

    impl CaseDir {

        fn new(tag: &str) -> Self {

            use core::sync::atomic::{AtomicUsize, Ordering};

            static COUNTER: AtomicUsize = AtomicUsize::new(0);

            let n = COUNTER.fetch_add(1, Ordering::Relaxed);

            let name = format!("azul_autotest_file_{}_{}_{}", std::process::id(), tag, n);

            let dir = path_join(temp_dir().as_str(), &name).as_str().to_string();

            let _ = dir_delete_all(&dir);

            assert!(dir_create_all(&dir).is_ok(), "could not create case dir {dir}");

            Self(dir)

        }

        fn path(&self) -> &str {

            &self.0

        }

        fn child(&self, name: &str) -> String {

            path_join(&self.0, name).as_str().to_string()

        }

    }

    #[cfg(feature = "std")]

    impl Drop for CaseDir {

        fn drop(&mut self) {

            let _ = dir_delete_all(&self.0);

        }

    }

    /// Paths that must never panic and never resolve to anything on disk.

    ///

    /// Deliberately excludes `"../".repeat(n)` and `"/".repeat(n)`: on unix both

    /// resolve to the root directory, so they *do* exist. See

    /// `traversal_above_root_and_repeated_slashes_resolve_to_root`.

    #[cfg(feature = "std")]

    fn hostile_paths() -> Vec<String> {

        vec![

            String::new(),

            "   ".to_string(),

            "\t\n".to_string(),

            "\0".to_string(),

            "a\0b".to_string(),

            "valid;garbage".to_string(),

            "0".to_string(),

            "-0".to_string(),

            i64::MAX.to_string(),

            i64::MIN.to_string(),

            "NaN".to_string(),

            "inf".to_string(),

            "\u{1F600}".to_string(),

            "e\u{301}\u{327}".to_string(),

            "x".repeat(100_000),

            "[".repeat(10_000),

        ]

    }

    #[cfg(feature = "std")]

    fn as_opt_string(s: Option<AzString>) -> Option<String> {

        s.map(|x| x.as_str().to_string())

    }

    // ==================================================================

    // path_to_azstring (private)

    // ==================================================================

    #[test]

    #[cfg(feature = "std")]

    fn path_to_azstring_preserves_utf8_and_empty() {

        assert_eq!(path_to_azstring(Path::new("")).as_str(), "");

        assert_eq!(

            path_to_azstring(Path::new("/tmp/a b/\u{1F600}.txt")).as_str(),

            "/tmp/a b/\u{1F600}.txt"

        );

    }

    #[test]

    #[cfg(all(feature = "std", unix))]

    fn path_to_azstring_is_lossy_never_panics_on_invalid_utf8() {

        use std::{ffi::OsStr, os::unix::ffi::OsStrExt};

        let os = OsStr::from_bytes(&[b'/', b't', 0xFF, 0xFE, b'p']);

        let s = path_to_azstring(Path::new(os));

        assert!(s.as_str().contains('\u{FFFD}'));

        assert!(s.as_str().starts_with("/t"));

        assert!(s.as_str().ends_with('p'));

    }

    // ==================================================================

    // FileError: constructor / io mapping / Display

    // ==================================================================

    #[test]

    fn file_error_new_keeps_fields_verbatim() {

        let e = FileError::new(FileErrorKind::NotFound, "boom");

        assert_eq!(e.kind, FileErrorKind::NotFound);

        assert_eq!(e.message.as_str(), "boom");

        let empty = FileError::new(FileErrorKind::Other, "");

        assert_eq!(empty.message.as_str(), "");

        assert_eq!(empty.to_string(), "");

    }

    #[test]

    fn file_error_new_survives_huge_and_unicode_messages() {

        let huge = "x".repeat(1_000_000);

        let e = FileError::new(FileErrorKind::IoError, huge.clone());

        assert_eq!(e.message.as_str().len(), 1_000_000);

        assert_eq!(e.message.as_str(), huge);

        let uni = FileError::new(FileErrorKind::InvalidPath, "\u{1F600} e\u{301} \u{202E}");

        assert_eq!(uni.message.as_str(), "\u{1F600} e\u{301} \u{202E}");

        assert_eq!(uni.to_string(), "\u{1F600} e\u{301} \u{202E}");

    }

    #[test]

    fn file_error_display_does_not_interpret_format_specifiers() {

        // The message is user/OS-supplied; it must be printed, not treated as a

        // format string.

        let e = FileError::new(FileErrorKind::Other, "{} {0} {{}} %s %n");

        assert_eq!(e.to_string(), "{} {0} {{}} %s %n");

        assert!(format!("{e:?}").contains("Other"));

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_error_from_io_error_maps_every_known_kind() {

        use std::io::{Error, ErrorKind};

        let cases = [

            (ErrorKind::NotFound, FileErrorKind::NotFound),

            (ErrorKind::PermissionDenied, FileErrorKind::PermissionDenied),

            (ErrorKind::AlreadyExists, FileErrorKind::AlreadyExists),

            (ErrorKind::IsADirectory, FileErrorKind::IsDirectory),

            (ErrorKind::DirectoryNotEmpty, FileErrorKind::DirectoryNotEmpty),

            // everything else collapses to IoError

            (ErrorKind::InvalidData, FileErrorKind::IoError),

            (ErrorKind::InvalidInput, FileErrorKind::IoError),

            (ErrorKind::UnexpectedEof, FileErrorKind::IoError),

            (ErrorKind::WriteZero, FileErrorKind::IoError),

            (ErrorKind::Other, FileErrorKind::IoError),

        ];

        for (io_kind, expected) in cases {

            let e = FileError::from_io_error(Error::new(io_kind, "msg"));

            assert_eq!(e.kind, expected, "unexpected mapping for {io_kind:?}");

            assert_eq!(e.message.as_str(), "msg");

        }

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_error_from_io_error_tolerates_empty_and_raw_os_errors() {

        use std::io::{Error, ErrorKind};

        let empty = FileError::from_io_error(Error::other(""));

        assert_eq!(empty.kind, FileErrorKind::IoError);

        assert_eq!(empty.message.as_str(), "");

        // ENOENT is 2 on every unix; the OS-error path must map like the

        // ErrorKind path.

        #[cfg(unix)]

        {

            let raw = FileError::from_io_error(Error::from_raw_os_error(2));

            assert_eq!(raw.kind, FileErrorKind::NotFound);

            assert!(!raw.message.as_str().is_empty());

        }

        // A nonsense errno must not panic and must not be silently classified.

        let bogus = FileError::from_io_error(Error::from_raw_os_error(i32::MAX));

        assert_eq!(bogus.kind, FileErrorKind::IoError);

    }

    // ==================================================================

    // file_read / file_write: round-trips and hostile paths

    // ==================================================================

    #[test]

    #[cfg(feature = "std")]

    fn file_write_read_roundtrip_bytes_including_invalid_utf8() {

        let case = CaseDir::new("rt_bytes");

        let p = case.child("blob.bin");

        let data: Vec<u8> = vec![0x00, 0xFF, 0xFE, 0x80, 0x7F, b'\n', 0x00];

        assert!(file_write(&p, &data).is_ok());

        let read = file_read(&p).expect("read back");

        assert_eq!(read.as_slice(), &data[..]);

        // The same bytes are not valid UTF-8: the string reader must reject

        // them instead of lossily decoding.

        let err = file_read_string(&p).expect_err("invalid utf-8 must not decode");

        assert_eq!(err.kind, FileErrorKind::IoError);

        assert!(!err.message.as_str().is_empty());

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_write_read_roundtrip_empty_file() {

        let case = CaseDir::new("rt_empty");

        let p = case.child("empty.bin");

        assert!(file_write(&p, b"").is_ok());

        assert!(file_read(&p).expect("read").is_empty());

        assert_eq!(file_read_string(&p).expect("read str").as_str(), "");

        assert_eq!(file_metadata(&p).expect("meta").size, 0);

        assert!(path_exists(&p));

        assert!(path_is_file(&p));

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_write_read_roundtrip_unicode_string() {

        let case = CaseDir::new("rt_unicode");

        let p = case.child("\u{1F600}_e\u{301}.txt");

        let content = "\u{1F600}\u{200D}\u{1F5A5}\u{FE0F} e\u{301}\u{327} \u{202E}rtl \u{0}nul";

        assert!(file_write_string(&p, content).is_ok());

        assert_eq!(file_read_string(&p).expect("read").as_str(), content);

        assert_eq!(file_read(&p).expect("read bytes").as_slice(), content.as_bytes());

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_write_read_roundtrip_one_megabyte() {

        let case = CaseDir::new("rt_big");

        let p = case.child("big.bin");

        let data: Vec<u8> = (0..1_000_000u32).map(|i| (i % 251) as u8).collect();

        assert!(file_write(&p, &data).is_ok());

        let read = file_read(&p).expect("read back");

        assert_eq!(read.len(), 1_000_000);

        assert_eq!(read.as_slice(), &data[..]);

        assert_eq!(file_metadata(&p).expect("meta").size, 1_000_000);

    }

    #[test]

    #[cfg(feature = "std")]

    fn file_read_rejects_every_hostile_path_without_panicking() {

        // Read-only probes only: these are relative paths resolved against the

        // test CWD, so a destructive op here could touch a real file.

        for p in hostile_paths() {

            let r = file_read(&p);

            assert!(r.is_err(), "file_read unexpectedly succeeded for {p:?}");

            let e = r.unwrap_err();

            assert!(

                !e.message.as_str().is_empty(),

                "empty error message for {p:?}"

            );

            assert!(file_read_string(&p).is_err());

            assert!(file_metadata(&p).is_err());

            assert!(path_canonicalize(&p).is_err());

            assert!(dir_list(&p).is_err());

        }

    }

    #[test]

    #[cfg(all(feature = "std", unix))]

    fn traversal_above_root_and_repeated_slashes_resolve_to_root() {

        // Two path shapes that look like "obviously invalid garbage" but are in

        // fact valid names for `/`: `..` at the root is the root, and runs of

        // separators collapse. Anything treating these as rejected input is

        // wrong.

        let climb = "../".repeat(64);