#![forbid(unsafe_code)]
#![warn(missing_docs)]
pub(crate) mod format;
mod reader;
pub mod write;
pub use write::{RealmBuilder, TableBuilder};
use std::path::Path;
#[derive(Debug)]
#[non_exhaustive]
pub enum RealmError {
Io(std::io::Error),
InvalidFormat(String),
UnsupportedVersion(u32),
}
impl std::fmt::Display for RealmError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
RealmError::Io(e) => write!(f, "I/O error: {e}"),
RealmError::InvalidFormat(msg) => write!(f, "invalid Realm format: {msg}"),
RealmError::UnsupportedVersion(v) => {
write!(f, "unsupported Realm version {v} (only v9 is supported)")
}
}
}
}
impl std::error::Error for RealmError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
if let RealmError::Io(e) = self { Some(e) } else { None }
}
}
impl From<std::io::Error> for RealmError {
fn from(e: std::io::Error) -> Self {
RealmError::Io(e)
}
}
pub type Result<T> = std::result::Result<T, RealmError>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ColumnType {
Int,
Bool,
String,
Data,
Float,
Double,
Timestamp,
Link,
LinkList,
BackLink,
Unknown(u8),
}
impl ColumnType {
pub fn from_u8(v: u8) -> Self {
match v {
0 => ColumnType::Int,
1 => ColumnType::Bool,
2 => ColumnType::String,
3 => ColumnType::Data,
4 => ColumnType::Float,
5 => ColumnType::Double,
7 => ColumnType::Timestamp,
8 | 12 => ColumnType::Link,
9 | 13 => ColumnType::LinkList,
14 => ColumnType::BackLink,
other => ColumnType::Unknown(other),
}
}
}
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum Value {
Null,
Bool(bool),
Int(i64),
Float(f64),
Timestamp(i64),
String(String),
Link(usize),
}
impl Value {
pub fn is_null(&self) -> bool {
matches!(self, Value::Null)
}
pub fn as_str(&self) -> &str {
if let Value::String(s) = self { s } else { "" }
}
pub fn as_int(&self) -> i64 {
if let Value::Int(i) = self { *i } else { 0 }
}
pub fn as_bool(&self) -> bool {
if let Value::Bool(b) = self { *b } else { false }
}
pub fn as_timestamp(&self) -> i64 {
if let Value::Timestamp(t) = self { *t } else { 0 }
}
pub fn as_float(&self) -> f64 {
if let Value::Float(f) = self { *f } else { 0.0 }
}
}
#[derive(Debug, Clone)]
pub struct Row {
pub values: Vec<Value>,
}
impl Row {
pub fn get(&self, col_idx: usize) -> &Value {
self.values.get(col_idx).unwrap_or(&Value::Null)
}
}
#[derive(Debug, Clone)]
pub struct RealmTable {
pub name: String,
pub columns: Vec<(String, ColumnType)>,
pub rows: Vec<Row>,
}
impl RealmTable {
pub fn column_index(&self, name: &str) -> Option<usize> {
self.columns.iter().position(|(n, _)| n == name)
}
pub fn get<'a>(&self, row: &'a Row, col_name: &str) -> &'a Value {
match self.column_index(col_name) {
Some(i) => row.get(i),
None => &Value::Null,
}
}
}
pub struct RealmFile {
tables: Vec<RealmTable>,
}
impl RealmFile {
pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
let data = std::fs::read(path)?;
Self::from_bytes(&data)
}
pub fn from_bytes(data: &[u8]) -> Result<Self> {
let tables = reader::read_tables(data)?;
Ok(RealmFile { tables })
}
pub fn tables(&self) -> &[RealmTable] {
&self.tables
}
pub fn table(&self, name: &str) -> Option<&RealmTable> {
self.tables.iter().find(|t| t.name == name)
}
}
#[cfg(test)]
mod tests {
use super::format::*;
use super::*;
#[test]
fn node_header_bits_width8() {
let mut h = [0u8; 8];
h[4] = 4;
h[7] = 5;
let hdr = NodeHeader::parse(&h);
assert_eq!(hdr.width, 8);
assert_eq!(hdr.wtype, WTYPE_BITS);
assert_eq!(hdr.size, 5);
assert!(!hdr.is_inner);
}
#[test]
fn node_header_multiply_width64() {
let mut h = [0u8; 8];
h[4] = (WTYPE_MULTIPLY << 3) | 7;
h[7] = 3;
let hdr = NodeHeader::parse(&h);
assert_eq!(hdr.wtype, WTYPE_MULTIPLY);
assert_eq!(hdr.width, 64);
assert_eq!(hdr.size, 3);
}
#[test]
fn node_header_width_encoding_all_values() {
let expected = [0u8, 1, 2, 4, 8, 16, 32, 64];
for (enc, &exp) in expected.iter().enumerate() {
let mut h = [0u8; 8];
h[4] = enc as u8;
assert_eq!(NodeHeader::parse(&h).width, exp, "enc={enc}");
}
}
#[test]
fn node_header_size_three_bytes() {
let mut h = [0u8; 8];
h[5] = 0x01;
h[6] = 0x02;
h[7] = 0x03;
assert_eq!(NodeHeader::parse(&h).size, 0x010203);
}
#[test]
fn node_header_inner_flag() {
let mut h = [0u8; 8];
h[4] = 0x80;
assert!(NodeHeader::parse(&h).is_inner);
}
#[test]
fn decode_short_string_normal() {
let mut slot = [0u8; 32];
slot[..5].copy_from_slice(b"hello");
slot[31] = 26; assert_eq!(decode_short_string(&slot), "hello");
}
#[test]
fn decode_short_string_empty() {
let mut slot = [0u8; 8];
slot[7] = 7; assert_eq!(decode_short_string(&slot), "");
}
#[test]
fn decode_short_string_full_slot() {
let mut slot = [b'x'; 8];
slot[7] = 0;
let s = decode_short_string(&slot);
assert_eq!(s.len(), 7);
}
#[test]
fn decode_short_string_empty_slice() {
assert_eq!(decode_short_string(&[]), "");
}
#[test]
fn read_bits_elem_8bit() {
let data = [10u8, 20, 30];
assert_eq!(read_bits_elem(&data, 0, 8), 10);
assert_eq!(read_bits_elem(&data, 2, 8), 30);
}
#[test]
fn read_bits_elem_4bit() {
let data = [0xABu8];
assert_eq!(read_bits_elem(&data, 0, 4), 0xB);
assert_eq!(read_bits_elem(&data, 1, 4), 0xA);
}
#[test]
fn read_bits_elem_1bit() {
let data = [0b1010_1010u8];
assert_eq!(read_bits_elem(&data, 0, 1), 0);
assert_eq!(read_bits_elem(&data, 1, 1), 1);
assert_eq!(read_bits_elem(&data, 7, 1), 1);
}
#[test]
fn read_bits_elem_64bit() {
let val: u64 = 0xDEAD_BEEF_1234_5678;
let data = val.to_le_bytes();
assert_eq!(read_bits_elem(&data, 0, 64), val);
}
#[test]
fn read_bits_elem_zero_width() {
assert_eq!(read_bits_elem(&[0xFF], 0, 0), 0);
}
#[test]
fn column_type_known_codes() {
assert_eq!(ColumnType::from_u8(0), ColumnType::Int);
assert_eq!(ColumnType::from_u8(1), ColumnType::Bool);
assert_eq!(ColumnType::from_u8(2), ColumnType::String);
assert_eq!(ColumnType::from_u8(3), ColumnType::Data);
assert_eq!(ColumnType::from_u8(4), ColumnType::Float);
assert_eq!(ColumnType::from_u8(5), ColumnType::Double);
assert_eq!(ColumnType::from_u8(7), ColumnType::Timestamp);
assert_eq!(ColumnType::from_u8(8), ColumnType::Link);
assert_eq!(ColumnType::from_u8(12), ColumnType::Link);
assert_eq!(ColumnType::from_u8(9), ColumnType::LinkList);
assert_eq!(ColumnType::from_u8(14), ColumnType::BackLink);
}
#[test]
fn column_type_unknown() {
assert!(matches!(ColumnType::from_u8(99), ColumnType::Unknown(99)));
}
#[test]
fn value_accessors_hit() {
assert_eq!(Value::String("hi".into()).as_str(), "hi");
assert_eq!(Value::Int(42).as_int(), 42);
assert_eq!(Value::Bool(true).as_bool(), true);
assert_eq!(Value::Timestamp(100).as_timestamp(), 100);
assert!((Value::Float(3.14).as_float() - 3.14).abs() < 1e-9);
}
#[test]
fn value_accessors_miss() {
assert_eq!(Value::Null.as_str(), "");
assert_eq!(Value::Null.as_int(), 0);
assert_eq!(Value::Null.as_bool(), false);
assert_eq!(Value::Null.as_timestamp(), 0);
assert_eq!(Value::Null.as_float(), 0.0);
}
#[test]
fn value_is_null() {
assert!(Value::Null.is_null());
assert!(!Value::Int(1).is_null());
assert!(!Value::String("x".into()).is_null());
}
#[test]
fn row_get_in_bounds() {
let row = Row { values: vec![Value::Int(1), Value::Bool(true)] };
assert_eq!(row.get(0), &Value::Int(1));
assert_eq!(row.get(1), &Value::Bool(true));
}
#[test]
fn row_get_out_of_bounds() {
let row = Row { values: vec![Value::Int(1)] };
assert_eq!(row.get(99), &Value::Null);
}
#[test]
fn realm_table_column_index() {
let table = RealmTable {
name: "t".into(),
columns: vec![
("id".into(), ColumnType::String),
("age".into(), ColumnType::Int),
],
rows: vec![],
};
assert_eq!(table.column_index("id"), Some(0));
assert_eq!(table.column_index("age"), Some(1));
assert_eq!(table.column_index("missing"), None);
}
#[test]
fn realm_table_get_by_name() {
let row = Row { values: vec![Value::String("abc".into()), Value::Int(7)] };
let table = RealmTable {
name: "t".into(),
columns: vec![
("id".into(), ColumnType::String),
("count".into(), ColumnType::Int),
],
rows: vec![],
};
assert_eq!(table.get(&row, "id").as_str(), "abc");
assert_eq!(table.get(&row, "count").as_int(), 7);
assert_eq!(table.get(&row, "missing"), &Value::Null);
}
#[test]
fn file_too_small_rejected() {
let result = RealmFile::from_bytes(&[0u8; 10]);
assert!(matches!(result, Err(RealmError::InvalidFormat(_))));
}
#[test]
fn bad_magic_rejected() {
let mut data = vec![0u8; 24];
data[16..20].copy_from_slice(b"XXXX");
data[20..24].copy_from_slice(&9u32.to_le_bytes());
assert!(matches!(
RealmFile::from_bytes(&data),
Err(RealmError::InvalidFormat(_))
));
}
#[test]
fn unsupported_version_rejected() {
let mut data = vec![0u8; 24];
data[16..20].copy_from_slice(b"T-DB");
data[20..24].copy_from_slice(&5u32.to_le_bytes());
assert!(matches!(
RealmFile::from_bytes(&data),
Err(RealmError::UnsupportedVersion(5))
));
}
#[test]
fn realm_error_display() {
let e = RealmError::UnsupportedVersion(5);
assert!(e.to_string().contains("v9"));
let e = RealmError::InvalidFormat("bad".into());
assert!(e.to_string().contains("bad"));
}
#[test]
fn realm_error_source_io() {
use std::error::Error;
let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "missing");
let e = RealmError::from(io_err);
assert!(e.source().is_some());
}
#[test]
fn realm_error_source_non_io() {
use std::error::Error;
let e = RealmError::InvalidFormat("x".into());
assert!(e.source().is_none());
}
}