serde: update serialization documentation and examples

Feature request: #63

Cargo.toml

@@ -170,6 +170,11 @@ name = "doc_worksheet_serialize_intro"
 path = "examples/doc_worksheet_serialize_intro.rs"
 required-features = ["serde"]
 
+[[example]]
+name = "doc_worksheet_serialize_intro2"
+path = "examples/doc_worksheet_serialize_intro2.rs"
+required-features = ["serde"]
+
 [[example]]
 name = "doc_worksheet_serialize_vectors"
 path = "examples/doc_worksheet_serialize_vectors.rs"

examples/doc_worksheet_serialize_headers3.rs

@@ -3,12 +3,13 @@
 // Copyright 2022-2023, John McNamara, [email protected]
 
 //! The following example demonstrates serializing instances of a Serde derived
-//! data structure to a worksheet using different methods.
+//! data structure to a worksheet using different methods (both serialization
+//! and deserialization).
 
 use rust_xlsxwriter::{
     CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
 };
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -30,7 +31,7 @@ fn main() -> Result<(), XlsxError> {
     let currency_format = Format::new().set_num_format("$0.00");
 
     // Create a serializable test struct.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         fruit: &'static str,
         cost: f64,
@@ -52,9 +53,9 @@ fn main() -> Result<(), XlsxError> {
         cost: 0.75,
     };
 
-    // 1. Set the serialization location and headers with `serialize_headers()`
+    // 1. Set the serialization location and headers with `deserialize_headers()`
     //    and serialize some data.
-    worksheet.serialize_headers(0, 0, &item1)?;
+    worksheet.deserialize_headers::<Produce>(0, 0)?;
 
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
@@ -82,17 +83,15 @@ fn main() -> Result<(), XlsxError> {
         .set_custom_headers(&custom_headers);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 6, &item1, &header_options)?;
+    worksheet.deserialize_headers_with_options::<Produce>(0, 6, &header_options)?;
 
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
     worksheet.serialize(&item3)?;
 
-    // 4. Set the serialization location and headers with custom headers. We use
+    // 4. Set the serialization location and headers with custom options. We use
     //    the customization to turn off the headers.
-    let header_options = SerializeHeadersOptions::new()
-        .hide_headers(true)
-        .set_custom_headers(&custom_headers);
+    let header_options = SerializeHeadersOptions::new().hide_headers(true);
 
     // Set the serialization location and custom headers.
     worksheet.serialize_headers_with_options(0, 9, &item1, &header_options)?;

examples/doc_worksheet_serialize_headers_rename1.rs

@@ -6,7 +6,7 @@
 //! using Serde field attributes.
 
 use rust_xlsxwriter::{Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -15,7 +15,7 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Create a serializable test struct. Note the serde attributes.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         #[serde(rename = "Item")]
         fruit: &'static str,
@@ -41,7 +41,7 @@ fn main() -> Result<(), XlsxError> {
     };
 
     // Set the serialization location and headers.
-    worksheet.serialize_headers(0, 0, &item1)?;
+    worksheet.deserialize_headers::<Produce>(0, 0)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_rename2.rs

@@ -3,11 +3,10 @@
 // Copyright 2022-2023, John McNamara, [email protected]
 
 //! The following example demonstrates renaming fields during serialization by
-//! specifying custom headers and renaming them there. You must still specify
-//! the actual field name to serialize in the `new()` constructor.
+//! specifying custom headers and renaming them there.
 //!
 use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -16,7 +15,7 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Create a serializable test struct.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         fruit: &'static str,
         cost: f64,
@@ -46,7 +45,7 @@ fn main() -> Result<(), XlsxError> {
     let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
+    worksheet.deserialize_headers_with_options::<Produce>(0, 0, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_skip1.rs

@@ -7,7 +7,7 @@
 //! to tell rustc not emit a `dead_code` warning.
 
 use rust_xlsxwriter::{Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -16,12 +16,12 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Create a serializable test struct. Note the serde attribute.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         fruit: &'static str,
         cost: f64,
 
-        #[serde(skip_serializing)]
+        #[serde(skip)]
         #[allow(dead_code)]
         in_stock: bool,
     }
@@ -46,7 +46,7 @@ fn main() -> Result<(), XlsxError> {
     };
 
     // Set the serialization location and headers.
-    worksheet.serialize_headers(0, 0, &item1)?;
+    worksheet.deserialize_headers::<Produce>(0, 0)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_skip2.rs

@@ -4,10 +4,10 @@
 
 //! The following example demonstrates skipping fields during serialization by
 //! omitting them from the serialization headers. To do this we need to specify
-//! custom headers.
+//! custom headers and set `use_custom_headers_only()`.
 
 use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -16,7 +16,7 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Create a serializable test struct.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         fruit: &'static str,
         cost: f64,
@@ -42,17 +42,20 @@ fn main() -> Result<(), XlsxError> {
         in_stock: false,
     };
 
-    // Set up the custom headers.
+    // Only set up the custom headers we want and omit "in_stock".
     let custom_headers = [
         CustomSerializeHeader::new("fruit"),
         CustomSerializeHeader::new("cost"),
     ];
+
+    // Note the use of "use_custom_headers_only" to only serialize the named
+    // custom headers.
     let header_options = SerializeHeadersOptions::new()
         .use_custom_headers_only(true)
         .set_custom_headers(&custom_headers);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
+    worksheet.deserialize_headers_with_options::<Produce>(0, 0, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_skip3.rs

@@ -6,7 +6,7 @@
 //! explicitly skipping them via custom headers.
 
 use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -15,7 +15,7 @@ fn main() -> Result<(), XlsxError> {
     let worksheet = workbook.add_worksheet();
 
     // Create a serializable test struct.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     struct Produce {
         fruit: &'static str,
         cost: f64,
@@ -41,16 +41,13 @@ fn main() -> Result<(), XlsxError> {
         in_stock: false,
     };
 
-    // Set up the custom headers.
-    let custom_headers = [
-        CustomSerializeHeader::new("fruit"),
-        CustomSerializeHeader::new("cost"),
-        CustomSerializeHeader::new("in_stock").skip(true),
-    ];
-    let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers);
+    // We only need to set a custom header for the field we want to skip.
+    let header_options = SerializeHeadersOptions::new()
+        .set_custom_headers(&[CustomSerializeHeader::new("in_stock").skip(true)]);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
+    worksheet.deserialize_headers_with_options::<Produce>(0, 0, &header_options)?;
+
     // Serialize the data.
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;

examples/doc_worksheet_serialize_intro2.rs

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright 2022-2023, John McNamara, [email protected]
+
+//! The following example demonstrates serializing instances of a Serde derived
+//! data structure to a worksheet. This version uses header deserialization.
+
+use rust_xlsxwriter::{Format, FormatBorder, Workbook, XlsxError};
+use serde::{Deserialize, Serialize};
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    // Add a worksheet to the workbook.
+    let worksheet = workbook.add_worksheet();
+
+    // Add some formats to use with the serialization data.
+    let header_format = Format::new()
+        .set_bold()
+        .set_border(FormatBorder::Thin)
+        .set_background_color("C6E0B4");
+
+    // Create a serializable test struct.
+    #[derive(Deserialize, Serialize)]
+    #[serde(rename_all = "PascalCase")]
+    struct Student<'a> {
+        name: &'a str,
+        age: u8,
+        id: u32,
+    }
+
+    let students = [
+        Student {
+            name: "Aoife",
+            age: 25,
+            id: 564351,
+        },
+        Student {
+            name: "Caoimhe",
+            age: 21,
+            id: 443287,
+        },
+    ];
+
+    // Set up the start location and headers of the data to be serialized.
+    worksheet.deserialize_headers_with_format::<Student>(1, 3, &header_format)?;
+
+    // Serialize the data.
+    worksheet.serialize(&students)?;
+
+    // Save the file.
+    workbook.save("serialize.xlsx")?;
+
+    Ok(())
+}

src/format.rs

@@ -2399,8 +2399,8 @@ impl From<String> for Format {
     }
 }
 
-/// The `Color` enum defines Excel colors the can be used throughout the
-/// `rust_xlsxwriter`.
+/// The `Color` enum defines Excel colors that can be used throughout the
+/// `rust_xlsxwriter` APIs.
 ///
 /// There are 3 types of colors within the enum:
 ///