diff --git a/Cargo.toml b/Cargo.toml index 1793f06c..29caba79 100644 --- a/Cargo.toml +++ b/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" diff --git a/examples/doc_worksheet_deserialize_headers1.rs b/examples/doc_worksheet_deserialize_headers1.rs new file mode 100644 index 00000000..1364c380 --- /dev/null +++ b/examples/doc_worksheet_deserialize_headers1.rs @@ -0,0 +1,51 @@ +// SPDX-License-Identifier: MIT OR Apache-2.0 +// +// Copyright 2022-2023, John McNamara, jmcnamara@cpan.org + +//! 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::(0, 0)?; + + // Serialize the data. + worksheet.serialize(&item1)?; + worksheet.serialize(&item2)?; + worksheet.serialize(&item3)?; + + // Save the file. + workbook.save("serialize.xlsx")?; + + Ok(()) +} diff --git a/examples/doc_worksheet_serialize.rs b/examples/doc_worksheet_serialize.rs index c930881d..e223dcb1 100644 --- a/examples/doc_worksheet_serialize.rs +++ b/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::(0, 0, &format)?; // Serialize the data. worksheet.serialize(&item1)?; diff --git a/examples/doc_worksheet_serialize_datetime1.rs b/examples/doc_worksheet_serialize_datetime1.rs index b81d29bf..f2cddb83 100644 --- a/examples/doc_worksheet_serialize_datetime1.rs +++ b/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); diff --git a/examples/doc_worksheet_serialize_datetime2.rs b/examples/doc_worksheet_serialize_datetime2.rs index 79a18b8c..0b933dbf 100644 --- a/examples/doc_worksheet_serialize_datetime2.rs +++ b/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); diff --git a/examples/doc_worksheet_serialize_datetime4.rs b/examples/doc_worksheet_serialize_datetime4.rs index ddeeefee..5e030c9e 100644 --- a/examples/doc_worksheet_serialize_datetime4.rs +++ b/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); diff --git a/examples/doc_worksheet_serialize_headers1.rs b/examples/doc_worksheet_serialize_headers1.rs index 6a072f29..f23b7cc3 100644 --- a/examples/doc_worksheet_serialize_headers1.rs +++ b/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")?; diff --git a/examples/doc_worksheet_serialize_headers3.rs b/examples/doc_worksheet_serialize_headers3.rs index 47497353..a3a35749 100644 --- a/examples/doc_worksheet_serialize_headers3.rs +++ b/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(¤cy_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)?; diff --git a/examples/doc_worksheet_serialize_headers4.rs b/examples/doc_worksheet_serialize_headers4.rs new file mode 100644 index 00000000..c930881d --- /dev/null +++ b/examples/doc_worksheet_serialize_headers4.rs @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: MIT OR Apache-2.0 +// +// Copyright 2022-2023, John McNamara, jmcnamara@cpan.org + +//! 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(()) +} diff --git a/examples/doc_worksheet_serialize_headers_custom.rs b/examples/doc_worksheet_serialize_headers_custom.rs index d4ba77cf..de9f6853 100644 --- a/examples/doc_worksheet_serialize_headers_custom.rs +++ b/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(¤cy_format), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_header_format(&header_format) .set_custom_headers(&custom_headers); diff --git a/examples/doc_worksheet_serialize_headers_format2.rs b/examples/doc_worksheet_serialize_headers_format2.rs index 001c067e..62064c2e 100644 --- a/examples/doc_worksheet_serialize_headers_format2.rs +++ b/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)?; diff --git a/examples/doc_worksheet_serialize_headers_format3.rs b/examples/doc_worksheet_serialize_headers_format3.rs index a7b9102a..f83607bb 100644 --- a/examples/doc_worksheet_serialize_headers_format3.rs +++ b/examples/doc_worksheet_serialize_headers_format3.rs @@ -4,9 +4,7 @@ //! The following example demonstrates formatting cells during serialization. //! -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -42,8 +40,8 @@ fn main() -> Result<(), XlsxError> { }; // Set the custom headers. - let header_options = SerializeHeadersOptions::new() - .set_custom_headers(&[CustomSerializeHeader::new("cost").set_value_format(&value_format)]); + let header_options = SerializeFieldOptions::new() + .set_custom_headers(&[CustomSerializeField::new("cost").set_value_format(&value_format)]); // Set the serialization location and headers. worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; diff --git a/examples/doc_worksheet_serialize_headers_format5.rs b/examples/doc_worksheet_serialize_headers_format5.rs index 6ed07a64..2bc98858 100644 --- a/examples/doc_worksheet_serialize_headers_format5.rs +++ b/examples/doc_worksheet_serialize_headers_format5.rs @@ -6,7 +6,7 @@ //! data structure to a worksheet with header and column formatting. use rust_xlsxwriter::{ - CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, + CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, }; use serde::{Deserialize, Serialize}; @@ -51,9 +51,9 @@ fn main() -> Result<(), XlsxError> { }; // Set up the custom headers. - let custom_headers = [CustomSerializeHeader::new("Price").set_column_format(¤cy_format)]; + let custom_headers = [CustomSerializeField::new("Price").set_column_format(¤cy_format)]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_header_format(&header_format) .set_custom_headers(&custom_headers); diff --git a/examples/doc_worksheet_serialize_headers_format6.rs b/examples/doc_worksheet_serialize_headers_format6.rs index 677a6266..f1578568 100644 --- a/examples/doc_worksheet_serialize_headers_format6.rs +++ b/examples/doc_worksheet_serialize_headers_format6.rs @@ -6,7 +6,7 @@ //! data structure to a worksheet with header and value formatting. use rust_xlsxwriter::{ - CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, + CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, }; use serde::{Deserialize, Serialize}; @@ -51,9 +51,9 @@ fn main() -> Result<(), XlsxError> { }; // Set the custom headers. - let custom_headers = [CustomSerializeHeader::new("Price").set_value_format(¤cy_format)]; + let custom_headers = [CustomSerializeField::new("Price").set_value_format(¤cy_format)]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_header_format(&header_format) .set_custom_headers(&custom_headers); diff --git a/examples/doc_worksheet_serialize_headers_format7.rs b/examples/doc_worksheet_serialize_headers_format7.rs index d159be4c..728c152f 100644 --- a/examples/doc_worksheet_serialize_headers_format7.rs +++ b/examples/doc_worksheet_serialize_headers_format7.rs @@ -5,7 +5,7 @@ //! The following example demonstrates turning off headers during serialization. //! The example in columns "D:E" have the headers turned off. //! -use rust_xlsxwriter::{SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -42,7 +42,7 @@ fn main() -> Result<(), XlsxError> { worksheet.serialize(&items)?; // Serialize the data but hide headers. - let header_options = SerializeHeadersOptions::new().hide_headers(true); + let header_options = SerializeFieldOptions::new().hide_headers(true); worksheet.deserialize_headers_with_options::(0, 3, &header_options)?; worksheet.serialize(&items)?; diff --git a/examples/doc_worksheet_serialize_headers_format8.rs b/examples/doc_worksheet_serialize_headers_format8.rs index 9d6710b8..6f423c2c 100644 --- a/examples/doc_worksheet_serialize_headers_format8.rs +++ b/examples/doc_worksheet_serialize_headers_format8.rs @@ -6,7 +6,7 @@ //! properties. The user can either merge them with the default properties or //! use the custom properties exclusively. //! -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -45,11 +45,11 @@ fn main() -> Result<(), XlsxError> { // Default handling of customized headers: the formatting is merged with the // default values so "in_stock" is still shown. let custom_headers = [ - CustomSerializeHeader::new("fruit").rename("Item"), - CustomSerializeHeader::new("cost").rename("Price"), - CustomSerializeHeader::new("in_stock").rename("Foo"), + CustomSerializeField::new("fruit").rename("Item"), + CustomSerializeField::new("cost").rename("Price"), + CustomSerializeField::new("in_stock").rename("Foo"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; worksheet.serialize(&items)?; @@ -57,10 +57,10 @@ fn main() -> Result<(), XlsxError> { // Set the "use_custom_headers_only" option to shown only the specified // custom headers. let custom_headers = [ - CustomSerializeHeader::new("fruit").rename("Item"), - CustomSerializeHeader::new("cost").rename("Price"), + CustomSerializeField::new("fruit").rename("Item"), + CustomSerializeField::new("cost").rename("Price"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .use_custom_headers_only(true); @@ -69,10 +69,10 @@ fn main() -> Result<(), XlsxError> { // This can also be used to set the order of the output. let custom_headers = [ - CustomSerializeHeader::new("cost").rename("Price"), - CustomSerializeHeader::new("fruit").rename("Item"), + CustomSerializeField::new("cost").rename("Price"), + CustomSerializeField::new("fruit").rename("Item"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .use_custom_headers_only(true); diff --git a/examples/doc_worksheet_serialize_headers_hide.rs b/examples/doc_worksheet_serialize_headers_hide.rs index a30ebd08..82aa1aec 100644 --- a/examples/doc_worksheet_serialize_headers_hide.rs +++ b/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::{SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; fn main() -> Result<(), XlsxError> { @@ -38,7 +38,7 @@ fn main() -> Result<(), XlsxError> { }; // Set up the headers options. - 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, 0, &item1, &header_options)?; diff --git a/examples/doc_worksheet_serialize_headers_rename2.rs b/examples/doc_worksheet_serialize_headers_rename2.rs index 9be106e0..a2a38b82 100644 --- a/examples/doc_worksheet_serialize_headers_rename2.rs +++ b/examples/doc_worksheet_serialize_headers_rename2.rs @@ -5,7 +5,7 @@ //! The following example demonstrates renaming fields during serialization by //! specifying custom headers and renaming them there. //! -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -39,10 +39,10 @@ fn main() -> Result<(), XlsxError> { // Set up the custom headers. let custom_headers = [ - CustomSerializeHeader::new("fruit").rename("Item"), - CustomSerializeHeader::new("cost").rename("Price"), + CustomSerializeField::new("fruit").rename("Item"), + CustomSerializeField::new("cost").rename("Price"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); // Set the serialization location and custom headers. worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; diff --git a/examples/doc_worksheet_serialize_headers_skip2.rs b/examples/doc_worksheet_serialize_headers_skip2.rs index 449bd26d..b686fcff 100644 --- a/examples/doc_worksheet_serialize_headers_skip2.rs +++ b/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 and set `use_custom_headers_only()`. -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -44,13 +44,13 @@ fn main() -> Result<(), XlsxError> { // Only set up the custom headers we want and omit "in_stock". let custom_headers = [ - CustomSerializeHeader::new("fruit"), - CustomSerializeHeader::new("cost"), + CustomSerializeField::new("fruit"), + CustomSerializeField::new("cost"), ]; // Note the use of "use_custom_headers_only" to only serialize the named // custom headers. - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .use_custom_headers_only(true) .set_custom_headers(&custom_headers); diff --git a/examples/doc_worksheet_serialize_headers_skip3.rs b/examples/doc_worksheet_serialize_headers_skip3.rs index 36a2add3..b63e1555 100644 --- a/examples/doc_worksheet_serialize_headers_skip3.rs +++ b/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, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; fn main() -> Result<(), XlsxError> { @@ -42,8 +42,8 @@ fn main() -> Result<(), XlsxError> { }; // 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)]); + let header_options = SerializeFieldOptions::new() + .set_custom_headers(&[CustomSerializeField::new("in_stock").skip(true)]); // Set the serialization location and custom headers. worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; diff --git a/examples/doc_worksheet_serialize_headers_with_options.rs b/examples/doc_worksheet_serialize_headers_with_options.rs index d2a50243..57063392 100644 --- a/examples/doc_worksheet_serialize_headers_with_options.rs +++ b/examples/doc_worksheet_serialize_headers_with_options.rs @@ -5,9 +5,7 @@ //! The following example demonstrates serializing instances of a Serde derived //! data structure to a worksheet. -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; fn main() -> Result<(), XlsxError> { @@ -46,12 +44,12 @@ fn main() -> Result<(), XlsxError> { // Set up the start location and headers of the data to be serialized using // custom headers. let custom_headers = [ - CustomSerializeHeader::new("fruit").rename("Fruit"), - CustomSerializeHeader::new("cost") + CustomSerializeField::new("fruit").rename("Fruit"), + CustomSerializeField::new("cost") .rename("Price") .set_value_format(¤cy), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_header_format(&bold) .set_custom_headers(&custom_headers); diff --git a/examples/doc_worksheet_serialize_headers_with_options2.rs b/examples/doc_worksheet_serialize_headers_with_options2.rs new file mode 100644 index 00000000..6037583e --- /dev/null +++ b/examples/doc_worksheet_serialize_headers_with_options2.rs @@ -0,0 +1,65 @@ +// SPDX-License-Identifier: MIT OR Apache-2.0 +// +// Copyright 2022-2023, John McNamara, jmcnamara@cpan.org + +//! The following example demonstrates serializing instances of a Serde derived +//! data structure to a worksheet. + +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, 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 bold = Format::new().set_bold(); + let currency = Format::new().set_num_format("$0.00"); + + // Create a serializable struct. + #[derive(Deserialize, Serialize)] + struct Produce { + fruit: &'static str, + cost: f64, + } + + // Create some data instances. + let items = [ + Produce { + fruit: "Peach", + cost: 1.05, + }, + Produce { + fruit: "Plum", + cost: 0.15, + }, + Produce { + fruit: "Pear", + cost: 0.75, + }, + ]; + + // Set up the start location and headers of the data to be serialized using + // custom headers. + let custom_headers = [ + CustomSerializeField::new("fruit").rename("Fruit"), + CustomSerializeField::new("cost") + .rename("Price") + .set_value_format(¤cy), + ]; + let header_options = SerializeFieldOptions::new() + .set_header_format(&bold) + .set_custom_headers(&custom_headers); + + worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; + + // Serialize the data. + worksheet.serialize(&items)?; + + // Save the file. + workbook.save("serialize.xlsx")?; + + Ok(()) +} diff --git a/src/serializer.rs b/src/serializer.rs index aa9af7a7..ef83374e 100644 --- a/src/serializer.rs +++ b/src/serializer.rs @@ -129,7 +129,7 @@ //! //! When serializing structs `rust_xlsxwriter` needs to know location where the //! serialization starts and also the type and field names of the struct being -//! serialized. Th field names are used as headers and the type name allows for +//! serialized. The field names are used as headers and the type name allows for //! several distinct structs to be serialized to the same worksheet. //! //! The worksheet methods that perform this function fall into two types: @@ -151,7 +151,7 @@ //! //! - [`Worksheet::deserialize_headers_with_options()`]: Similar to the previous //! methods but also allows configuration of the headers and fields via -//! [`SerializeHeadersOptions`]. +//! [`SerializeFieldOptions`]. //! //! - [`Worksheet::serialize_headers()`]: Similar to the `deserialize_headers()` //! method but it requires a concrete instance of the type of struct that you @@ -164,7 +164,7 @@ //! //! - [`Worksheet::serialize_headers_with_options()`]: Similar to the previous //! methods but also allows configuration of the headers and fields via -//! [`SerializeHeadersOptions`]. +//! [`SerializeFieldOptions`]. //! //! The example below shows the usage of some of these methods. //! @@ -172,7 +172,7 @@ //! # // This code is available in examples/doc_worksheet_serialize_headers3.rs //! # //! use rust_xlsxwriter::{ -//! CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, +//! CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, //! }; //! use serde::{Deserialize, Serialize}; //! @@ -238,12 +238,12 @@ //! // the customization to set the header format and also rename 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(¤cy_format), //! ]; -//! let header_options = SerializeHeadersOptions::new() +//! let header_options = SerializeFieldOptions::new() //! .set_header_format(&header_format) //! .set_custom_headers(&custom_headers); //! @@ -256,7 +256,7 @@ //! //! // 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)?; @@ -297,7 +297,7 @@ //! 2. Rename the header (not field) when setting up custom serialization //! headers via [`Worksheet::deserialize_headers_with_options()`] or //! [`Worksheet::serialize_headers_with_options()`] and -//! [`CustomSerializeHeader::rename()`]. +//! [`CustomSerializeField::rename()`]. //! //! [field attribute]: https://serde.rs/field-attrs.html //! [container attribute]: https://serde.rs/container-attrs.html @@ -376,7 +376,7 @@ //! ```rust //! # // This code is available in examples/doc_worksheet_serialize_headers_rename2.rs //! # -//! # use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +//! # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; //! # use serde::{Deserialize, Serialize}; //! # //! # fn main() -> Result<(), XlsxError> { @@ -410,10 +410,10 @@ //! //! // Set up the custom headers. //! let custom_headers = [ -//! CustomSerializeHeader::new("fruit").rename("Item"), -//! CustomSerializeHeader::new("cost").rename("Price"), +//! CustomSerializeField::new("fruit").rename("Item"), +//! CustomSerializeField::new("cost").rename("Price"), //! ]; -//! let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); +//! let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); //! //! // Set the serialization location and custom headers. //! worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; @@ -450,7 +450,7 @@ //! This method is useful when you can't add any additional attributes on the //! struct. //! 3. Marking the field as skippable via custom headers and the -//! [`CustomSerializeHeader::skip()`] method. This is only required in a few +//! [`CustomSerializeField::skip()`] method. This is only required in a few //! edge cases where the previous methods won't work. //! //! [field attributes]: https://serde.rs/field-attrs.html @@ -531,13 +531,13 @@ //! The following example demonstrates skipping fields during serialization by //! omitting them from the serialization headers. To do this we need to specify //! custom headers and set -//! [`SerializeHeadersOptions::use_custom_headers_only()`]. The output is the +//! [`SerializeFieldOptions::use_custom_headers_only()`]. The output is the //! same as the image above. //! //! ```rust //! # // This code is available in examples/doc_worksheet_serialize_headers_skip2.rs //! # -//! # use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +//! # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; //! # use serde::{Deserialize, Serialize}; //! # //! # fn main() -> Result<(), XlsxError> { @@ -575,13 +575,13 @@ //! //! // Set up only the custom headers we want and omit "in_stock". //! let custom_headers = [ -//! CustomSerializeHeader::new("fruit"), -//! CustomSerializeHeader::new("cost"), +//! CustomSerializeField::new("fruit"), +//! CustomSerializeField::new("cost"), //! ]; //! //! // Note the use of "use_custom_headers_only" to only serialize the named //! // custom headers. -//! let header_options = SerializeHeadersOptions::new() +//! let header_options = SerializeFieldOptions::new() //! .use_custom_headers_only(true) //! .set_custom_headers(&custom_headers); //! @@ -608,7 +608,7 @@ //! ```rust //! # // This code is available in examples/doc_worksheet_serialize_headers_skip3.rs //! # -//! # use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +//! # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; //! # use serde::{Deserialize, Serialize}; //! # //! # fn main() -> Result<(), XlsxError> { @@ -645,8 +645,8 @@ //! # }; //! # //! // 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)]); +//! let header_options = SerializeFieldOptions::new() +//! .set_custom_headers(&[CustomSerializeField::new("in_stock").skip(true)]); //! //! // Set the serialization location and custom headers. //! worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; @@ -684,11 +684,11 @@ //! There are a few ways of formatting the values for a field: //! //! - Use [`Worksheet::set_column_format()`] to format the entire column. -//! - Use [`CustomSerializeHeader::set_column_format()`] to format the entire +//! - Use [`CustomSerializeField::set_column_format()`] to format the entire //! column. This is the same as the worksheet method but it has the advantage //! of having the column number calculated automatically based on the field //! name. -//! - Use [`CustomSerializeHeader::set_value_format()`] to format just the +//! - Use [`CustomSerializeField::set_value_format()`] to format just the //! serialized data (and not the entire column). //! //! Examples of each are shown below. @@ -770,14 +770,14 @@ //! //! The following variation on the example demonstrates setting formatting via //! custom headers. This produces the same output as the previous example but -//! doesn't require you to manually, or programattically, calculate the column +//! doesn't require you to manually, or programmatically, calculate the column //! number. //! //! ```rust //! # // This code is available in examples/doc_worksheet_serialize_headers_format5.rs //! # //! # use rust_xlsxwriter::{ -//! # CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, +//! # CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, //! # }; //! # use serde::{Deserialize, Serialize}; //! # @@ -823,9 +823,9 @@ //! # //! // Set up the custom headers. //! let custom_headers = -//! [CustomSerializeHeader::new("Price").set_column_format(¤cy_format)]; +//! [CustomSerializeField::new("Price").set_column_format(¤cy_format)]; //! -//! let header_options = SerializeHeadersOptions::new() +//! let header_options = SerializeFieldOptions::new() //! .set_header_format(&header_format) //! .set_custom_headers(&custom_headers); //! @@ -853,7 +853,7 @@ //! # // This code is available in examples/doc_worksheet_serialize_headers_format6.rs //! # //! # use rust_xlsxwriter::{ -//! # CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, +//! # CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, //! # }; //! # use serde::{Deserialize, Serialize}; //! # @@ -899,9 +899,9 @@ //! # //! // Set up the custom headers. //! let custom_headers = -//! [CustomSerializeHeader::new("Price").set_value_format(¤cy_format)]; +//! [CustomSerializeField::new("Price").set_value_format(¤cy_format)]; //! -//! let header_options = SerializeHeadersOptions::new() +//! let header_options = SerializeFieldOptions::new() //! .set_header_format(&header_format) //! .set_custom_headers(&custom_headers); //! @@ -967,8 +967,8 @@ //! # // This code is available in examples/doc_worksheet_serialize_datetime1.rs //! # //! use rust_xlsxwriter::{ -//! CustomSerializeHeader, ExcelDateTime, Format, FormatBorder, -//! SerializeHeadersOptions, Workbook, XlsxError, +//! CustomSerializeField, ExcelDateTime, Format, FormatBorder, +//! SerializeFieldOptions, Workbook, XlsxError, //! }; //! use serde::{Deserialize, Serialize}; //! @@ -1013,13 +1013,13 @@ //! // 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); //! @@ -1093,13 +1093,13 @@ //! # // 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); //! # @@ -1164,7 +1164,7 @@ use serde::{ser, Deserialize, Deserializer, Serialize}; // information in the serializer. // ----------------------------------------------------------------------- pub(crate) struct SerializerState { - pub(crate) structs: HashMap>, + pub(crate) structs: HashMap>, pub(crate) current_struct: String, pub(crate) current_field: String, pub(crate) current_row: RowNum, @@ -1205,16 +1205,16 @@ impl SerializerState { } // ----------------------------------------------------------------------- -// SerializeHeadersOptions. +// SerializeFieldOptions. // ----------------------------------------------------------------------- -/// The `SerializeHeadersOptions` struct represents custom field/header options. +/// The `SerializeFieldOptions` struct represents custom field/header options. /// -/// `SerializeHeadersOptions` can be used to set column headers to map serialized +/// `SerializeFieldOptions` can be used to set column headers to map serialized /// data to. It allows you to reorder, rename, format or skip headers and also /// define formatting for field values. /// -/// It is used in conjunction with the [`CustomSerializeHeader`] struct and +/// It is used in conjunction with the [`CustomSerializeField`] struct and /// [`Worksheet::deserialize_headers_with_options()`] and /// [`Worksheet::serialize_headers_with_options()`] methods. /// @@ -1230,7 +1230,7 @@ impl SerializerState { /// # // This code is available in examples/doc_worksheet_serialize_headers_custom.rs /// # /// # use rust_xlsxwriter::{ -/// # CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, +/// # CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, /// # }; /// # use serde::{Deserialize, Serialize}; /// # @@ -1273,14 +1273,14 @@ impl SerializerState { /// /// // Set up the custom headers. /// let custom_headers = [ -/// CustomSerializeHeader::new("fruit") +/// CustomSerializeField::new("fruit") /// .rename("Item"), -/// CustomSerializeHeader::new("cost") +/// CustomSerializeField::new("cost") /// .rename("Price") /// .set_value_format(¤cy_format), /// ]; /// -/// let header_options = SerializeHeadersOptions::new() +/// let header_options = SerializeFieldOptions::new() /// .set_header_format(&header_format) /// .set_custom_headers(&custom_headers); /// @@ -1305,24 +1305,24 @@ impl SerializerState { /// #[derive(Clone)] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] -pub struct SerializeHeadersOptions { +pub struct SerializeFieldOptions { pub(crate) struct_name: String, pub(crate) header_format: Option, pub(crate) hide_headers: bool, - pub(crate) custom_headers: Vec, + pub(crate) custom_headers: Vec, pub(crate) use_custom_headers_only: bool, } -impl Default for SerializeHeadersOptions { +impl Default for SerializeFieldOptions { fn default() -> Self { Self::new() } } -impl SerializeHeadersOptions { +impl SerializeFieldOptions { /// Create serialization header options. /// - /// Create a `SerializeHeadersOptions` struct to be used with the + /// Create a `SerializeFieldOptions` struct to be used with the /// [`Worksheet::deserialize_headers_with_options()`] or /// [`Worksheet::serialize_headers_with_options()`] methods. /// @@ -1330,8 +1330,8 @@ impl SerializeHeadersOptions { /// column and field specific formatting. /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn new() -> SerializeHeadersOptions { - SerializeHeadersOptions { + pub fn new() -> SerializeFieldOptions { + SerializeFieldOptions { struct_name: String::new(), header_format: None, hide_headers: false, @@ -1357,7 +1357,7 @@ impl SerializeHeadersOptions { /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers_format2.rs /// # - /// # use rust_xlsxwriter::{Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError}; + /// # use rust_xlsxwriter::{Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError}; /// # use serde::Serialize; /// # /// # fn main() -> Result<(), XlsxError> { @@ -1396,7 +1396,7 @@ impl SerializeHeadersOptions { /// }; /// /// // 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)?; /// @@ -1418,7 +1418,7 @@ impl SerializeHeadersOptions { /// /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn set_header_format(mut self, format: impl Into) -> SerializeHeadersOptions { + pub fn set_header_format(mut self, format: impl Into) -> SerializeFieldOptions { self.header_format = Some(format.into()); self } @@ -1442,7 +1442,7 @@ impl SerializeHeadersOptions { /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers_format7.rs /// # - /// # use rust_xlsxwriter::{SerializeHeadersOptions, Workbook, XlsxError}; + /// # use rust_xlsxwriter::{SerializeFieldOptions, Workbook, XlsxError}; /// # use serde::{Deserialize, Serialize}; /// # /// # fn main() -> Result<(), XlsxError> { @@ -1479,7 +1479,7 @@ impl SerializeHeadersOptions { /// worksheet.serialize(&items)?; /// /// // Serialize the data but hide headers. - /// let header_options = SerializeHeadersOptions::new().hide_headers(true); + /// let header_options = SerializeFieldOptions::new().hide_headers(true); /// /// worksheet.deserialize_headers_with_options::(0, 3, &header_options)?; /// worksheet.serialize(&items)?; @@ -1497,7 +1497,7 @@ impl SerializeHeadersOptions { /// /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn hide_headers(mut self, enable: bool) -> SerializeHeadersOptions { + pub fn hide_headers(mut self, enable: bool) -> SerializeFieldOptions { self.hide_headers = enable; self } @@ -1508,11 +1508,11 @@ impl SerializeHeadersOptions { /// individual fields. It allows you to rename field headers, set /// formatting for serialized values, set the column width and other properties. /// - /// See [`CustomSerializeHeader`] for more details. + /// See [`CustomSerializeField`] for more details. /// /// # Parameters /// - /// * `custom_headers` - An array of [`CustomSerializeHeader`] values. + /// * `custom_headers` - An array of [`CustomSerializeField`] values. /// /// # Examples /// @@ -1524,7 +1524,7 @@ impl SerializeHeadersOptions { /// # // This code is available in examples/doc_worksheet_serialize_headers_custom.rs /// # /// # use rust_xlsxwriter::{ - /// # CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, + /// # CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, /// # }; /// # use serde::{Deserialize, Serialize}; /// # @@ -1567,14 +1567,14 @@ impl SerializeHeadersOptions { /// /// // Set up the custom headers. /// let custom_headers = [ - /// CustomSerializeHeader::new("fruit") + /// CustomSerializeField::new("fruit") /// .rename("Item"), - /// CustomSerializeHeader::new("cost") + /// CustomSerializeField::new("cost") /// .rename("Price") /// .set_value_format(¤cy_format), /// ]; /// - /// let header_options = SerializeHeadersOptions::new() + /// let header_options = SerializeFieldOptions::new() /// .set_header_format(&header_format) /// .set_custom_headers(&custom_headers); /// @@ -1601,39 +1601,144 @@ impl SerializeHeadersOptions { #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] pub fn set_custom_headers( mut self, - custom_headers: &[CustomSerializeHeader], - ) -> SerializeHeadersOptions { + custom_headers: &[CustomSerializeField], + ) -> SerializeFieldOptions { self.custom_headers = custom_headers.to_vec(); self } - /// TODO + /// Set the option to use only the specified custom headers. + /// + /// The default behavior when using custom headers is that the custom + /// properties are merged over the default properties. So if you have a + /// struct with three fields "item", "cost" and "availability" and you + /// specify a custom header just for "cost" will still get all three fields + /// output in the serialization. + /// + /// However, you may wish to output only the custom selected fields for use + /// cases where you wish to skip fields or reorder them. The + /// `use_custom_headers_only` property allow you to so that. See the + /// example below for the effect of the option. /// /// # Parameters /// /// * `enable` - Turn the property on/off. It is off by default. /// + /// # Examples + /// + /// The following example demonstrates different methods of handling custom + /// properties. The user can either merge them with the default properties + /// or use the custom properties exclusively. + /// + /// + /// ``` + /// # // This code is available in examples/doc_worksheet_serialize_headers_format8.rs + /// # + /// # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, 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)] + /// # struct Produce { + /// # fruit: &'static str, + /// # cost: f64, + /// # in_stock: bool, + /// # } + /// # + /// # // Create some data instances. + /// # let items = [ + /// # Produce { + /// # fruit: "Peach", + /// # cost: 1.05, + /// # in_stock: true, + /// # }, + /// # Produce { + /// # fruit: "Plum", + /// # cost: 0.15, + /// # in_stock: false, + /// # }, + /// # Produce { + /// # fruit: "Pear", + /// # cost: 0.75, + /// # in_stock: true, + /// # }, + /// # ]; + /// # + /// // Default handling of customized headers: the formatting is merged with the + /// // default values so "in_stock" is still shown. + /// let custom_headers = [ + /// CustomSerializeField::new("fruit").rename("Item"), + /// CustomSerializeField::new("cost").rename("Price"), + /// CustomSerializeField::new("in_stock").rename("Foo"), + /// ]; + /// let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); + /// + /// worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; + /// worksheet.serialize(&items)?; + /// + /// // Set the "use_custom_headers_only" option to shown only the specified + /// // custom headers. + /// let custom_headers = [ + /// CustomSerializeField::new("fruit").rename("Item"), + /// CustomSerializeField::new("cost").rename("Price"), + /// ]; + /// let header_options = SerializeFieldOptions::new() + /// .set_custom_headers(&custom_headers) + /// .use_custom_headers_only(true); + /// + /// worksheet.deserialize_headers_with_options::(0, 4, &header_options)?; + /// worksheet.serialize(&items)?; + /// + /// // This can also be used to set the order of the output. + /// let custom_headers = [ + /// CustomSerializeField::new("cost").rename("Price"), + /// CustomSerializeField::new("fruit").rename("Item"), + /// ]; + /// let header_options = SerializeFieldOptions::new() + /// .set_custom_headers(&custom_headers) + /// .use_custom_headers_only(true); + /// + /// worksheet.deserialize_headers_with_options::(0, 7, &header_options)?; + /// worksheet.serialize(&items)?; + /// # + /// # // Save the file. + /// # workbook.save("serialize.xlsx")?; + /// # + /// # Ok(()) + /// # } + /// ``` + /// + /// Output file: + /// + /// /// /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn use_custom_headers_only(mut self, enable: bool) -> SerializeHeadersOptions { + pub fn use_custom_headers_only(mut self, enable: bool) -> SerializeFieldOptions { self.use_custom_headers_only = enable; self } } // ----------------------------------------------------------------------- -// CustomSerializeHeader. +// CustomSerializeField. // ----------------------------------------------------------------------- -/// The `CustomSerializeHeader` struct represents a custom serializer +/// The `CustomSerializeField` struct represents a custom serializer /// field/header. /// -/// `CustomSerializeHeader` can be used to set column headers to map serialized -/// data to. It allows you to rename, format or skip headers and also to define +/// `CustomSerializeField` can be used to set column headers to map serialized +/// fields to. It allows you to rename, format or skip headers and also to define /// formatting for field values. /// -/// It is used in conjunction with the [`SerializeHeadersOptions`] struct and +/// It is used in conjunction with the [`SerializeFieldOptions`] struct and /// [`Worksheet::deserialize_headers_with_options()`] and /// [`Worksheet::serialize_headers_with_options()`] methods. /// @@ -1649,7 +1754,7 @@ impl SerializeHeadersOptions { /// # // This code is available in examples/doc_worksheet_serialize_headers_custom.rs /// # /// use rust_xlsxwriter::{ -/// CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, +/// CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, /// }; /// use serde::{Deserialize, Serialize}; /// @@ -1692,14 +1797,14 @@ impl SerializeHeadersOptions { /// /// // Set up the custom headers. /// let custom_headers = [ -/// CustomSerializeHeader::new("fruit") +/// CustomSerializeField::new("fruit") /// .rename("Item"), -/// CustomSerializeHeader::new("cost") +/// CustomSerializeField::new("cost") /// .rename("Price") /// .set_value_format(¤cy_format), /// ]; /// -/// let header_options = SerializeHeadersOptions::new() +/// let header_options = SerializeFieldOptions::new() /// .set_header_format(&header_format) /// .set_custom_headers(&custom_headers); /// @@ -1726,7 +1831,7 @@ impl SerializeHeadersOptions { /// #[derive(Clone)] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] -pub struct CustomSerializeHeader { +pub struct CustomSerializeField { pub(crate) field_name: String, pub(crate) header_name: String, pub(crate) header_format: Option, @@ -1739,11 +1844,11 @@ pub struct CustomSerializeHeader { pub(crate) pixel_width: Option, } -impl CustomSerializeHeader { - /// Create custom serialize header options. +impl CustomSerializeField { + /// Create custom serialize field/header options. /// - /// Create a `CustomSerializeHeader` to be used with - /// [`SerializeHeadersOptions::set_custom_headers()`]. + /// Create a `CustomSerializeField` to be used with + /// [`SerializeFieldOptions::set_custom_headers()`]. /// /// The `field_name` argument must correspond to a struct field being /// serialized. @@ -1753,11 +1858,11 @@ impl CustomSerializeHeader { /// * `field_name` - The name of the serialized field to map to the header. /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn new(field_name: impl Into) -> CustomSerializeHeader { + pub fn new(field_name: impl Into) -> CustomSerializeField { let field_name = field_name.into(); let header_name = field_name.clone(); - CustomSerializeHeader { + CustomSerializeField { field_name, header_name, header_format: None, @@ -1784,7 +1889,7 @@ impl CustomSerializeHeader { /// 2. Rename the header (not field) when setting up custom serialization /// headers via [`Worksheet::deserialize_headers_with_options()`] or /// [`Worksheet::serialize_headers_with_options()`] and - /// [`CustomSerializeHeader::rename()`]. + /// [`CustomSerializeField::rename()`]. /// /// [field attribute]: https://serde.rs/field-attrs.html /// [container attribute]: https://serde.rs/container-attrs.html @@ -1806,7 +1911,7 @@ impl CustomSerializeHeader { /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers_rename2.rs /// # - /// # use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; + /// # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; /// # use serde::{Deserialize, Serialize}; /// # /// # fn main() -> Result<(), XlsxError> { @@ -1840,10 +1945,10 @@ impl CustomSerializeHeader { /// /// // Set up the custom headers. /// let custom_headers = [ - /// CustomSerializeHeader::new("fruit").rename("Item"), - /// CustomSerializeHeader::new("cost").rename("Price"), + /// CustomSerializeField::new("fruit").rename("Item"), + /// CustomSerializeField::new("cost").rename("Price"), /// ]; - /// let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + /// let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); /// /// // Set the serialization location and custom headers. /// worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; @@ -1866,14 +1971,14 @@ impl CustomSerializeHeader { /// src="https://rustxlsxwriter.github.io/images/worksheet_serialize_headers_rename1.png"> /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn rename(mut self, name: impl Into) -> CustomSerializeHeader { + pub fn rename(mut self, name: impl Into) -> CustomSerializeField { self.header_name = name.into(); self } /// Set the header format for a custom serialize header. /// - /// In general the [`SerializeHeadersOptions::set_header_format()`] method + /// In general the [`SerializeFieldOptions::set_header_format()`] method /// should be used to set the header format for all custom headers but if /// you require individual headers to have different header formats you can /// use this method. @@ -1885,7 +1990,7 @@ impl CustomSerializeHeader { /// * `format` - The [`Format`] property for the custom header. /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn set_header_format(mut self, format: impl Into) -> CustomSerializeHeader { + pub fn set_header_format(mut self, format: impl Into) -> CustomSerializeField { self.header_format = Some(format.into()); self } @@ -1895,7 +2000,7 @@ impl CustomSerializeHeader { /// This method can be used to set a number format, or other properties, for /// data that is serialized below the header. This method sets the format /// for the entire column whereas the - /// [`CustomSerializeHeader::set_value_format()`] method below only sets it + /// [`CustomSerializeField::set_value_format()`] method below only sets it /// for serialized data within the column. /// /// This a a wrapper around the [`Worksheet::set_column_format()`] method @@ -1918,7 +2023,7 @@ impl CustomSerializeHeader { /// # // This code is available in examples/doc_worksheet_serialize_headers_format5.rs /// # /// # use rust_xlsxwriter::{ - /// # CustomSerializeHeader, Format, FormatBorder, SerializeHeadersOptions, Workbook, XlsxError, + /// # CustomSerializeField, Format, FormatBorder, SerializeFieldOptions, Workbook, XlsxError, /// # }; /// # use serde::{Deserialize, Serialize}; /// # @@ -1964,9 +2069,9 @@ impl CustomSerializeHeader { /// # /// // Set up the custom headers. /// let custom_headers = - /// [CustomSerializeHeader::new("Price").set_column_format(¤cy_format)]; + /// [CustomSerializeField::new("Price").set_column_format(¤cy_format)]; /// - /// let header_options = SerializeHeadersOptions::new() + /// let header_options = SerializeFieldOptions::new() /// .set_header_format(&header_format) /// .set_custom_headers(&custom_headers); /// @@ -1990,7 +2095,7 @@ impl CustomSerializeHeader { /// /// - pub fn set_column_format(mut self, format: impl Into) -> CustomSerializeHeader { + pub fn set_column_format(mut self, format: impl Into) -> CustomSerializeField { self.column_format = Some(format.into()); self } @@ -2001,7 +2106,7 @@ impl CustomSerializeHeader { /// This method can be used to set a number format, or other properties, for /// data that is serialized below the header. This method sets the format /// for the serialized data within the column whereas the - /// [`CustomSerializeHeader::set_column_format()`] method above sets it for + /// [`CustomSerializeField::set_column_format()`] method above sets it for /// the the entire column. /// /// See [`Format`] and [`Format::set_num_format()`] for more information on @@ -2021,7 +2126,7 @@ impl CustomSerializeHeader { /// # // This code is available in examples/doc_worksheet_serialize_headers_format3.rs /// # /// # use rust_xlsxwriter::{ - /// # CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, + /// # CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError, /// # }; /// # use serde::{Deserialize, Serialize}; /// # @@ -2058,9 +2163,9 @@ impl CustomSerializeHeader { /// # }; /// # /// // Set the custom headers. - /// let header_options = SerializeHeadersOptions::new() + /// let header_options = SerializeFieldOptions::new() /// .set_custom_headers( - /// &[CustomSerializeHeader::new("cost").set_value_format(&value_format)] + /// &[CustomSerializeField::new("cost").set_value_format(&value_format)] /// ); /// /// // Set the serialization location and headers. @@ -2085,7 +2190,7 @@ impl CustomSerializeHeader { /// /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn set_value_format(mut self, format: impl Into) -> CustomSerializeHeader { + pub fn set_value_format(mut self, format: impl Into) -> CustomSerializeField { self.value_format = Some(format.into()); self } @@ -2124,7 +2229,7 @@ impl CustomSerializeHeader { /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers_skip3.rs /// # - /// # use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; + /// # use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; /// # use serde::{Deserialize, Serialize}; /// # /// # fn main() -> Result<(), XlsxError> { @@ -2161,8 +2266,8 @@ impl CustomSerializeHeader { /// }; /// /// // 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)]); + /// let header_options = SerializeFieldOptions::new() + /// .set_custom_headers(&[CustomSerializeField::new("in_stock").skip(true)]); /// /// // Set the serialization location and custom headers. /// worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; @@ -2185,7 +2290,7 @@ impl CustomSerializeHeader { /// src="https://rustxlsxwriter.github.io/images/worksheet_serialize_headers_skip1.png"> /// #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] - pub fn skip(mut self, enable: bool) -> CustomSerializeHeader { + pub fn skip(mut self, enable: bool) -> CustomSerializeField { self.skip = enable; self } @@ -2203,7 +2308,7 @@ impl CustomSerializeHeader { /// /// * `width` - The row width in character units. /// - pub fn set_column_width(mut self, width: impl Into) -> CustomSerializeHeader { + pub fn set_column_width(mut self, width: impl Into) -> CustomSerializeField { self.width = Some(width.into()); self } @@ -2221,7 +2326,7 @@ impl CustomSerializeHeader { /// /// * `width` - The row width in character units. /// - pub fn set_column_width_pixels(mut self, width: u16) -> CustomSerializeHeader { + pub fn set_column_width_pixels(mut self, width: u16) -> CustomSerializeField { self.pixel_width = Some(width); self } @@ -2918,7 +3023,7 @@ impl<'a> ser::SerializeStructVariant for &'a mut SerializerHeader { } // ----------------------------------------------------------------------- -// Header DeSerializer. This is the a simplified implementation of the +// Header Deserializer. This is the a simplified implementation of the // Deserializer trait to capture the headers/field names only. // ----------------------------------------------------------------------- pub(crate) struct DeSerializerHeader<'a> { diff --git a/src/worksheet.rs b/src/worksheet.rs index a2b5cf0d..ec84c91b 100644 --- a/src/worksheet.rs +++ b/src/worksheet.rs @@ -30,7 +30,7 @@ use serde::Serialize; use crate::SerializerHeader; #[cfg(feature = "serde")] -use crate::CustomSerializeHeader; +use crate::CustomSerializeField; #[cfg(feature = "serde")] use serde::Deserialize; @@ -39,7 +39,7 @@ use serde::Deserialize; use crate::deserialize_headers; #[cfg(feature = "serde")] -use crate::SerializeHeadersOptions; +use crate::SerializeFieldOptions; use crate::drawing::{Drawing, DrawingCoordinates, DrawingInfo, DrawingObject}; use crate::error::XlsxError; @@ -5994,25 +5994,51 @@ impl Worksheet { /// Write a Serde serializable struct to a worksheet. /// /// This method can be used to serialize [Serde](https://serde.rs) enabled - /// data structure into cells in a worksheet. + /// data structures into cells in a worksheet. /// /// See [Working with Serde](crate::serializer#working-with-serde) for /// background details on how serialization works with `rust_xlsxwriter`. /// - /// In order to serialize an instance of a data structure you must first - /// define the fields/headers and worksheet location that the serialization - /// will refer to. You can do this using one of the following methods: - /// - /// - [`Worksheet::serialize_headers()`]: The simplest most direct method. It - /// requires a argument of the type of struct that you wish to serialize. The - /// library uses this to infer the struct name and fields (via serialization). - /// - [`Worksheet::serialize_headers_with_format()`]: This is similar to the - /// previous method but it allows you to add a cell format for the headers. - /// - [`Worksheet::serialize_headers_with_options()`]: This requires the struct - /// type to be passed as a string and an array of [`CustomSerializeHeader`] - /// objects. However it gives the highest degree of control over the output. - /// This method also allows you to turn off the headers above the serialized - /// data. + /// When serializing structs `rust_xlsxwriter` needs to know location where + /// the serialization starts and also the type and field names of the struct + /// being serialized. The field names are used as headers and the type name + /// allows for several distinct structs to be serialized to the same + /// worksheet. + /// + /// + /// + /// The worksheet methods that perform this function fall into two types: + /// methods which use deserialization to find the fields from the *type* and + /// methods that use serialization to find the fields from an *instance of + /// the type*. The deserialization methods are easier to use but require + /// that the struct derives the Serde [`Deserialize`] trait as well as the + /// [`Serialize`] trait. The serialization methods work for anything else. + /// + /// There available methods are. + /// + /// - [`Worksheet::deserialize_headers()`]: The simplest most direct method. + /// It only requires the type of struct that you wish to serialize and + /// that it derives the [`Deserialize`] and [`Serialize`] traits. The + /// library uses this to infer the struct name and fields (via + /// deserialization). + /// + /// - [`Worksheet::deserialize_headers_with_format()`]: This is similar to + /// the previous method but it allows you to add a cell format for the + /// headers. + /// + /// - [`Worksheet::deserialize_headers_with_options()`]: Similar to the + /// previous methods but also allows configuration of the headers and + /// fields via [`SerializeFieldOptions`]. + /// + /// - [`Worksheet::serialize_headers()`]: Similar to the + /// `deserialize_headers()` method but it requires a concrete instance of + /// the type of struct that you wish to serialize. The library uses this + /// to infer the struct name and fields (via serialization). This method + /// only requires that the struct derives [`Serialize`]. + /// + /// Once the headers are set up an subsequent calls to `serialize()` will + /// write the struct data in rows beneath the header. + /// /// /// # Parameters /// @@ -6030,14 +6056,14 @@ impl Worksheet { /// /// # Examples /// - /// The following example demonstrates serializing instances of a Serde - /// derived data structure to a worksheet. + /// The following example demonstrates serializing instances of a Serde derived + /// data structure to a worksheet. /// /// ``` /// # // This code is available in examples/doc_worksheet_serialize.rs /// # - /// use rust_xlsxwriter::{Workbook, XlsxError, Format}; - /// use serde::Serialize; + /// use rust_xlsxwriter::{Format, Workbook, XlsxError}; + /// use serde::{Deserialize, Serialize}; /// /// fn main() -> Result<(), XlsxError> { /// let mut workbook = Workbook::new(); @@ -6049,7 +6075,7 @@ impl Worksheet { /// let format = Format::new().set_bold(); /// /// // Create a serializable struct. - /// #[derive(Serialize)] + /// #[derive(Deserialize, Serialize)] /// #[serde(rename_all = "PascalCase")] /// struct Produce { /// fruit: &'static str, @@ -6070,9 +6096,8 @@ impl Worksheet { /// 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::(0, 0, &format)?; /// /// // Serialize the data. /// worksheet.serialize(&item1)?; @@ -6110,8 +6135,12 @@ impl Worksheet { /// written and where serialized data will be written. /// /// See [Setting serialization - /// headers](crate::serializer#setting-serialization-headers) for - /// more information. + /// headers](crate::serializer#setting-serialization-headers) for more + /// information. + /// + /// See also [`Worksheet::deserialize_headers()`] which only requires the + /// serializable type and not an actual instance. That method requires that + /// your struct also derives "Deserialize". /// /// # Parameters /// @@ -6137,15 +6166,15 @@ impl Worksheet { /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers1.rs /// # - /// # use rust_xlsxwriter::{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(); - /// # + /// use rust_xlsxwriter::{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(); + /// /// // Create a serializable struct. /// #[derive(Serialize)] /// #[serde(rename_all = "PascalCase")] @@ -6176,12 +6205,12 @@ impl Worksheet { /// worksheet.serialize(&item1)?; /// worksheet.serialize(&item2)?; /// worksheet.serialize(&item3)?; - /// # - /// # // Save the file. - /// # workbook.save("serialize.xlsx")?; - /// # - /// # Ok(()) - /// # } + /// + /// // Save the file. + /// workbook.save("serialize.xlsx")?; + /// + /// Ok(()) + /// } /// ``` /// /// Output file: @@ -6189,8 +6218,7 @@ impl Worksheet { /// /// - /// This example demonstrates starting the serialization in a different - /// position. + /// You can serialize the data to any valid region of the worksheet: /// /// ``` /// # // This code is available in examples/doc_worksheet_serialize_headers2.rs @@ -6226,14 +6254,14 @@ impl Worksheet { /// # cost: 0.75, /// # }; /// # - /// // Set up the start location and headers of the data to be serialized using - /// // any temporary or valid instance. + /// # // Set up the start location and headers of the data to be serialized using + /// # // any temporary or valid instance. /// worksheet.serialize_headers(1, 2, &item1)?; - /// - /// // Serialize the data. - /// worksheet.serialize(&item1)?; - /// worksheet.serialize(&item2)?; - /// worksheet.serialize(&item3)?; + /// # + /// # // Serialize the data. + /// # worksheet.serialize(&item1)?; + /// # worksheet.serialize(&item2)?; + /// # worksheet.serialize(&item3)?; /// # /// # // Save the file. /// # workbook.save("serialize.xlsx")?; @@ -6273,6 +6301,10 @@ impl Worksheet { /// headers](crate::serializer#setting-serialization-headers) for more /// information. /// + /// See also [`Worksheet::deserialize_headers_with_format()`] which only + /// requires the serializable type and not an actual instance. That method + /// requires that your struct also derives "Deserialize". + /// /// # Parameters /// /// * `row` - The zero indexed row number. @@ -6292,21 +6324,21 @@ impl Worksheet { /// /// # Examples /// - /// The following example demonstrates serializing instances of a Serde - /// derived data structure to a worksheet. + /// The following example demonstrates serializing instances of a Serde derived + /// data structure to a worksheet. /// /// ``` - /// # // This code is available in examples/doc_worksheet_serialize.rs - /// # - /// # use rust_xlsxwriter::{Workbook, XlsxError, Format}; - /// # use serde::Serialize; - /// # - /// # fn main() -> Result<(), XlsxError> { - /// # let mut workbook = Workbook::new(); - /// # - /// # // Add a worksheet to the workbook. - /// # let worksheet = workbook.add_worksheet(); + /// # // This code is available in examples/doc_worksheet_serialize_headers4.rs /// # + /// 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(); /// @@ -6340,14 +6372,13 @@ impl Worksheet { /// worksheet.serialize(&item1)?; /// worksheet.serialize(&item2)?; /// worksheet.serialize(&item3)?; - /// # - /// # // Save the file. - /// # workbook.save("serialize.xlsx")?; - /// # - /// # Ok(()) - /// # } - /// ``` /// + /// // Save the file. + /// workbook.save("serialize.xlsx")?; + /// + /// Ok(()) + /// } + /// ``` /// Output file: /// /// Result<(), XlsxError> { - /// # let mut workbook = Workbook::new(); - /// # - /// # // Add a worksheet to the workbook. - /// # let worksheet = workbook.add_worksheet(); - /// # + /// use rust_xlsxwriter::{ + /// CustomSerializeField, Format, SerializeFieldOptions, 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 some formats to use with the serialization data. /// let bold = Format::new().set_bold(); /// let currency = Format::new().set_num_format("$0.00"); @@ -6458,25 +6498,26 @@ impl Worksheet { /// // Set up the start location and headers of the data to be serialized using /// // custom headers. /// let custom_headers = [ - /// CustomSerializeHeader::new("fruit") - /// .rename("Fruit") - /// .set_header_format(&bold), - /// CustomSerializeHeader::new("cost") + /// CustomSerializeField::new("fruit") + /// .rename("Fruit"), + /// CustomSerializeField::new("cost") /// .rename("Price") - /// .set_header_format(&bold) /// .set_value_format(¤cy), /// ]; + /// let header_options = SerializeFieldOptions::new() + /// .set_header_format(&bold) + /// .set_custom_headers(&custom_headers); /// - /// worksheet.serialize_headers_with_options(0, 0, "Produce", &custom_headers)?; + /// worksheet.serialize_headers_with_options(0, 0, &items[0], &header_options)?; /// /// // Serialize the data. /// worksheet.serialize(&items)?; - /// # - /// # // Save the file. - /// # workbook.save("serialize.xlsx")?; - /// # - /// # Ok(()) - /// # } + /// + /// // Save the file. + /// workbook.save("serialize.xlsx")?; + /// + /// Ok(()) + /// } /// ``` /// /// Output file: @@ -6491,7 +6532,7 @@ impl Worksheet { row: RowNum, col: ColNum, data_structure: &T, - header_options: &SerializeHeadersOptions, + header_options: &SerializeFieldOptions, ) -> Result<&mut Worksheet, XlsxError> where T: Serialize, @@ -6507,10 +6548,94 @@ impl Worksheet { self.store_serialization_headers_with_options(row, col, &headers, header_options) } - /// TODO + /// Write the location and headers for data serialization. + /// + /// The [`Worksheet::serialize()`] method, above, serializes Serde derived + /// structs to worksheet cells. However, before you serialize the data you + /// need to set the position in the worksheet where the headers will be + /// written and where serialized data will be written. + /// + /// See [Setting serialization + /// headers](crate::serializer#setting-serialization-headers) for more + /// information. + /// + /// See also [`Worksheet::serialize_headers()`] which requires an instance + /// of the serializable type but doesn't require that your struct also + /// derives "Deserialize". + /// + /// # Parameters + /// + /// * `row` - The zero indexed row number. + /// * `col` - The zero indexed column number. /// /// # Errors /// + /// * [`XlsxError::RowColumnLimitError`] - Row or column exceeds Excel's + /// worksheet limits. + /// * [`XlsxError::MaxStringLengthExceeded`] - String exceeds Excel's limit + /// of 32,767 characters. + /// * [`XlsxError::SerdeError`] - Errors encountered during the Serde + /// serialization. + /// + /// # Examples + /// + /// The following example demonstrates serializing instances of a Serde + /// derived data structure to a worksheet. + /// + /// ``` + /// # // This code is available in examples/doc_worksheet_deserialize_headers1.rs + /// # + /// 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::(0, 0)?; + /// + /// // Serialize the data. + /// worksheet.serialize(&item1)?; + /// worksheet.serialize(&item2)?; + /// worksheet.serialize(&item3)?; + /// + /// // Save the file. + /// workbook.save("serialize.xlsx")?; + /// + /// Ok(()) + /// } + /// ``` + /// + /// Output file: + /// + /// + /// #[cfg(feature = "serde")] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] pub fn deserialize_headers<'de, T>( @@ -6524,10 +6649,100 @@ impl Worksheet { self.deserialize_headers_with_format::(row, col, &Format::default()) } - /// TODO + /// Write the location and headers for data serialization, with formatting. + /// + /// The [`Worksheet::serialize()`] method, above, serializes Serde derived + /// structs to worksheet cells. However, before you serialize the data you + /// need to set the position in the worksheet where the headers will be + /// written and where serialized data will be written. This method also + /// allows you to set the format for the headers. + /// + /// See [Setting serialization + /// headers](crate::serializer#setting-serialization-headers) for more + /// information. + /// + /// See also [`Worksheet::serialize_headers_with_format()`] which requires + /// an instance of the serializable type but doesn't require that your + /// struct also derives "Deserialize". + /// + /// # Parameters + /// + /// * `row` - The zero indexed row number. + /// * `col` - The zero indexed column number. + /// * `format` - The [`Format`] property for the cell. /// /// # Errors /// + /// * [`XlsxError::RowColumnLimitError`] - Row or column exceeds Excel's + /// worksheet limits. + /// * [`XlsxError::MaxStringLengthExceeded`] - String exceeds Excel's limit + /// of 32,767 characters. + /// * [`XlsxError::SerdeError`] - Errors encountered during the Serde + /// serialization. + /// + /// # Examples + /// + /// The following example demonstrates serializing instances of a Serde + /// derived data structure to a worksheet. + /// + /// ``` + /// # // This code is available in examples/doc_worksheet_serialize.rs + /// # + /// # use rust_xlsxwriter::{Format, 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 a simple format for the headers. + /// # let format = Format::new().set_bold(); + /// # + /// # // 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_with_format::(0, 0, &format)?; + /// # + /// # // Serialize the data. + /// # worksheet.serialize(&item1)?; + /// # worksheet.serialize(&item2)?; + /// # worksheet.serialize(&item3)?; + /// # + /// # // Save the file. + /// # workbook.save("serialize.xlsx")?; + /// # + /// # Ok(()) + /// # } + /// ``` + /// + /// Output file: + /// + /// + /// + /// #[cfg(feature = "serde")] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] pub fn deserialize_headers_with_format<'de, T>( @@ -6545,17 +6760,129 @@ impl Worksheet { self.store_serialization_headers(row, col, &headers, format) } - /// TODO + /// Write the location and headers for data serialization, with additional + /// options. + /// + /// The [`Worksheet::serialize()`] and + /// [`Worksheet::deserialize_headers_with_format()`] methods, above, set the + /// serialization headers and location via an instance of the structure to + /// be serialized. This will work for the majority of use cases, and for + /// other cases you can adjust the output by using Serde Container or Field + /// [Attributes]. See [Working with Serde](#working-with-serde). + /// + /// [Attributes]: https://serde.rs/attributes.html + /// + /// If these methods don't give you the output or flexibility you require + /// you can use the `deserialize_headers_with_options()` method with + /// [`SerializeFieldOptions`] and [`CustomSerializeField`] options. This + /// allows you to reorder, rename, format or skip headers and also define + /// formatting for field values. + /// + /// See [`SerializeFieldOptions`] and [`CustomSerializeField`] for + /// additional information and examples. + /// + /// See also [`Worksheet::serialize_headers_with_options()`] which requires + /// an instance of the serializable type but doesn't require that your + /// struct also derives "Deserialize". + /// + /// + /// # Parameters + /// + /// * `row` - The zero indexed row number. + /// * `col` - The zero indexed column number. + /// * `header_options` - A [`SerializeFieldOptions`] instance. /// /// # Errors /// + /// * [`XlsxError::RowColumnLimitError`] - Row or column exceeds Excel's + /// worksheet limits. + /// * [`XlsxError::MaxStringLengthExceeded`] - String exceeds Excel's limit + /// of 32,767 characters. + /// * [`XlsxError::SerdeError`] - Errors encountered during the Serde + /// serialization. + /// + /// # Examples + /// + /// The following example demonstrates serializing instances of a Serde derived + /// data structure to a worksheet. + /// + /// ``` + /// # // This code is available in examples/doc_worksheet_serialize_headers_with_options2.rs + /// # + /// use rust_xlsxwriter::{ + /// CustomSerializeField, Format, SerializeFieldOptions, 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 bold = Format::new().set_bold(); + /// let currency = Format::new().set_num_format("$0.00"); + /// + /// // Create a serializable struct. + /// #[derive(Deserialize, Serialize)] + /// struct Produce { + /// fruit: &'static str, + /// cost: f64, + /// } + /// + /// // Create some data instances. + /// let items = [ + /// Produce { + /// fruit: "Peach", + /// cost: 1.05, + /// }, + /// Produce { + /// fruit: "Plum", + /// cost: 0.15, + /// }, + /// Produce { + /// fruit: "Pear", + /// cost: 0.75, + /// }, + /// ]; + /// + /// // Set up the start location and headers of the data to be serialized using + /// // custom headers. + /// let custom_headers = [ + /// CustomSerializeField::new("fruit") + /// .rename("Fruit"), + /// CustomSerializeField::new("cost") + /// .rename("Price") + /// .set_value_format(¤cy), + /// ]; + /// let header_options = SerializeFieldOptions::new() + /// .set_header_format(&bold) + /// .set_custom_headers(&custom_headers); + /// + /// worksheet.deserialize_headers_with_options::(0, 0, &header_options)?; + /// + /// // Serialize the data. + /// worksheet.serialize(&items)?; + /// + /// // Save the file. + /// workbook.save("serialize.xlsx")?; + /// + /// Ok(()) + /// } + /// ``` + /// + /// Output file: + /// + /// + /// #[cfg(feature = "serde")] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))] pub fn deserialize_headers_with_options<'de, T>( &mut self, row: RowNum, col: ColNum, - header_options: &SerializeHeadersOptions, + header_options: &SerializeFieldOptions, ) -> Result<&mut Worksheet, XlsxError> where T: Deserialize<'de>, @@ -6573,7 +6900,7 @@ impl Worksheet { row: RowNum, col: ColNum, headers: &SerializerHeader, - header_options: &SerializeHeadersOptions, + header_options: &SerializeFieldOptions, ) -> Result<&mut Worksheet, XlsxError> { // Check that any custom field names match the actual field names. let field_names: HashSet = HashSet::from_iter(headers.field_names.clone()); @@ -6588,7 +6915,7 @@ impl Worksheet { // Create a map of the user defined custom field settings to overwrite // the default field settings. - let mut custom_fields: HashMap<&String, &CustomSerializeHeader> = HashMap::new(); + let mut custom_fields: HashMap<&String, &CustomSerializeField> = HashMap::new(); for custom_header in &header_options.custom_headers { custom_fields.insert(&custom_header.field_name, custom_header); } @@ -6601,7 +6928,7 @@ impl Worksheet { // specified custom fields. The "use_custom_headers_only" overrides the // default headers to allow users to skip fields. if !header_options.use_custom_headers_only { - let mut custom_headers: Vec = vec![]; + let mut custom_headers: Vec = vec![]; for field_name in &headers.field_names { match custom_fields.get(field_name) { @@ -6610,7 +6937,7 @@ impl Worksheet { custom_headers.push((*custom_field).clone()); } } - None => custom_headers.push(CustomSerializeHeader::new(field_name)), + None => custom_headers.push(CustomSerializeField::new(field_name)), } } @@ -6630,14 +6957,14 @@ impl Worksheet { header_format: &Format, ) -> Result<&mut Worksheet, XlsxError> { // Convert the field names to custom header structs. - let custom_headers: Vec = headers + let custom_headers: Vec = headers .field_names .iter() - .map(CustomSerializeHeader::new) + .map(CustomSerializeField::new) .collect(); // Transfer the options to a default option struct. - let header_options = SerializeHeadersOptions { + let header_options = SerializeFieldOptions { struct_name: headers.struct_name.clone(), header_format: Some(header_format.clone()), custom_headers, @@ -6653,7 +6980,7 @@ impl Worksheet { &mut self, row: RowNum, col: ColNum, - header_options: &SerializeHeadersOptions, + header_options: &SerializeFieldOptions, ) -> Result<&mut Worksheet, XlsxError> { // Check row and columns are in the allowed range. if !self.check_dimensions_only(row, col) { @@ -6675,7 +7002,7 @@ impl Worksheet { ))); } - // HashMap + // HashMap let mut field_map = HashMap::new(); let col_initial = col; diff --git a/tests/integration/serde06.rs b/tests/integration/serde06.rs index 07707063..47f97f95 100644 --- a/tests/integration/serde06.rs +++ b/tests/integration/serde06.rs @@ -6,9 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; // Test case for Serde serialization. First test isn't serialized. @@ -83,10 +81,10 @@ fn create_new_xlsx_file_3(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1").set_header_format(&bold), - CustomSerializeHeader::new("col2").set_header_format(&bold), + CustomSerializeField::new("col1").set_header_format(&bold), + CustomSerializeField::new("col2").set_header_format(&bold), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data, &header_options)?; worksheet.serialize(&data)?; @@ -117,11 +115,11 @@ fn create_new_xlsx_file_4(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .set_header_format(&bold); diff --git a/tests/integration/serde07.rs b/tests/integration/serde07.rs index 760f41ba..ebc314b4 100644 --- a/tests/integration/serde07.rs +++ b/tests/integration/serde07.rs @@ -6,7 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; // Test case for Serde serialization. First test isn't serialized. @@ -133,10 +133,10 @@ fn create_new_xlsx_file_4(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data[0], &header_options)?; @@ -179,10 +179,10 @@ fn create_new_xlsx_file_5(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .use_custom_headers_only(true); @@ -226,11 +226,11 @@ fn create_new_xlsx_file_6(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), - CustomSerializeHeader::new("col3").skip(true), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), + CustomSerializeField::new("col3").skip(true), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data[0], &header_options)?; worksheet.serialize(&data)?; @@ -268,10 +268,10 @@ fn create_new_xlsx_file_7(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .use_custom_headers_only(true); @@ -314,10 +314,10 @@ fn create_new_xlsx_file_8(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data[0], &header_options)?; worksheet.serialize(&data)?; @@ -355,10 +355,10 @@ fn create_new_xlsx_file_9(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("field1").rename("col1"), - CustomSerializeHeader::new("field2").rename("col2"), + CustomSerializeField::new("field1").rename("col1"), + CustomSerializeField::new("field2").rename("col2"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data[0], &header_options)?; worksheet.serialize(&data)?; @@ -399,8 +399,8 @@ fn create_new_xlsx_file_10(filename: &str) -> Result<(), XlsxError> { }, ]; - let custom_headers = [CustomSerializeHeader::new("col3").skip(true)]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let custom_headers = [CustomSerializeField::new("col3").skip(true)]; + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data[0], &header_options)?; worksheet.serialize(&data)?; @@ -442,11 +442,11 @@ fn create_new_xlsx_file_11(filename: &str) -> Result<(), XlsxError> { ]; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), - CustomSerializeHeader::new("col3").skip(true), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), + CustomSerializeField::new("col3").skip(true), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .use_custom_headers_only(true); diff --git a/tests/integration/serde08.rs b/tests/integration/serde08.rs index a69d7178..6ff04458 100644 --- a/tests/integration/serde08.rs +++ b/tests/integration/serde08.rs @@ -6,9 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; // Test case for Serde serialization. First test isn't serialized. @@ -77,11 +75,11 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1").set_value_format(&bold), - CustomSerializeHeader::new("col2").set_value_format(&italic), - CustomSerializeHeader::new("col3").set_value_format(&bold_italic), + CustomSerializeField::new("col1").set_value_format(&bold), + CustomSerializeField::new("col2").set_value_format(&italic), + CustomSerializeField::new("col3").set_value_format(&bold_italic), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -91,11 +89,11 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { // Secondary test. This should be ignored since one of the field names is wrong. let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), - CustomSerializeHeader::new("col99"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), + CustomSerializeField::new("col99"), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); let _ = worksheet.serialize_headers_with_options(6, 0, &data1, &header_options); diff --git a/tests/integration/serde09.rs b/tests/integration/serde09.rs index 508d0fdb..e86ba86e 100644 --- a/tests/integration/serde09.rs +++ b/tests/integration/serde09.rs @@ -6,7 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; // Test case for Serde serialization. First test isn't serialized. @@ -45,10 +45,10 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2"), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2"), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .hide_headers(true); diff --git a/tests/integration/serde10.rs b/tests/integration/serde10.rs index e703ed1c..ac5fb892 100644 --- a/tests/integration/serde10.rs +++ b/tests/integration/serde10.rs @@ -7,7 +7,7 @@ use crate::common; use rust_xlsxwriter::{ - CustomSerializeHeader, ExcelDateTime, Format, SerializeHeadersOptions, Workbook, XlsxError, + CustomSerializeField, ExcelDateTime, Format, SerializeFieldOptions, Workbook, XlsxError, }; use serde::Serialize; @@ -75,10 +75,10 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2").set_value_format(&format), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2").set_value_format(&format), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -124,10 +124,10 @@ fn create_new_xlsx_file_3(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2").set_value_format(&format), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2").set_value_format(&format), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -182,10 +182,10 @@ fn create_new_xlsx_file_4(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2").set_value_format(&format), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2").set_value_format(&format), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -231,10 +231,10 @@ fn create_new_xlsx_file_5(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1"), - CustomSerializeHeader::new("col2").set_value_format(&format), + CustomSerializeField::new("col1"), + CustomSerializeField::new("col2").set_value_format(&format), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; diff --git a/tests/integration/serde11.rs b/tests/integration/serde11.rs index ea2d833a..ecb454ea 100644 --- a/tests/integration/serde11.rs +++ b/tests/integration/serde11.rs @@ -6,9 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::{Deserialize, Serialize}; // Test case for Serde serialization. First test isn't serialized. @@ -77,11 +75,11 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1").set_header_format(&bold), - CustomSerializeHeader::new("col2").set_header_format(&italic), - CustomSerializeHeader::new("col3").set_header_format(&bold), + CustomSerializeField::new("col1").set_header_format(&bold), + CustomSerializeField::new("col2").set_header_format(&italic), + CustomSerializeField::new("col3").set_header_format(&bold), ]; - let header_options = SerializeHeadersOptions::new().set_custom_headers(&custom_headers); + let header_options = SerializeFieldOptions::new().set_custom_headers(&custom_headers); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -129,8 +127,8 @@ fn create_new_xlsx_file_3(filename: &str) -> Result<(), XlsxError> { col3: 9, }; - let custom_headers = [CustomSerializeHeader::new("col2").set_header_format(&italic)]; - let header_options = SerializeHeadersOptions::new() + let custom_headers = [CustomSerializeField::new("col2").set_header_format(&italic)]; + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .set_header_format(&bold); @@ -181,10 +179,10 @@ fn create_new_xlsx_file_4(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1").set_header_format(&bold), - CustomSerializeHeader::new("col3").set_header_format(&bold), + CustomSerializeField::new("col1").set_header_format(&bold), + CustomSerializeField::new("col3").set_header_format(&bold), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .set_header_format(&italic); @@ -235,10 +233,10 @@ fn create_new_xlsx_file_5(filename: &str) -> Result<(), XlsxError> { }; let custom_headers = [ - CustomSerializeHeader::new("col1").set_header_format(&bold), - CustomSerializeHeader::new("col3").set_header_format(&bold), + CustomSerializeField::new("col1").set_header_format(&bold), + CustomSerializeField::new("col3").set_header_format(&bold), ]; - let header_options = SerializeHeadersOptions::new() + let header_options = SerializeFieldOptions::new() .set_custom_headers(&custom_headers) .set_header_format(&italic); diff --git a/tests/integration/serde12.rs b/tests/integration/serde12.rs index 7d3fa93f..2a7c5a39 100644 --- a/tests/integration/serde12.rs +++ b/tests/integration/serde12.rs @@ -6,7 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{CustomSerializeHeader, SerializeHeadersOptions, Workbook, XlsxError}; +use rust_xlsxwriter::{CustomSerializeField, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; // Test case for Serde serialization. First test isn't serialized. @@ -69,8 +69,8 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { col3: 9, }; - let header_options = SerializeHeadersOptions::new() - .set_custom_headers(&[CustomSerializeHeader::new("col2").set_column_width(13.57)]); + let header_options = SerializeFieldOptions::new() + .set_custom_headers(&[CustomSerializeField::new("col2").set_column_width(13.57)]); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; @@ -115,8 +115,8 @@ fn create_new_xlsx_file_3(filename: &str) -> Result<(), XlsxError> { col3: 9, }; - let header_options = SerializeHeadersOptions::new() - .set_custom_headers(&[CustomSerializeHeader::new("col2").set_column_width_pixels(100)]); + let header_options = SerializeFieldOptions::new() + .set_custom_headers(&[CustomSerializeField::new("col2").set_column_width_pixels(100)]); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?; diff --git a/tests/integration/serde13.rs b/tests/integration/serde13.rs index 07c705fe..c4795828 100644 --- a/tests/integration/serde13.rs +++ b/tests/integration/serde13.rs @@ -6,9 +6,7 @@ // Copyright 2022-2023, John McNamara, jmcnamara@cpan.org use crate::common; -use rust_xlsxwriter::{ - CustomSerializeHeader, Format, SerializeHeadersOptions, Workbook, XlsxError, -}; +use rust_xlsxwriter::{CustomSerializeField, Format, SerializeFieldOptions, Workbook, XlsxError}; use serde::Serialize; // Test case for Serde serialization. First test isn't serialized. @@ -75,8 +73,8 @@ fn create_new_xlsx_file_2(filename: &str) -> Result<(), XlsxError> { col3: 9, }; - let header_options = SerializeHeadersOptions::new() - .set_custom_headers(&[CustomSerializeHeader::new("col2").set_column_format(&bold)]); + let header_options = SerializeFieldOptions::new() + .set_custom_headers(&[CustomSerializeField::new("col2").set_column_format(&bold)]); worksheet.serialize_headers_with_options(0, 0, &data1, &header_options)?;