1#![forbid(unsafe_code)]
41#![warn(missing_docs)]
42
43pub(crate) mod format;
44mod reader;
45pub mod write;
46
47pub use write::{RealmBuilder, TableBuilder};
48
49use std::path::Path;
50
51#[derive(Debug)]
55#[non_exhaustive]
56pub enum RealmError {
57 Io(std::io::Error),
59 InvalidFormat(String),
61 UnsupportedVersion(u32),
63}
64
65impl std::fmt::Display for RealmError {
66 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
67 match self {
68 RealmError::Io(e) => write!(f, "I/O error: {e}"),
69 RealmError::InvalidFormat(msg) => write!(f, "invalid Realm format: {msg}"),
70 RealmError::UnsupportedVersion(v) => {
71 write!(f, "unsupported Realm version {v} (only v9 is supported)")
72 }
73 }
74 }
75}
76
77impl std::error::Error for RealmError {
78 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
79 if let RealmError::Io(e) = self { Some(e) } else { None }
80 }
81}
82
83impl From<std::io::Error> for RealmError {
84 fn from(e: std::io::Error) -> Self {
85 RealmError::Io(e)
86 }
87}
88
89pub type Result<T> = std::result::Result<T, RealmError>;
91
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
98#[non_exhaustive]
99pub enum ColumnType {
100 Int,
102 Bool,
104 String,
106 Data,
108 Float,
110 Double,
112 Timestamp,
114 Link,
116 LinkList,
118 BackLink,
120 Unknown(u8),
122}
123
124impl ColumnType {
125 pub fn from_u8(v: u8) -> Self {
127 match v {
128 0 => ColumnType::Int,
129 1 => ColumnType::Bool,
130 2 => ColumnType::String,
131 3 => ColumnType::Data,
132 4 => ColumnType::Float,
133 5 => ColumnType::Double,
134 7 => ColumnType::Timestamp,
135 8 | 12 => ColumnType::Link,
136 9 | 13 => ColumnType::LinkList,
137 14 => ColumnType::BackLink,
138 other => ColumnType::Unknown(other),
139 }
140 }
141}
142
143#[derive(Debug, Clone, PartialEq)]
147#[non_exhaustive]
148pub enum Value {
149 Null,
151 Bool(bool),
153 Int(i64),
155 Float(f64),
157 Timestamp(i64),
159 String(String),
161 Link(usize),
163}
164
165impl Value {
166 pub fn is_null(&self) -> bool {
168 matches!(self, Value::Null)
169 }
170
171 pub fn as_str(&self) -> &str {
173 if let Value::String(s) = self { s } else { "" }
174 }
175
176 pub fn as_int(&self) -> i64 {
178 if let Value::Int(i) = self { *i } else { 0 }
179 }
180
181 pub fn as_bool(&self) -> bool {
183 if let Value::Bool(b) = self { *b } else { false }
184 }
185
186 pub fn as_timestamp(&self) -> i64 {
188 if let Value::Timestamp(t) = self { *t } else { 0 }
189 }
190
191 pub fn as_float(&self) -> f64 {
193 if let Value::Float(f) = self { *f } else { 0.0 }
194 }
195}
196
197#[derive(Debug, Clone)]
203pub struct Row {
204 pub values: Vec<Value>,
206}
207
208impl Row {
209 pub fn get(&self, col_idx: usize) -> &Value {
211 self.values.get(col_idx).unwrap_or(&Value::Null)
212 }
213}
214
215#[derive(Debug, Clone)]
219pub struct RealmTable {
220 pub name: String,
222 pub columns: Vec<(String, ColumnType)>,
224 pub rows: Vec<Row>,
226}
227
228impl RealmTable {
229 pub fn column_index(&self, name: &str) -> Option<usize> {
231 self.columns.iter().position(|(n, _)| n == name)
232 }
233
234 pub fn get<'a>(&self, row: &'a Row, col_name: &str) -> &'a Value {
238 match self.column_index(col_name) {
239 Some(i) => row.get(i),
240 None => &Value::Null,
241 }
242 }
243}
244
245pub struct RealmFile {
251 tables: Vec<RealmTable>,
252}
253
254impl RealmFile {
255 pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
263 let data = std::fs::read(path)?;
264 Self::from_bytes(&data)
265 }
266
267 pub fn from_bytes(data: &[u8]) -> Result<Self> {
271 let tables = reader::read_tables(data)?;
272 Ok(RealmFile { tables })
273 }
274
275 pub fn tables(&self) -> &[RealmTable] {
277 &self.tables
278 }
279
280 pub fn table(&self, name: &str) -> Option<&RealmTable> {
284 self.tables.iter().find(|t| t.name == name)
285 }
286}
287
288#[cfg(test)]
291mod tests {
292 use super::format::*;
293 use super::*;
294
295 #[test]
298 fn node_header_bits_width8() {
299 let mut h = [0u8; 8];
300 h[4] = 4;
302 h[7] = 5;
303 let hdr = NodeHeader::parse(&h);
304 assert_eq!(hdr.width, 8);
305 assert_eq!(hdr.wtype, WTYPE_BITS);
306 assert_eq!(hdr.size, 5);
307 assert!(!hdr.is_inner);
308 }
309
310 #[test]
311 fn node_header_multiply_width64() {
312 let mut h = [0u8; 8];
313 h[4] = (WTYPE_MULTIPLY << 3) | 7;
315 h[7] = 3;
316 let hdr = NodeHeader::parse(&h);
317 assert_eq!(hdr.wtype, WTYPE_MULTIPLY);
318 assert_eq!(hdr.width, 64);
319 assert_eq!(hdr.size, 3);
320 }
321
322 #[test]
323 fn node_header_width_encoding_all_values() {
324 let expected = [0u8, 1, 2, 4, 8, 16, 32, 64];
326 for (enc, &exp) in expected.iter().enumerate() {
327 let mut h = [0u8; 8];
328 h[4] = enc as u8;
329 assert_eq!(NodeHeader::parse(&h).width, exp, "enc={enc}");
330 }
331 }
332
333 #[test]
334 fn node_header_size_three_bytes() {
335 let mut h = [0u8; 8];
337 h[5] = 0x01;
338 h[6] = 0x02;
339 h[7] = 0x03;
340 assert_eq!(NodeHeader::parse(&h).size, 0x010203);
341 }
342
343 #[test]
344 fn node_header_inner_flag() {
345 let mut h = [0u8; 8];
346 h[4] = 0x80;
347 assert!(NodeHeader::parse(&h).is_inner);
348 }
349
350 #[test]
353 fn decode_short_string_normal() {
354 let mut slot = [0u8; 32];
355 slot[..5].copy_from_slice(b"hello");
356 slot[31] = 26; assert_eq!(decode_short_string(&slot), "hello");
358 }
359
360 #[test]
361 fn decode_short_string_empty() {
362 let mut slot = [0u8; 8];
363 slot[7] = 7; assert_eq!(decode_short_string(&slot), "");
365 }
366
367 #[test]
368 fn decode_short_string_full_slot() {
369 let mut slot = [b'x'; 8];
371 slot[7] = 0;
372 let s = decode_short_string(&slot);
373 assert_eq!(s.len(), 7);
374 }
375
376 #[test]
377 fn decode_short_string_empty_slice() {
378 assert_eq!(decode_short_string(&[]), "");
379 }
380
381 #[test]
384 fn read_bits_elem_8bit() {
385 let data = [10u8, 20, 30];
386 assert_eq!(read_bits_elem(&data, 0, 8), 10);
387 assert_eq!(read_bits_elem(&data, 2, 8), 30);
388 }
389
390 #[test]
391 fn read_bits_elem_4bit() {
392 let data = [0xABu8];
394 assert_eq!(read_bits_elem(&data, 0, 4), 0xB);
395 assert_eq!(read_bits_elem(&data, 1, 4), 0xA);
396 }
397
398 #[test]
399 fn read_bits_elem_1bit() {
400 let data = [0b1010_1010u8];
401 assert_eq!(read_bits_elem(&data, 0, 1), 0);
402 assert_eq!(read_bits_elem(&data, 1, 1), 1);
403 assert_eq!(read_bits_elem(&data, 7, 1), 1);
404 }
405
406 #[test]
407 fn read_bits_elem_64bit() {
408 let val: u64 = 0xDEAD_BEEF_1234_5678;
409 let data = val.to_le_bytes();
410 assert_eq!(read_bits_elem(&data, 0, 64), val);
411 }
412
413 #[test]
414 fn read_bits_elem_zero_width() {
415 assert_eq!(read_bits_elem(&[0xFF], 0, 0), 0);
416 }
417
418 #[test]
421 fn column_type_known_codes() {
422 assert_eq!(ColumnType::from_u8(0), ColumnType::Int);
423 assert_eq!(ColumnType::from_u8(1), ColumnType::Bool);
424 assert_eq!(ColumnType::from_u8(2), ColumnType::String);
425 assert_eq!(ColumnType::from_u8(3), ColumnType::Data);
426 assert_eq!(ColumnType::from_u8(4), ColumnType::Float);
427 assert_eq!(ColumnType::from_u8(5), ColumnType::Double);
428 assert_eq!(ColumnType::from_u8(7), ColumnType::Timestamp);
429 assert_eq!(ColumnType::from_u8(8), ColumnType::Link);
430 assert_eq!(ColumnType::from_u8(12), ColumnType::Link);
431 assert_eq!(ColumnType::from_u8(9), ColumnType::LinkList);
432 assert_eq!(ColumnType::from_u8(14), ColumnType::BackLink);
433 }
434
435 #[test]
436 fn column_type_unknown() {
437 assert!(matches!(ColumnType::from_u8(99), ColumnType::Unknown(99)));
438 }
439
440 #[test]
443 fn value_accessors_hit() {
444 assert_eq!(Value::String("hi".into()).as_str(), "hi");
445 assert_eq!(Value::Int(42).as_int(), 42);
446 assert_eq!(Value::Bool(true).as_bool(), true);
447 assert_eq!(Value::Timestamp(100).as_timestamp(), 100);
448 assert!((Value::Float(3.14).as_float() - 3.14).abs() < 1e-9);
449 }
450
451 #[test]
452 fn value_accessors_miss() {
453 assert_eq!(Value::Null.as_str(), "");
454 assert_eq!(Value::Null.as_int(), 0);
455 assert_eq!(Value::Null.as_bool(), false);
456 assert_eq!(Value::Null.as_timestamp(), 0);
457 assert_eq!(Value::Null.as_float(), 0.0);
458 }
459
460 #[test]
461 fn value_is_null() {
462 assert!(Value::Null.is_null());
463 assert!(!Value::Int(1).is_null());
464 assert!(!Value::String("x".into()).is_null());
465 }
466
467 #[test]
470 fn row_get_in_bounds() {
471 let row = Row { values: vec![Value::Int(1), Value::Bool(true)] };
472 assert_eq!(row.get(0), &Value::Int(1));
473 assert_eq!(row.get(1), &Value::Bool(true));
474 }
475
476 #[test]
477 fn row_get_out_of_bounds() {
478 let row = Row { values: vec![Value::Int(1)] };
479 assert_eq!(row.get(99), &Value::Null);
480 }
481
482 #[test]
483 fn realm_table_column_index() {
484 let table = RealmTable {
485 name: "t".into(),
486 columns: vec![
487 ("id".into(), ColumnType::String),
488 ("age".into(), ColumnType::Int),
489 ],
490 rows: vec![],
491 };
492 assert_eq!(table.column_index("id"), Some(0));
493 assert_eq!(table.column_index("age"), Some(1));
494 assert_eq!(table.column_index("missing"), None);
495 }
496
497 #[test]
498 fn realm_table_get_by_name() {
499 let row = Row { values: vec![Value::String("abc".into()), Value::Int(7)] };
500 let table = RealmTable {
501 name: "t".into(),
502 columns: vec![
503 ("id".into(), ColumnType::String),
504 ("count".into(), ColumnType::Int),
505 ],
506 rows: vec![],
507 };
508 assert_eq!(table.get(&row, "id").as_str(), "abc");
509 assert_eq!(table.get(&row, "count").as_int(), 7);
510 assert_eq!(table.get(&row, "missing"), &Value::Null);
511 }
512
513 #[test]
516 fn file_too_small_rejected() {
517 let result = RealmFile::from_bytes(&[0u8; 10]);
518 assert!(matches!(result, Err(RealmError::InvalidFormat(_))));
519 }
520
521 #[test]
522 fn bad_magic_rejected() {
523 let mut data = vec![0u8; 24];
524 data[16..20].copy_from_slice(b"XXXX");
525 data[20..24].copy_from_slice(&9u32.to_le_bytes());
526 assert!(matches!(
527 RealmFile::from_bytes(&data),
528 Err(RealmError::InvalidFormat(_))
529 ));
530 }
531
532 #[test]
533 fn unsupported_version_rejected() {
534 let mut data = vec![0u8; 24];
535 data[16..20].copy_from_slice(b"T-DB");
536 data[20..24].copy_from_slice(&5u32.to_le_bytes());
537 assert!(matches!(
538 RealmFile::from_bytes(&data),
539 Err(RealmError::UnsupportedVersion(5))
540 ));
541 }
542
543 #[test]
544 fn realm_error_display() {
545 let e = RealmError::UnsupportedVersion(5);
546 assert!(e.to_string().contains("v9"));
547 let e = RealmError::InvalidFormat("bad".into());
548 assert!(e.to_string().contains("bad"));
549 }
550
551 #[test]
552 fn realm_error_source_io() {
553 use std::error::Error;
554 let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "missing");
555 let e = RealmError::from(io_err);
556 assert!(e.source().is_some());
557 }
558
559 #[test]
560 fn realm_error_source_non_io() {
561 use std::error::Error;
562 let e = RealmError::InvalidFormat("x".into());
563 assert!(e.source().is_none());
564 }
565}