serde: refactored serialization options examples

Feature request: #63

.github/workflows/rust_resave_tests.yml

@@ -18,4 +18,4 @@ jobs:
     - uses: actions/checkout@v3
 
     - name: Run the tests for the resave feature set
-      run: cargo test --features test-resave --test '*'
+      run: cargo test --features test-resave

.github/workflows/rust_serde_chrono_tests.yml

@@ -18,4 +18,4 @@ jobs:
     - uses: actions/checkout@v3
 
     - name: Run the tests for the serde feature set
-      run: cargo test --features serde --features chrono --test '*'
+      run: cargo test --features serde --features chrono

.github/workflows/rust_serde_tests.yml

@@ -18,4 +18,4 @@ jobs:
     - uses: actions/checkout@v3
 
     - name: Run the tests for the serde feature set
-      run: cargo test --features serde --test '*'
+      run: cargo test --features serde

.github/workflows/rust_wasm_tests.yml

@@ -18,4 +18,4 @@ jobs:
     - uses: actions/checkout@v3
 
     - name: Run the tests for the wasm feature set
-      run: cargo test --features wasm --test '*'
+      run: cargo test --features wasm

examples/doc_worksheet_serialize_datetime1.rs

@@ -6,7 +6,8 @@
 //! data structure, including datetimes, to a worksheet.
 
 use rust_xlsxwriter::{
-    CustomSerializeHeader, ExcelDateTime, Format, FormatBorder, Workbook, XlsxError,
+    CustomSerializeHeader, ExcelDateTime, Format, FormatBorder, SerializeHeadersOptions, Workbook,
+    XlsxError,
 };
 use serde::Serialize;
 
@@ -51,19 +52,17 @@ 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")
-            .set_header_format(&header_format),
+        CustomSerializeHeader::new("name").rename("Student"),
         CustomSerializeHeader::new("dob")
             .rename("Birthday")
-            .set_cell_format(&date_format)
-            .set_header_format(&header_format),
-        CustomSerializeHeader::new("id")
-            .rename("ID")
-            .set_header_format(&header_format),
+            .set_cell_format(&date_format),
+        CustomSerializeHeader::new("id").rename("ID"),
     ];
+    let header_options = SerializeHeadersOptions::new()
+        .set_header_format(&header_format)
+        .set_custom_headers(&custom_headers);
 
-    worksheet.serialize_headers_with_options(0, 0, "Student", &custom_headers)?;
+    worksheet.serialize_headers_with_options(0, 0, &students[0], &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&students)?;

examples/doc_worksheet_serialize_datetime2.rs

@@ -6,7 +6,9 @@
 //! data structure, including chrono datetimes, to a worksheet.
 
 use chrono::NaiveDate;
-use rust_xlsxwriter::{CustomSerializeHeader, Format, FormatBorder, Workbook, XlsxError};
+use rust_xlsxwriter::{
+    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+};
 use serde::Serialize;
 
 use rust_xlsxwriter::utility::serialize_chrono_naive_to_excel;
@@ -56,19 +58,18 @@ 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")
-            .set_header_format(&header_format),
+        CustomSerializeHeader::new("name").rename("Student"),
         CustomSerializeHeader::new("dob")
             .rename("Birthday")
-            .set_cell_format(&date_format)
-            .set_header_format(&header_format),
-        CustomSerializeHeader::new("id")
-            .rename("ID")
-            .set_header_format(&header_format),
+            .set_cell_format(&date_format),
+        CustomSerializeHeader::new("id").rename("ID"),
     ];
+    let header_options = SerializeHeadersOptions::new()
+        .set_header_format(&header_format)
+        .set_custom_headers(&custom_headers);
 
-    worksheet.serialize_headers_with_options(0, 0, "Student", &custom_headers)?;
+    // Set the serialization location and custom headers.
+    worksheet.serialize_headers_with_options(0, 0, &students[0], &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&students)?;

examples/doc_worksheet_serialize_datetime4.rs

@@ -6,7 +6,9 @@
 //! data structure, including `Option` chrono datetimes, to a worksheet.
 
 use chrono::NaiveDate;
