Trait Container 

pub trait Container {
    // Required methods
    fn disk_file_path(&self) -> &str;
    fn disk_file_offset(&self) -> u64;
    fn files(&self) -> &HashMap<String, RFile>;
    fn files_mut(&mut self) -> &mut HashMap<String, RFile>;
    fn paths_cache(&self) -> &HashMap<String, Vec<String>>;
    fn paths_cache_mut(&mut self) -> &mut HashMap<String, Vec<String>>;
    fn local_timestamp(&self) -> u64;

    // Provided methods
    fn extract(
        &mut self,
        container_path: ContainerPath,
        destination_path: &Path,
        keep_container_path_structure: bool,
        schema: &Option<Schema>,
        case_insensitive: bool,
        keys_first: bool,
        extra_data: &Option<EncodeableExtraData<'_>>,
        keep_data_in_memory: bool,
    ) -> Result<Vec<PathBuf>> { ... }
    fn extract_metadata(
        &mut self,
        _destination_path: &Path,
    ) -> Result<Vec<PathBuf>> { ... }
    fn insert(&mut self, file: RFile) -> Result<Option<ContainerPath>> { ... }
    fn insert_file(
        &mut self,
        source_path: &Path,
        container_path_folder: &str,
        schema: &Option<Schema>,
    ) -> Result<Option<ContainerPath>> { ... }
    fn insert_folder(
        &mut self,
        source_path: &Path,
        container_path_folder: &str,
        ignored_paths: &Option<Vec<&str>>,
        schema: &Option<Schema>,
        include_base_folder: bool,
    ) -> Result<Vec<ContainerPath>> { ... }
    fn remove(&mut self, path: &ContainerPath) -> Vec<ContainerPath> { ... }
    fn disk_file_name(&self) -> String { ... }
    fn has_file(&self, path: &str) -> bool { ... }
    fn has_folder(&self, path: &str) -> bool { ... }
    fn file(&self, path: &str, case_insensitive: bool) -> Option<&RFile> { ... }
    fn file_mut(
        &mut self,
        path: &str,
        case_insensitive: bool,
    ) -> Option<&mut RFile> { ... }
    fn files_by_type(&self, file_types: &[FileType]) -> Vec<&RFile> { ... }
    fn files_by_type_mut(&mut self, file_types: &[FileType]) -> Vec<&mut RFile> { ... }
    fn files_by_path(
        &self,
        path: &ContainerPath,
        case_insensitive: bool,
    ) -> Vec<&RFile> { ... }
    fn files_by_path_mut(
        &mut self,
        path: &ContainerPath,
        case_insensitive: bool,
    ) -> Vec<&mut RFile> { ... }
    fn files_by_paths(
        &self,
        paths: &[ContainerPath],
        case_insensitive: bool,
    ) -> Vec<&RFile> { ... }
    fn files_by_paths_mut(
        &mut self,
        paths: &[ContainerPath],
        case_insensitive: bool,
    ) -> Vec<&mut RFile> { ... }
    fn files_by_type_and_paths(
        &self,
        file_types: &[FileType],
        paths: &[ContainerPath],
        case_insensitive: bool,
    ) -> Vec<&RFile> { ... }
    fn files_by_type_and_paths_mut(
        &mut self,
        file_types: &[FileType],
        paths: &[ContainerPath],
        case_insensitive: bool,
    ) -> Vec<&mut RFile> { ... }
    fn paths_cache_generate(&mut self) { ... }
    fn paths_cache_insert_path(&mut self, path: &str) { ... }
    fn paths_cache_remove_path(&mut self, path: &str) { ... }
    fn paths_folders_raw(&self) -> HashSet<String> { ... }
    fn paths(&self) -> Vec<ContainerPath> { ... }
    fn paths_raw(&self) -> Vec<&str> { ... }
    fn paths_raw_from_container_path(&self, path: &ContainerPath) -> Vec<String> { ... }
    fn internal_timestamp(&self) -> u64 { ... }
    fn preload(&mut self) -> Result<()> { ... }
    fn move_paths(
        &mut self,
        in_out_paths: &[(ContainerPath, ContainerPath)],
    ) -> Result<Vec<(ContainerPath, ContainerPath)>> { ... }
    fn move_path(
        &mut self,
        source_path: &ContainerPath,
        destination_path: &ContainerPath,
    ) -> Result<Vec<(ContainerPath, ContainerPath)>> { ... }
    fn clean_undecoded(&mut self) { ... }
}

