Struct DB 

pub struct DB { /* private fields */ }

In-memory representation of a decoded DB table.

Holds a complete DB table including header metadata and row data. The table data is stored as a TableInMemory which provides access to rows and columns.

Fields

• mysterious_byte - Boolean flag of unknown purpose (observed as 0 or 1)
• guid - Globally Unique Identifier for this table instance
• table - The actual table data with definition and rows

Getters

Fields have public getters via the getset crate:

• mysterious_byte() - Get the mysterious byte value
• guid() - Get the table’s GUID
• table() - Get reference to the table data

The Mysterious Byte

The purpose of this byte is unknown, but it appears in all DB tables. Observed values are 0 or 1 (interpreted as boolean). In Warhammer 2, a value of 0 can cause crashes when tables are loaded by the game.

GUID Handling

GUIDs are only present in some games (e.g., Warhammer series). Older games like Napoleon and Empire don’t use GUIDs, and adding them can crash those games. The encoding process respects the game’s GUID requirements.

Example

use rpfm_lib::files::{Decodeable, db::DB, DecodeableExtraData, table::Table};
use rpfm_lib::schema::Schema;
use std::io::Cursor;

let mut extra = DecodeableExtraData::default();
extra.set_schema(Some(&schema));
extra.set_table_name(Some("units_tables"));

let mut reader = Cursor::new(table_data);
let db = DB::decode(&mut reader, &Some(extra)).unwrap();

// Access table data
let row_count = db.table().len();

Implementations

impl DB

pub fn mysterious_byte(&self) -> &bool

Boolean flag of unknown purpose (always 0 or 1).

In Warhammer 2, a value of 0 can crash the game when loading tables.

pub fn guid(&self) -> &String

Globally Unique Identifier for this table instance.

Only present in newer games. Empty string for games without GUID support.

pub fn table(&self) -> &TableInMemory

The table data including definition and rows.

impl DB

pub fn new( definition: &Definition, definition_patch: Option<&DefinitionPatch>, table_name: &str, ) -> Self

Creates a new empty DB table with the specified definition.

Initializes a DB table with no rows but with the structure defined by the provided definition. The mysterious byte is set to true (safe default) and the GUID is empty.

Arguments

• definition - Schema definition specifying column types and structure
• definition_patch - Optional patches to modify the definition
• table_name - Name of the table (for internal tracking)

Returns

A new empty DB table ready to have rows added.

Example

use rpfm_lib::files::{db::DB, table::Table};
use rpfm_lib::schema::Definition;

let db = DB::new(&definition, None, "units_tables");
assert_eq!(db.table().len(), 0);

pub fn read_header<R: ReadBytes>( data: &mut R, ) -> Result<(i32, bool, String, u32)>

Decodes the header section of a DB table.

Reads the header bytes to extract metadata without decoding the full table data. This is useful for inspecting table properties before committing to a full decode.

Header Format

The header contains optional and required fields:

1. Optional GUID Marker (0xFD 0xFE 0xFC 0xFF) + 2-byte sized UTF-16 string
2. Optional Version Marker (0xFC 0xFD 0xFE 0xFF) + 4-byte signed integer
3. Mysterious Byte (1 byte boolean)
4. Entry Count (4-byte unsigned integer)

Arguments

• data - Reader positioned at the start of the DB table

Returns

A tuple containing:

• version - Table version number (0 if no version marker present)
• mysterious_byte - Unknown boolean flag
• guid - Table GUID (empty string if no GUID marker present)
• entry_count - Number of rows in the table

Errors

Returns RLibError::DecodingDBNotADBTable if:

• The data is less than 5 bytes (minimum valid header size)
• The data doesn’t conform to the DB header format

Side Effects

After reading, the reader is positioned at the start of the table data section.

pub fn definition(&self) -> &Definition

Returns the schema definition for this DB table.

pub fn patches(&self) -> &DefinitionPatch

Returns the definition patches applied to this DB table.

pub fn table_name(&self) -> &str

Returns the table name (e.g., "units_tables").

pub fn table_name_without_tables(&self) -> String

Returns the table name without the "_tables" suffix.

Panics

Panics if the table name doesn’t end with "_tables".

