disk 0.1.21

(De)serialize files to/from disk
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

//---------------------------------------------------------------------------------------------------- Use
use anyhow::{anyhow,bail};
use std::path::PathBuf;
use crate::common;
use serde_json::ser::{Serializer,PrettyFormatter};
use std::io::{
	Read,Write,
	BufReader,
};
use once_cell::sync::Lazy;

//---------------------------------------------------------------------------------------------------- Json
static ENCODING_OPTIONS: Lazy<PrettyFormatter<'static>> = Lazy::new(|| PrettyFormatter::with_indent(b"    "));

crate::common::impl_macro!(Json, "json");
//crate::common::impl_macro_outer!(Json, "json");

/// [`JSON`](https://docs.rs/serde_json) file format
///
/// File extension is `.json`.
///
/// ## Encoding
/// The encoding option used is:
/// ```txt
/// serde_json::ser::PrettyFormatter::with_indent(b"    ");
/// ```
/// This is 4 spaces instead of the default 2.
///
/// ## Safety
/// When manually implementing, you are **promising** that the `PATH`'s manually specified are correct.
pub unsafe trait Json: serde::Serialize + serde::de::DeserializeOwned {
	#[doc(hidden)]
	#[inline(always)]
	/// Internal function. Most efficient `from_file()` impl.
	fn __from_file() -> Result<Self, anyhow::Error> {
		let path = Self::absolute_path()?;
		let file = std::fs::File::open(path)?;
		Ok(serde_json::from_reader(BufReader::new(file))?)
	}

	#[doc(hidden)]
	#[inline(always)]
	/// Internal function. Most efficient `from_path()` impl.
	fn __from_path(path: &std::path::Path) -> Result<Self, anyhow::Error> {
		let file = std::fs::File::open(path)?;
		Ok(serde_json::from_reader(BufReader::new(file))?)
	}

	// Required functions for generic-ness.
	#[inline(always)]
	/// Convert [`Self`] to bytes.
	fn to_bytes(&self) -> Result<Vec<u8>, anyhow::Error> {
		let mut vec = Vec::with_capacity(128);
		let mut ser = Serializer::with_formatter(&mut vec, ENCODING_OPTIONS.clone());
		self.serialize(&mut ser)?;
		Ok(vec)
	}
	#[inline(always)]
	/// Create [`Self`] from bytes.
	fn from_bytes(bytes: &[u8]) -> Result<Self, anyhow::Error> {
		Ok(serde_json::de::from_slice(bytes)?)
	}

	// JSON operations.
	#[inline(always)]
	/// This uses [`serde_json::ser::to_string_pretty`];
	fn to_string(&self) -> Result<String, anyhow::Error> {
		let vec = self.to_bytes()?;
		// SAFETY
		// `serde_json` doesn't emit
		// invalid UTF-8 if vec is successful.
		unsafe { Ok(String::from_utf8_unchecked(vec)) }
	}
	#[inline(always)]
	/// Create [`Self`] from a [`String`].
	fn from_string(string: &str) -> Result<Self, anyhow::Error> {
		Ok(serde_json::de::from_str(string)?)
	}

	// Common functions.
	common::impl_string!("json");
}

//---------------------------------------------------------------------------------------------------- TESTS
//#[cfg(test)]
//mod tests {
//}