-use rust_xlsxwriter::{CustomSerializeHeader, Format, FormatBorder, Workbook, XlsxError};
+use rust_xlsxwriter::{
+    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+};
 use serde::Serialize;
 
 use rust_xlsxwriter::utility::serialize_chrono_option_naive_to_excel;
@@ -56,19 +58,17 @@ 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")
-            .set_header_format(&header_format),
+        CustomSerializeHeader::new("name").rename("Student"),
         CustomSerializeHeader::new("dob")
             .rename("Birthday")
-            .set_cell_format(&date_format)
-            .set_header_format(&header_format),
-        CustomSerializeHeader::new("id")
-            .rename("ID")
-            .set_header_format(&header_format),
+            .set_cell_format(&date_format),
+        CustomSerializeHeader::new("id").rename("ID"),
     ];
+    let header_options = SerializeHeadersOptions::new()
+        .set_header_format(&header_format)
+        .set_custom_headers(&custom_headers);
 
-    worksheet.serialize_headers_with_options(0, 0, "Student", &custom_headers)?;
+    worksheet.serialize_headers_with_options(0, 0, &students[0], &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&students)?;

examples/doc_worksheet_serialize_headers3.rs

@@ -5,7 +5,9 @@
 //! The following example demonstrates serializing instances of a Serde derived
 //! data structure to a worksheet using different methods.
 
-use rust_xlsxwriter::{CustomSerializeHeader, Format, FormatBorder, Workbook, XlsxError};
+use rust_xlsxwriter::{
+    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -53,13 +55,15 @@ fn main() -> Result<(), XlsxError> {
     // 1. Set the serialization location and headers with `serialize_headers()`
     //    and serialize some data.
     worksheet.serialize_headers(0, 0, &item1)?;
+
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
     worksheet.serialize(&item3)?;
 
     // 2. Set the serialization location and formatted headers with
     //    `serialize_headers_with_format()` and serialize some data.
     worksheet.serialize_headers_with_format(0, 3, &item1, &header_format)?;
+
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
     worksheet.serialize(&item3)?;
@@ -68,28 +72,31 @@ 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")
-            .set_header_format(&header_format),
+        CustomSerializeHeader::new("fruit").rename("Item"),
         CustomSerializeHeader::new("cost")
             .rename("Price")
-            .set_header_format(&header_format)
             .set_cell_format(&currency_format),
     ];
+    let header_options = SerializeHeadersOptions::new()
+        .set_header_format(&header_format)
+        .set_custom_headers(&custom_headers);
+
+    // Set the serialization location and custom headers.
+    worksheet.serialize_headers_with_options(0, 6, &item1, &header_options)?;
 
-    worksheet.serialize_headers_with_options(0, 6, "Produce", &custom_headers)?;
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
     worksheet.serialize(&item3)?;
 
     // 4. Set the serialization location and headers with custom headers. We use
     //    the customization to turn off the headers.
-    let custom_headers = [
-        CustomSerializeHeader::new("fruit").hide_headers(true),
-        CustomSerializeHeader::new("cost"),
-    ];
+    let header_options = SerializeHeadersOptions::new()
+        .hide_headers(true)
+        .set_custom_headers(&custom_headers);
+
+    // Set the serialization location and custom headers.
+    worksheet.serialize_headers_with_options(0, 9, &item1, &header_options)?;
 
-    worksheet.serialize_headers_with_options(0, 9, "Produce", &custom_headers)?;
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;
     worksheet.serialize(&item3)?;

examples/doc_worksheet_serialize_headers_custom.rs

@@ -5,7 +5,9 @@
 //! The following example demonstrates serializing instances of a Serde derived
 //! data structure to a worksheet with custom headers and cell formatting.
 
-use rust_xlsxwriter::{CustomSerializeHeader, Format, FormatBorder, Workbook, XlsxError};
+use rust_xlsxwriter::{
+    CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError,
+};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -47,17 +49,19 @@ fn main() -> Result<(), XlsxError> {
 
     // Set up the custom headers.
     let custom_headers = [
-        CustomSerializeHeader::new("fruit")
-            .rename("Item")
-            .set_header_format(&header_format),
+        CustomSerializeHeader::new("fruit").rename("Item"),
         CustomSerializeHeader::new("cost")
             .rename("Price")
-            .set_header_format(&header_format)
             .set_cell_format(&currency_format),
     ];
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(1, 1, "Produce", &custom_headers)?;
+    let header_options = SerializeHeadersOptions::new()
+        .set_header_format(&header_format)
+        .set_custom_headers(&custom_headers);
+
+    // Set the serialization location and custom headers.
+    worksheet.serialize_headers_with_options(1, 1, &item1, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_format2.rs

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

examples/doc_worksheet_serialize_headers_format3.rs

@@ -4,7 +4,9 @@
 
 //! The following example demonstrates formatting cells during serialization.
 //!
-use rust_xlsxwriter::{CustomSerializeHeader, Format, Workbook, XlsxError};
+use rust_xlsxwriter::{
+    CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError,
+};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -40,12 +42,11 @@ fn main() -> Result<(), XlsxError> {
     };
 
     // Set the serialization location and headers.
-    let custom_headers = [
-        CustomSerializeHeader::new("fruit"),
-        CustomSerializeHeader::new("cost").set_cell_format(&cell_format),
-    ];
+    let custom_headers = [CustomSerializeHeader::new("cost").set_cell_format(&cell_format)];
+    let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers);
 
-    worksheet.serialize_headers_with_options(0, 0, "Produce", &custom_headers)?;
+    // Set the serialization location and custom headers.
+    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_hide.rs

@@ -5,7 +5,7 @@
 //! The following example demonstrates serializing data without outputting the
 //! headers above the data.
 //!
-use rust_xlsxwriter::{CustomSerializeHeader, Workbook, XlsxError};
+use rust_xlsxwriter::{SerializeHeadersOptions, Workbook, XlsxError};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -37,14 +37,11 @@ fn main() -> Result<(), XlsxError> {
         cost: 0.75,
     };
 
-    // Set up the custom headers.
-    let custom_headers = [
-        CustomSerializeHeader::new("fruit").hide_headers(true),
-        CustomSerializeHeader::new("cost"),
-    ];
+    // Set up the headers options.
+    let header_options = SerializeHeadersOptions::new().hide_headers(true);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, "Produce", &custom_headers)?;
+    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_rename2.rs

@@ -6,7 +6,7 @@
 //! specifying custom headers and renaming them there. You must still specify
 //! the actual field name to serialize in the `new()` constructor.
 //!
-use rust_xlsxwriter::{CustomSerializeHeader, Workbook, XlsxError};
+use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -43,9 +43,10 @@ fn main() -> Result<(), XlsxError> {
         CustomSerializeHeader::new("fruit").rename("Item"),
         CustomSerializeHeader::new("cost").rename("Price"),
     ];
+    let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, "Produce", &custom_headers)?;
+    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_skip2.rs

@@ -6,7 +6,7 @@
 //! omitting them from the serialization headers. To do this we need to specify
 //! custom headers.
 
-use rust_xlsxwriter::{CustomSerializeHeader, Workbook, XlsxError};
+use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -47,9 +47,12 @@ fn main() -> Result<(), XlsxError> {
         CustomSerializeHeader::new("fruit"),
         CustomSerializeHeader::new("cost"),
     ];
+    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, "Produce", &custom_headers)?;
+    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
 
     // Serialize the data.
     worksheet.serialize(&item1)?;

examples/doc_worksheet_serialize_headers_skip3.rs

@@ -5,7 +5,7 @@
 //! The following example demonstrates skipping fields during serialization by
 //! explicitly skipping them via custom headers.
 
-use rust_xlsxwriter::{CustomSerializeHeader, Workbook, XlsxError};
+use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError};
 use serde::Serialize;
 
 fn main() -> Result<(), XlsxError> {
@@ -47,10 +47,10 @@ fn main() -> Result<(), XlsxError> {
         CustomSerializeHeader::new("cost"),
         CustomSerializeHeader::new("in_stock").skip(true),
     ];
+    let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers);
 
     // Set the serialization location and custom headers.
-    worksheet.serialize_headers_with_options(0, 0, "Produce", &custom_headers)?;
-
+    worksheet.serialize_headers_with_options(0, 0, &item1, &header_options)?;
     // Serialize the data.
     worksheet.serialize(&item1)?;
     worksheet.serialize(&item2)?;