pub fn data(&self) -> Cow<'_, [Vec<DecodedData>]>

Returns the table rows as a slice of decoded data.

pub fn data_mut(&mut self) -> &mut Vec<Vec<DecodedData>>

Returns a mutable reference to the table rows.

Ensure modifications maintain valid structure matching the definition.

pub fn set_data(&mut self, data: &[Vec<DecodedData>]) -> Result<()>

Replaces all table data with the provided rows.

Errors

Returns an error if rows don’t match the table definition structure.

pub fn new_row(&self) -> Vec<DecodedData>

Creates a new row with default values from the table definition.

pub fn column_position_by_name(&self, column_name: &str) -> Option<usize>

Returns the column index for a given column name, or None if not found.

pub fn len(&self) -> usize

Returns the number of rows in the table.

pub fn is_empty(&self) -> bool

Returns true if the table has no rows.

pub fn set_definition(&mut self, new_definition: &Definition)

Replaces the table definition and migrates existing data to match.

Use this to update tables to a newer schema version. Data is converted between compatible types where possible.

pub fn update(&mut self, new_definition: &Definition)

Alias for set_definition.

pub fn cascade_edition( pack: &mut Pack, schema: &Schema, table_name: &str, field: &Field, definition: &Definition, value_before: &str, value_after: &str, ) -> Vec<ContainerPath>

Performs a cascade update of a value across all referencing tables in a Pack.

When a key field value is changed, this function finds all tables that reference that field and updates them accordingly. It also updates corresponding Loc entries if the edited field affects localisation keys.

Arguments

• pack - The Pack to search and update.
• schema - Schema containing table definitions and reference information.
• table_name - Name of the source table (e.g., "units_tables").
• field - The field being edited.
• definition - Definition of the source table.
• value_before - Original value being replaced.
• value_after - New value to set.

Returns

List of paths where references were found and updated.

pub fn merge(sources: &[&Self]) -> Result<Self>

Merges multiple DB tables into a single new table.

Combines all rows from the source tables. The first table’s definition and patches are used for the merged result. All source tables are converted to match this definition before merging.

Errors

Returns an error if:

• Tables have different names (can’t merge units_tables with buildings_tables)
• Fewer than 2 tables are provided

pub fn tsv_import( records: StringRecordsIter<'_, File>, field_order: &HashMap<u32, String>, schema: &Schema, table_name: &str, table_version: i32, ) -> Result<Self>

Imports a DB table from TSV (tab-separated values) format.

Arguments

• records - CSV reader iterator over TSV records.
• field_order - Mapping of column positions to field names.
• schema - Schema containing the table definition.
• table_name - Name of the table (e.g., "units_tables").
• table_version - Version of the table definition to use.

Errors

Returns an error if no matching definition is found in the schema.

pub fn tsv_export( &self, writer: &mut Writer<File>, table_path: &str, keys_first: bool, ) -> Result<()>

Exports the DB table to TSV (tab-separated values) format.

Arguments

• writer - CSV writer for the output file.
• table_path - Path used in the TSV metadata header.
• keys_first - If true, key columns are written before non-key columns.

pub fn altered(&self) -> bool

Returns true if data was modified during decoding (e.g., invalid values corrected).

pub fn generate_twad_key_deletes_keys(&self, keys: &mut HashSet<String>)

Generates combined primary keys to populate the twad_key_deletes table.

Different tables use different key concatenation rules. This function handles the table-specific key format for each known table type.

Trait Implementations

impl Clone for DB

fn clone(&self) -> DB

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DB

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Decodeable for DB

fn decode<R: ReadBytes>( data: &mut R, extra_data: &Option<DecodeableExtraData<'_>>, ) -> Result<Self>

Decodes binary data into the implementing type.

impl<'de> Deserialize<'de> for DB

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Encodeable for DB

fn encode<W: WriteBytes>( &mut self, buffer: &mut W, extra_data: &Option<EncodeableExtraData<'_>>, ) -> Result<()>

Encodes the implementing type into binary data.

impl From<TableInMemory> for DB

Implementation to create a DB from a Table.

fn from(table: TableInMemory) -> Self

Converts to this type from the input type.

impl PartialEq for DB

fn eq(&self, other: &DB) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for DB

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for DB