Interface for working with container-like files.

This trait provides a unified API for manipulating file containers such as PackFiles, allowing implementors to store, retrieve, and manage collections of RFiles with hierarchical path structures.

Implementors

• Pack: Total War PackFile containers (.pack files)
• Other container formats that store multiple files

Core Operations

The trait provides several categories of operations:

• File access: Get references to files by path, type, or pattern
• Insertion: Add files from disk or RFile instances
• Extraction: Write files to disk, optionally as TSV for DB/Loc files
• Removal: Delete files or folders by path
• Queries: Check existence, list folders, filter by type

Path Handling

All paths use forward slashes (/) as separators, regardless of OS. Paths starting with / are automatically normalized by removing the leading slash.

Required Methods

fn disk_file_path(&self) -> &str

Returns the full path on disk where this container is stored.

Returns

The absolute file path, or an empty string if the container is not backed by a disk file.

fn disk_file_offset(&self) -> u64

Returns the byte offset of this container’s data within its disk file.

This is used for nested containers (e.g., a container embedded within another file).

Returns

The offset in bytes, or 0 if the container starts at the beginning of the file.

fn files(&self) -> &HashMap<String, RFile>

Returns a reference to the internal file map.

The map uses file paths as keys and RFiles as values.

fn files_mut(&mut self) -> &mut HashMap<String, RFile>

Returns a mutable reference to the internal file map.

The map uses file paths as keys and RFiles as values.

fn paths_cache(&self) -> &HashMap<String, Vec<String>>

Returns the paths cache mapping lowercase paths to their original-cased variants.

This cache enables efficient case-insensitive file lookups. The map structure is: lowercase_path -> vec![OriginalCased1, OriginalCased2, ...]

Important

If you manipulate the file list directly (via files_mut()), you must update this cache using paths_cache_insert_path(), paths_cache_remove_path(), or paths_cache_generate().

fn paths_cache_mut(&mut self) -> &mut HashMap<String, Vec<String>>

Returns a mutable reference to the paths cache.

See paths_cache() for details on cache structure and maintenance.

fn local_timestamp(&self) -> u64

This method returns the Last modified date the filesystem reports for the container file, in seconds.

Implementors should return 0 if the Container doesn’t have a file on disk yet.

Provided Methods

