Repository: arrayfire/arrayfire-rust (language: rust)

Issue:
Add serialization and deserialization tutorial to the book



Discussion / hints:

Fix patch:
diff --git a/src/core/array.rs b/src/core/array.rs
index 0e741a30a..bae191d25 100644
--- a/src/core/array.rs
+++ b/src/core/array.rs
@@ -1218,6 +1218,7 @@ mod tests {
 
         #[test]
         fn array_serde_json() {
+            // ANCHOR: array_json_serde_snippet
             let input = randu!(u8; 2, 2);
             let serd = match serde_json::to_string(&input) {
                 Ok(serialized_str) => serialized_str,
@@ -1225,12 +1226,14 @@ mod tests {
             };
 
             let deserd: Array<u8> = serde_json::from_str(&serd).unwrap();
+            // ANCHOR_END: array_json_serde_snippet
 
             assert_eq!(sum_all(&(input - deserd)), (0u32, 0u32));
         }
 
         #[test]
         fn array_serde_bincode() {
+            // ANCHOR: array_bincode_serde_snippet
             let input = randu!(u8; 2, 2);
             let encoded = match bincode::serialize(&input) {
                 Ok(encoded) => encoded,
@@ -1238,6 +1241,7 @@ mod tests {
             };
 
             let decoded: Array<u8> = bincode::deserialize(&encoded).unwrap();
+            // ANCHOR_END: array_bincode_serde_snippet
 
             assert_eq!(sum_all(&(input - decoded)), (0u32, 0u32));
         }
diff --git a/src/core/dim4.rs b/src/core/dim4.rs
index 1b869a75b..b5d8d346e 100644
--- a/src/core/dim4.rs
+++ b/src/core/dim4.rs
@@ -151,6 +151,7 @@ mod tests {
 
         #[test]
         fn dim4_serde() {
+            // ANCHOR: dim4_json_serde_snippet
             let dims = dim4!(4, 4);
             let serd = match serde_json::to_string(&dims) {
                 Ok(serialized_str) => serialized_str,
@@ -160,6 +161,7 @@ mod tests {
 
             let deserd: Dim4 = serde_json::from_str(&serd).unwrap();
             assert_eq!(deserd, dims);
+            // ANCHOR_END: dim4_json_serde_snippet
         }
     }
 }
diff --git a/src/core/random.rs b/src/core/random.rs
index 9ec7b9bb6..77c86f7c0 100644
--- a/src/core/random.rs
+++ b/src/core/random.rs
@@ -355,13 +355,19 @@ mod tests {
         #[test]
         #[cfg(feature = "afserde")]
         fn random_engine_serde_bincode() {
-            let input = RandomEngine::new(RandomEngineType::THREEFRY_2X32_16, Some(2047));
+            // ANCHOR: rng_bincode_serde_snippet
+            use RandomEngineType::THREEFRY_2X32_16;
+
+            let input = RandomEngine::new(THREEFRY_2X32_16, Some(2047));
             let encoded = match bincode::serialize(&input) {
                 Ok(encoded) => encoded,
                 Err(_) => vec![],
             };
+            // Save to disk or anything else required
 
+            // Load different object if required
             let decoded: RandomEngine = bincode::deserialize(&encoded).unwrap();
+            // ANCHOR_END: rng_bincode_serde_snippet
 
             assert_eq!(input.get_seed(), decoded.get_seed());
             assert_eq!(input.get_type(), decoded.get_type());
diff --git a/src/core/seq.rs b/src/core/seq.rs
index 4d6ec98c8..c2f9a2c1f 100644
--- a/src/core/seq.rs
+++ b/src/core/seq.rs
@@ -78,6 +78,7 @@ mod tests {
         use super::Seq;
         use crate::seq;
 
+        // ANCHOR: seq_json_serde_snippet
         let original = seq!(1:2:1);
         let serd = match serde_json::to_string(&original) {
             Ok(serialized_str) => serialized_str,
@@ -86,5 +87,6 @@ mod tests {
 
         let deserd: Seq<i32> = serde_json::from_str(&serd).unwrap();
         assert_eq!(deserd, original);
+        // ANCHOR_END: seq_json_serde_snippet
     }
 }
diff --git a/src/image/mod.rs b/src/image/mod.rs
index b1a694708..831e18cad 100644
--- a/src/image/mod.rs
+++ b/src/image/mod.rs
@@ -1400,7 +1400,7 @@ where
 /// digital photography systems where Y is luma component and Cb & Cr are the blue-difference and
 /// red-difference chroma components.
 ///
-/// Input array to this function should be of real data in the range [0,1].
+/// Input array to this function should be of real data in the range \[0,1\].
 ///
 /// # Parameters
 ///
@@ -1435,9 +1435,9 @@ where
 /// Input array to this function should be of real data with the following range in their
 /// respective channels.
 ///
-/// - Y  −> [16,219]
-/// - Cb −> [16,240]
-/// - Cr −> [16,240]
+/// - Y  −> \[16,219\]
+/// - Cb −> \[16,240\]
+/// - Cr −> \[16,240\]
 ///
 /// # Parameters
 ///
diff --git a/tutorials-book/src/SUMMARY.md b/tutorials-book/src/SUMMARY.md
index 64f54e7cf..39a2437f5 100644
--- a/tutorials-book/src/SUMMARY.md
+++ b/tutorials-book/src/SUMMARY.md
@@ -8,3 +8,4 @@
 - [Interoperability with CUDA](./cuda-interop.md)
 - [Interoperability with OpenCL](./opencl-interop.md)
 - [Multhi-Threading](./multi-threading.md)
+- [Serialization & Deserialization](./serde.md)
diff --git a/tutorials-book/src/serde.md b/tutorials-book/src/serde.md
new file mode 100644
index 000000000..c4c5a297a
--- /dev/null
+++ b/tutorials-book/src/serde.md
@@ -0,0 +1,29 @@
+# Serialization & Deserialization of ArrayFire Objects
+
+To save [Array][1] contents, shape in JSON format, it just takes couple of lines of code as shown below:
+```rust,noplaypen
+{{#include ../../src/core/array.rs:array_json_serde_snippet}}
+```
+Saving [Array][1] in different formats is as simple as changing the object qualifier of methods `serialize` and `deserialize`. For example, if user wants to store [Array][1] in `bincode` format instead of JSON, the above code only needs to be change in couple of lines.
+```rust,noplaypen
+{{#include ../../src/core/array.rs:array_bincode_serde_snippet}}
+```
+
+In similar fashion, we can serialize and deserialize [Dim4][2], [RandomEngine][3], [Seq][4] and other Enums. Examples of [Dim4][2], [RandomEngine][3] and [Seq][4] are given below.
+
+```rust,noplaypen
+{{#include ../../src/core/dim4.rs:dim4_json_serde_snippet}}
+```
+
+```rust,noplaypen
+{{#include ../../src/core/random.rs:rng_bincode_serde_snippet}}
+```
+
+```rust,noplaypen
+{{#include ../../src/core/seq.rs:seq_json_serde_snippet}}
+```
+
+[1]: http://arrayfire.org/arrayfire-rust/arrayfire/struct.Array.html
+[2]: http://arrayfire.org/arrayfire-rust/arrayfire/struct.Dim4.html
+[3]: http://arrayfire.org/arrayfire-rust/arrayfire/struct.RandomEngine.html
+[4]: http://arrayfire.org/arrayfire-rust/arrayfire/struct.Seq.html


Test patch: