serde: update serialization documentation and examples

Feature request: #63

Cargo.toml

@@ -85,6 +85,11 @@ name = "app_serialize"
 path = "examples/app_serialize.rs"
 required-features = ["serde"]
 
+[[example]]
+name = "doc_worksheet_deserialize_headers1"
+path = "examples/doc_worksheet_deserialize_headers1.rs"
+required-features = ["serde"]
+
 [[example]]
 name = "doc_worksheet_serialize"
 path = "examples/doc_worksheet_serialize.rs"
@@ -105,6 +110,11 @@ name = "doc_worksheet_serialize_headers3"
 path = "examples/doc_worksheet_serialize_headers3.rs"
 required-features = ["serde"]
 
+[[example]]
+name = "doc_worksheet_serialize_headers4"
+path = "examples/doc_worksheet_serialize_headers4.rs"
+required-features = ["serde"]
+
 [[example]]
 name = "doc_worksheet_serialize_headers_custom"
 path = "examples/doc_worksheet_serialize_headers_custom.rs"
@@ -185,6 +195,11 @@ name = "doc_worksheet_serialize_headers_with_options"
 path = "examples/doc_worksheet_serialize_headers_with_options.rs"
 required-features = ["serde"]
 
+[[example]]
+name = "doc_worksheet_serialize_headers_with_options2"
+path = "examples/doc_worksheet_serialize_headers_with_options2.rs"
+required-features = ["serde"]
+
 [[example]]
 name = "doc_worksheet_serialize_intro"
 path = "examples/doc_worksheet_serialize_intro.rs"
@@ -223,7 +238,6 @@ name = "doc_worksheet_serialize_datetime4"
 path = "examples/doc_worksheet_serialize_datetime4.rs"
 required-features = ["serde", "chrono"]
 
-
 [[example]]
 name = "doc_worksheet_serialize_datetime5"
 path = "examples/doc_worksheet_serialize_datetime5.rs"

examples/doc_worksheet_deserialize_headers1.rs

@@ -0,0 +1,51 @@
+// 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.
+
+use rust_xlsxwriter::{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();
+
+    // Create a serializable struct.
+    #[derive(Deserialize, Serialize)]
+    #[serde(rename_all = "PascalCase")]
+    struct Produce {
+        fruit: &'static str,
+        cost: f64,
+    }
+
+    // Create some data instances.
+    let item1 = Produce {
+        fruit: "Peach",
+        cost: 1.05,
+    };
+    let item2 = Produce {
+        fruit: "Plum",
+        cost: 0.15,
+    };
+    let item3 = Produce {
+        fruit: "Pear",
+        cost: 0.75,
+    };
+
+    // Set up the start location and headers of the data to be serialized.
+    worksheet.deserialize_headers::<Produce>(0, 0)?;
+
+    // Serialize the data.
+    worksheet.serialize(&item1)?;
+    worksheet.serialize(&item2)?;
+    worksheet.serialize(&item3)?;
+
+    // Save the file.
+    workbook.save("serialize.xlsx")?;
+
+    Ok(())
+}

examples/doc_worksheet_serialize.rs

@@ -6,7 +6,7 @@
 //! data structure to a worksheet.
 
 use rust_xlsxwriter::{Format, Workbook, XlsxError};
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), XlsxError> {
     let mut workbook = Workbook::new();
@@ -18,7 +18,7 @@ fn main() -> Result<(), XlsxError> {
     let format = Format::new().set_bold();
 
     // Create a serializable struct.
-    #[derive(Serialize)]
+    #[derive(Deserialize, Serialize)]
     #[serde(rename_all = "PascalCase")]
     struct Produce {
         fruit: &'static str,
@@ -39,9 +39,8 @@ fn main() -> Result<(), XlsxError> {
         cost: 0.75,
     };
 
-    // Set up the start location and headers of the data to be serialized using
-    // any temporary or valid instance.
-    worksheet.serialize_headers_with_format(0, 0, &item1, &format)?;
+    // Set up the start location and headers of the data to be serialized.
+    worksheet.deserialize_headers_with_format::<Produce>(0, 0, &format)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_datetime1.rs

@@ -6,7 +6,7 @@
 //! data structure, including datetimes, to a worksheet.
 
 use rust_xlsxwriter::{
-    CustomSerializeHeader, ExcelDateTime, Format, FormatBorder, SerializeHeadersOptions, Workbook,
+    CustomSerializeField, ExcelDateTime, Format, FormatBorder, SerializeFieldOptions, Workbook,
     XlsxError,
 };
 use serde::{Deserialize, Serialize};
@@ -52,13 +52,13 @@ fn main() -> Result<(), XlsxError> {
     // Set up the start location and headers of the data to be serialized. Note,
     // we need to add a cell format for the datetime data.
     let custom_headers = [
-        CustomSerializeHeader::new("name").rename("Student"),
-        CustomSerializeHeader::new("dob")
+        CustomSerializeField::new("name").rename("Student"),
+        CustomSerializeField::new("dob")
             .rename("Birthday")
             .set_value_format(&date_format),
-        CustomSerializeHeader::new("id").rename("ID"),
+        CustomSerializeField::new("id").rename("ID"),
     ];
-    let header_options = SerializeHeadersOptions::new()
+    let header_options = SerializeFieldOptions::new()
         .set_header_format(&header_format)
         .set_custom_headers(&custom_headers);
 

examples/doc_worksheet_serialize_datetime2.rs

@@ -7,7 +7,7 @@
 
 use chrono::NaiveDate;
 use rust_xlsxwriter::{
-    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+    CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError,
 };
 use serde::{Deserialize, Serialize};
 
@@ -58,13 +58,13 @@ fn main() -> Result<(), XlsxError> {
     // Set up the start location and headers of the data to be serialized. Note,
     // we need to add a cell format for the datetime data.
     let custom_headers = [
-        CustomSerializeHeader::new("name").rename("Student"),
-        CustomSerializeHeader::new("dob")
+        CustomSerializeField::new("name").rename("Student"),
+        CustomSerializeField::new("dob")
             .rename("Birthday")
             .set_value_format(&date_format),
-        CustomSerializeHeader::new("id").rename("ID"),
+        CustomSerializeField::new("id").rename("ID"),
     ];
-    let header_options = SerializeHeadersOptions::new()
+    let header_options = SerializeFieldOptions::new()
         .set_header_format(&header_format)
         .set_custom_headers(&custom_headers);
 

examples/doc_worksheet_serialize_datetime4.rs

@@ -7,7 +7,7 @@
 
 use chrono::NaiveDate;
 use rust_xlsxwriter::{
-    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+    CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError,
 };
 use serde::Serialize;
 
@@ -58,13 +58,13 @@ fn main() -> Result<(), XlsxError> {
     // Set up the start location and headers of the data to be serialized. Note,
     // we need to add a cell format for the datetime data.
     let custom_headers = [
-        CustomSerializeHeader::new("name").rename("Student"),
-        CustomSerializeHeader::new("dob")
+        CustomSerializeField::new("name").rename("Student"),
+        CustomSerializeField::new("dob")
             .rename("Birthday")
             .set_value_format(&date_format),
-        CustomSerializeHeader::new("id").rename("ID"),
+        CustomSerializeField::new("id").rename("ID"),
     ];
-    let header_options = SerializeHeadersOptions::new()
+    let header_options = SerializeFieldOptions::new()
         .set_header_format(&header_format)
         .set_custom_headers(&custom_headers);
 

examples/doc_worksheet_serialize_headers1.rs

@@ -17,24 +17,33 @@ fn main() -> Result<(), XlsxError> {
     // Create a serializable struct.
     #[derive(Serialize)]
     #[serde(rename_all = "PascalCase")]
-    struct Student<'a> {
-        name: &'a str,
-        age: u8,
-        id: u32,
+    struct Produce {
+        fruit: &'static str,
+        cost: f64,
     }
 
-    let student = Student {
-        name: "Aoife",
-        age: 25,
-        id: 564351,
+    // Create some data instances.
+    let item1 = Produce {
+        fruit: "Peach",
+        cost: 1.05,
+    };
+    let item2 = Produce {
+        fruit: "Plum",
+        cost: 0.15,
+    };
+    let item3 = Produce {
+        fruit: "Pear",
+        cost: 0.75,
     };
 
     // Set up the start location and headers of the data to be serialized using
     // any temporary or valid instance.
-    worksheet.serialize_headers(2, 4, &student)?;
+    worksheet.serialize_headers(0, 0, &item1)?;
 
     // Serialize the data.
-    worksheet.serialize(&student)?;
+    worksheet.serialize(&item1)?;
+    worksheet.serialize(&item2)?;
+    worksheet.serialize(&item3)?;
 
     // Save the file.
     workbook.save("serialize.xlsx")?;

examples/doc_worksheet_serialize_headers3.rs

@@ -7,7 +7,7 @@
 //! and deserialization).
 
 use rust_xlsxwriter::{
-    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+    CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError,
 };
 use serde::{Deserialize, Serialize};
 
@@ -73,12 +73,12 @@ fn main() -> Result<(), XlsxError> {
     //    the customization to set the header format and also the cell format
     //    for the number values.
     let custom_headers = [
-        CustomSerializeHeader::new("fruit").rename("Item"),
-        CustomSerializeHeader::new("cost")
+        CustomSerializeField::new("fruit").rename("Item"),
+        CustomSerializeField::new("cost")
             .rename("Price")
             .set_value_format(&currency_format),
     ];
-    let header_options = SerializeHeadersOptions::new()
+    let header_options = SerializeFieldOptions::new()
         .set_header_format(&header_format)
         .set_custom_headers(&custom_headers);
 
@@ -91,7 +91,7 @@ fn main() -> Result<(), XlsxError> {
 
     // 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);
+    let header_options = SerializeFieldOptions::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_headers4.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.
+
+use rust_xlsxwriter::{Format, Workbook, XlsxError};
+use serde::Serialize;
+
+fn main() -> Result<(), XlsxError> {
+    let mut workbook = Workbook::new();
+
+    // Add a worksheet to the workbook.
+    let worksheet = workbook.add_worksheet();
+
+    // Add a simple format for the headers.
+    let format = Format::new().set_bold();
+
+    // Create a serializable struct.
+    #[derive(Serialize)]
+    #[serde(rename_all = "PascalCase")]
+    struct Produce {
+        fruit: &'static str,
+        cost: f64,
+    }
+
+    // Create some data instances.
+    let item1 = Produce {
+        fruit: "Peach",
+        cost: 1.05,
+    };
+    let item2 = Produce {
+        fruit: "Plum",
+        cost: 0.15,
+    };
+    let item3 = Produce {
+        fruit: "Pear",
+        cost: 0.75,
+    };
+
+    // Set up the start location and headers of the data to be serialized using
+    // any temporary or valid instance.
+    worksheet.serialize_headers_with_format(0, 0, &item1, &format)?;
+
+    // Serialize the data.
+    worksheet.serialize(&item1)?;
+    worksheet.serialize(&item2)?;
+    worksheet.serialize(&item3)?;
+
+    // Save the file.
+    workbook.save("serialize.xlsx")?;
+
+    Ok(())
+}

examples/doc_worksheet_serialize_headers_custom.rs

@@ -6,7 +6,7 @@
 //! data structure to a worksheet with custom headers and cell formatting.
 
 use rust_xlsxwriter::{
-    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+    CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError,
 };
 use serde::{Deserialize, Serialize};
 
@@ -49,13 +49,13 @@ fn main() -> Result<(), XlsxError> {
 
     // Set up the custom headers.
     let custom_headers = [
-        CustomSerializeHeader::new("fruit").rename("Item"),
-        CustomSerializeHeader::new("cost")
+        CustomSerializeField::new("fruit").rename("Item"),
+        CustomSerializeField::new("cost")
             .rename("Price")
             .set_value_format(&currency_format),
     ];
 
-    let header_options = SerializeHeadersOptions::new()
+    let header_options = SerializeFieldOptions::new()
         .set_header_format(&header_format)
         .set_custom_headers(&custom_headers);
 

examples/doc_worksheet_serialize_headers_format2.rs

@@ -4,7 +4,7 @@
 
 //! The following example demonstrates formatting headers during serialization.
 //!
-use rust_xlsxwriter::{Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError};
+use rust_xlsxwriter::{Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -43,7 +43,7 @@ fn main() -> Result<(), XlsxError> {
     };
 
     // Set the serialization location and headers.
-    let header_options = SerializeHeadersOptions::new().set_header_format(&header_format);
+    let header_options = SerializeFieldOptions::new().set_header_format(&header_format);
 
     worksheet.serialize_headers_with_options(1, 1, &item1, &header_options)?;