fn extract( &mut self, container_path: ContainerPath, destination_path: &Path, keep_container_path_structure: bool, schema: &Option<Schema>, case_insensitive: bool, keys_first: bool, extra_data: &Option<EncodeableExtraData<'_>>, keep_data_in_memory: bool, ) -> Result<Vec<PathBuf>>

Extracts files from the container to disk.

This method writes files matching the provided ContainerPath to the filesystem, optionally preserving the container’s folder structure.

Parameters

• container_path: Path to file or folder within the container to extract
• destination_path: Target directory on disk where files will be written
• keep_container_path_structure: If true, preserves the container’s folder hierarchy
• schema: If provided, attempts to export DB/Loc files as TSV (falls back to binary on error)
• case_insensitive: Enable case-insensitive folder matching (file extraction is always case-sensitive)
• keys_first: When exporting to TSV, place key columns first
• extra_data: Optional encoding context for binary files
• keep_data_in_memory: If true, loads disk-backed files to memory before extraction

Returns

Returns a list of paths to the extracted files on disk.

Errors

Returns an error if:

• The specified container path doesn’t exist
• Disk I/O operations fail
• File decoding fails (for TSV export)

Examples

// Extract a single file, preserving structure
let paths = container.extract(
    ContainerPath::File("db/units_tables/units.bin".to_string()),
    Path::new("./output"),
    true,  // Keep structure
    &Some(schema),
    false, // Case-sensitive
    true,  // Keys first
    &None,
    false
)?;

// Extract entire folder as TSV
let paths = container.extract(
    ContainerPath::Folder("db/".to_string()),
    Path::new("./output"),
    false, // Flat extraction
    &Some(schema),
    true,  // Case-insensitive
    true,
    &None,
    false
)?;

fn extract_metadata(&mut self, _destination_path: &Path) -> Result<Vec<PathBuf>>

Extracts container metadata as .json files.

This method writes any metadata associated with the container (such as pack settings, notes, or configuration) to the specified destination directory.

Parameters

• destination_path: Directory where metadata files will be written

Returns

Returns a list of paths to the extracted metadata files.

Default Implementation

The default implementation does nothing and returns an empty list. Container types with metadata should override this method.

fn insert(&mut self, file: RFile) -> Result<Option<ContainerPath>>

Inserts an RFile into the container.

If a file with the same path already exists, it will be replaced.

Parameters

• file: The RFile to insert

Returns

Returns the ContainerPath of the inserted file, or None if insertion failed.

fn insert_file( &mut self, source_path: &Path, container_path_folder: &str, schema: &Option<Schema>, ) -> Result<Option<ContainerPath>>

Inserts a file from disk into the container.

This method reads a file from the filesystem and inserts it at the specified path within the container. If a file already exists at that path, it will be replaced.

TSV Import

If a Schema is provided and the source file has a .tsv extension, this method will attempt to import it as a binary DB/Loc file. If the conversion fails, it falls back to importing it as a plain text file.

Parameters

• source_path: Path to the file on disk to import
• container_path_folder: Target path within the container (folder or full path)
• schema: Optional schema for TSV-to-binary conversion

Returns

Returns the ContainerPath of the inserted file, or None if insertion failed.

Errors

Returns an error if:

• The source file cannot be read
• File type detection fails

Path Behavior

• If container_path_folder ends with / or is empty, the source filename is appended
• Otherwise, container_path_folder is used as the full target path

fn insert_folder( &mut self, source_path: &Path, container_path_folder: &str, ignored_paths: &Option<Vec<&str>>, schema: &Option<Schema>, include_base_folder: bool, ) -> Result<Vec<ContainerPath>>

Inserts an entire folder from disk into the container recursively.

This method recursively scans a directory and imports all files, preserving the folder structure. Files with identical paths in the container are replaced.

TSV Import

If a Schema is provided, .tsv files will be converted to binary DB/Loc format. If conversion fails, they’re imported as plain text files.

Parameters

• source_path: Path to the folder on disk to import
• container_path_folder: Target folder path within the container
• ignored_paths: Optional list of relative paths to exclude from import
• schema: Optional schema for TSV-to-binary conversion
• include_base_folder: If true, includes the source folder name in container paths

Returns

Returns a list of all ContainerPaths that were inserted.

Errors

Returns an error if:

• The source directory cannot be read
• Any file read or type detection fails

Folder Inclusion Behavior

• include_base_folder = false: Contents of source_path go directly into container_path_folder
• include_base_folder = true: A subfolder with the source folder’s name is created first

Examples

// Import folder contents directly into "data/"
container.insert_folder(
    Path::new("./my_mod"),
    "data/",
    &None,
    &Some(schema),
    false  // Don't include "my_mod" folder name
)?;

// Import with ignored paths
container.insert_folder(
    Path::new("./my_mod"),
    "data/",
    &Some(vec![".git/", "node_modules/"]),
    &None,
    true  // Include "my_mod" folder name
)?;

fn remove(&mut self, path: &ContainerPath) -> Vec<ContainerPath>

Removes files matching the provided ContainerPath from the container.

This method deletes files or entire folder hierarchies from the container.

Parameters

• path: The container path to remove (file or folder)

Returns

Returns a list of removed ContainerPaths, always using the File variant.

Special Cases

• ContainerPath::Folder(""): Represents the container root, deletes all files
• ContainerPath::File(...): Deletes a single file
• ContainerPath::Folder(...): Deletes all files under that folder (recursive)

Examples

// Remove a single file
container.remove(&ContainerPath::File("data/units.bin".to_string()));

// Remove entire folder
container.remove(&ContainerPath::Folder("db/".to_string()));

// Clear entire container
container.remove(&ContainerPath::Folder("".to_string()));

fn disk_file_name(&self) -> String

Returns the filename of the container on disk.

Extracts just the filename portion from disk_file_path().

Returns

The filename as a string, or an empty string if no disk path is set.

fn has_file(&self, path: &str) -> bool

Checks if a file with the specified path exists in the container.

Parameters

• path: The file path to check (case-sensitive)

Returns

true if the file exists, false otherwise.

fn has_folder(&self, path: &str) -> bool

Checks if a non-empty folder exists at the specified path.

A folder is considered to exist if there is at least one file whose path starts with the provided folder path.

Parameters

• path: The folder path to check

Returns

true if the folder exists and contains files, false otherwise.

Note

Empty string always returns false. Paths are normalized to end with / for matching.

fn file(&self, path: &str, case_insensitive: bool) -> Option<&RFile>

Returns a reference to an RFile in the container by path.

Parameters

• path: The file path to look up
• case_insensitive: If true, performs case-insensitive matching

Returns

Some(&RFile) if the file exists, None otherwise.

fn file_mut(&mut self, path: &str, case_insensitive: bool) -> Option<&mut RFile>

Returns a mutable reference to an RFile in the container by path.

Parameters

• path: The file path to look up
• case_insensitive: If true, performs case-insensitive matching

Returns

Some(&mut RFile) if the file exists, None otherwise.

fn files_by_type(&self, file_types: &[FileType]) -> Vec<&RFile>

Returns references to all files of the specified types.

Parameters

• file_types: Slice of FileTypes to filter by

Returns

A vector of references to matching files.

fn files_by_type_mut(&mut self, file_types: &[FileType]) -> Vec<&mut RFile>

Returns mutable references to all files of the specified types.

Parameters

• file_types: Slice of FileTypes to filter by

Returns

A vector of mutable references to matching files.

fn files_by_path( &self, path: &ContainerPath, case_insensitive: bool, ) -> Vec<&RFile>

Returns references to files matching the provided ContainerPath.

Parameters

• path: The container path to match (file or folder)
• case_insensitive: Enable case-insensitive matching

Returns

A vector of references to matching files.

Special Cases

ContainerPath::Folder("") represents the container root and returns all files.

fn files_by_path_mut( &mut self, path: &ContainerPath, case_insensitive: bool, ) -> Vec<&mut RFile>

Returns mutable references to files matching the provided ContainerPath.

Parameters

• path: The container path to match (file or folder)
• case_insensitive: Enable case-insensitive matching

Returns

A vector of mutable references to matching files.

Special Cases

ContainerPath::Folder("") represents the container root and returns all files.

fn files_by_paths( &self, paths: &[ContainerPath], case_insensitive: bool, ) -> Vec<&RFile>

Returns references to files matching any of the provided ContainerPaths.

Parameters

• paths: Slice of container paths to match
• case_insensitive: Enable case-insensitive matching

Returns

A vector of references to all matching files (may contain duplicates if paths overlap).

fn files_by_paths_mut( &mut self, paths: &[ContainerPath], case_insensitive: bool, ) -> Vec<&mut RFile>

Returns mutable references to files matching any of the provided ContainerPaths.

This method should be used instead of files_by_path_mut() when you need mutable references to files across multiple different paths, as it properly handles the borrowing requirements.

Parameters

• paths: Slice of container paths to match
• case_insensitive: Enable case-insensitive matching

Returns

A vector of mutable references to all matching files (no duplicates).

fn files_by_type_and_paths( &self, file_types: &[FileType], paths: &[ContainerPath], case_insensitive: bool, ) -> Vec<&RFile>

Returns references to files matching both type and path criteria.

This is a filtered combination of files_by_type() and files_by_paths().

Parameters

• file_types: Slice of FileTypes to filter by
• paths: Slice of ContainerPaths to match
• case_insensitive: Enable case-insensitive path matching

Returns

A vector of references to files matching both the type and path criteria.

fn files_by_type_and_paths_mut( &mut self, file_types: &[FileType], paths: &[ContainerPath], case_insensitive: bool, ) -> Vec<&mut RFile>

Returns mutable references to files matching both type and path criteria.

This is a filtered combination of files_by_type_mut() and files_by_paths_mut().

Parameters

• file_types: Slice of FileTypes to filter by
• paths: Slice of ContainerPaths to match
• case_insensitive: Enable case-insensitive path matching

Returns

A vector of mutable references to files matching both the type and path criteria.

fn paths_cache_generate(&mut self)

Regenerates the internal paths cache from the current file list.

The paths cache maps lowercase paths to their actual casing variants, enabling efficient case-insensitive lookups. This method should be called after bulk modifications to the file list.

fn paths_cache_insert_path(&mut self, path: &str)

Adds a single path to the paths cache.

This is more efficient than regenerating the entire cache when adding individual files.

Parameters

• path: The file path to add (with original casing)

fn paths_cache_remove_path(&mut self, path: &str)

Removes a single path from the paths cache.

This is more efficient than regenerating the entire cache when removing individual files.

Parameters

• path: The file path to remove (with original casing)

Note

Reserved paths (notes, settings) are automatically skipped.

fn paths_folders_raw(&self) -> HashSet<String>

Returns a set of all folder paths contained within the container.

This method analyzes file paths to extract unique folder hierarchies.

Returns

A set of folder paths (without trailing slashes). Root-level files contribute no entries.

fn paths(&self) -> Vec<ContainerPath>

This method returns the list of ContainerPath corresponding to RFiles within the provided Container.

fn paths_raw(&self) -> Vec<&str>

This method returns the list of paths (as &str) corresponding to RFiles within the provided Container.

fn paths_raw_from_container_path(&self, path: &ContainerPath) -> Vec<String>

This function returns the list of paths (as String) corresponding to RFiles that match the provided ContainerPath.

fn internal_timestamp(&self) -> u64

This method returns the Last modified date stored on the provided Container, in seconds.

A default implementation that returns 0 is provided for Container types that don’t support internal timestamps.

Implementors should return 0 if the Container doesn’t have a file on disk yet.

fn preload(&mut self) -> Result<()>

This function preloads to memory any lazy-loaded RFile within this container.

fn move_paths( &mut self, in_out_paths: &[(ContainerPath, ContainerPath)], ) -> Result<Vec<(ContainerPath, ContainerPath)>>

This function allows you to move multiple RFiles or folders of RFiles from one folder to another.

It returns a list with all the new ContainerPath.

fn move_path( &mut self, source_path: &ContainerPath, destination_path: &ContainerPath, ) -> Result<Vec<(ContainerPath, ContainerPath)>>

This function allows you to move any RFile or folder of RFiles from one folder to another.

It returns a list with all the new ContainerPath.

fn clean_undecoded(&mut self)

This function removes all not-in-memory-already Files from the Container.

Used for removing possibly corrupted RFiles from the Container in order to sanitize it.

BE CAREFUL WITH USING THIS. IT MAY (PROBABLY WILL) CAUSE DATA LOSSES.

Implementors

impl Container for AnimPack

impl Container for Pack