From 55a963e3602c34b02330df4a2f5ac162d8889bae Mon Sep 17 00:00:00 2001 From: Nicolas Hatcher Date: Tue, 20 Feb 2024 15:19:05 +0100 Subject: [PATCH] FIX: Adds more documentation --- base/src/model.rs | 145 +++++++++++++++++++++- base/src/new_empty.rs | 4 +- base/src/test/engineering/test_complex.rs | 2 +- base/src/test/mod.rs | 1 + base/src/test/test_extend.rs | 106 ++++++++++++++++ 5 files changed, 250 insertions(+), 8 deletions(-) create mode 100644 base/src/test/test_extend.rs diff --git a/base/src/model.rs b/base/src/model.rs index 550588c..52ef35b 100644 --- a/base/src/model.rs +++ b/base/src/model.rs @@ -42,7 +42,7 @@ use crate::{ utils as common, }; -pub use chrono_tz::Tz; +use chrono_tz::Tz; #[cfg(test)] pub use crate::mock_time::get_milliseconds_since_epoch; @@ -651,7 +651,7 @@ impl Model { } } - /// Sets the color of the sheet tab + /// Sets the color of the sheet tab. /// /// # Examples /// @@ -974,6 +974,10 @@ impl Model { /// # Ok(()) /// # } /// ``` + /// + /// See also: + /// * [Model::extend_to()] + /// * [Model::extend_copied_value()] pub fn move_cell_value_to_area( &mut self, value: &str, @@ -1040,6 +1044,10 @@ impl Model { /// # Ok(()) /// # } /// ``` + /// + /// See also: + /// * [Model::extend_copied_value()] + /// * [Model::move_cell_value_to_area()] pub fn extend_to( &self, sheet: u32, @@ -1069,6 +1077,8 @@ impl Model { /// 'Extends' the formula `value` from `source` to `target` /// + /// # Examples + /// /// ```rust /// # use ironcalc_base::model::Model; /// # use ironcalc_base::expressions::types::CellReferenceIndex; @@ -1081,6 +1091,10 @@ impl Model { /// # Ok(()) /// # } /// ``` + /// + /// See also: + /// * [Model::extend_to()] + /// * [Model::move_cell_value_to_area()] pub fn extend_copied_value( &mut self, value: &str, @@ -1118,6 +1132,8 @@ impl Model { /// Returns the formula in (`sheet`, `row`, `column`) if any /// + /// # Examples + /// /// ```rust /// # use ironcalc_base::model::Model; /// # fn main() -> Result<(), Box> { @@ -1130,6 +1146,9 @@ impl Model { /// # Ok(()) /// # } /// ``` + /// + /// See also: + /// * [Model::get_cell_content()] pub fn cell_formula( &self, sheet: u32, @@ -1152,6 +1171,28 @@ impl Model { /// Updates the value of a cell with some text /// It does not change the style unless needs to add "quoting" + /// + /// # Examples + /// + /// ```rust + /// # use ironcalc_base::model::Model; + /// # fn main() -> Result<(), Box> { + /// let mut model = Model::new_empty("model", "en", "UTC")?; + /// let (sheet, row, column) = (0, 1, 1); + /// model.set_user_input(sheet, row, column, "Hello!".to_string()); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "Hello!".to_string()); + /// + /// model.update_cell_with_text(sheet, row, column, "Goodbye!"); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "Goodbye!".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// See also: + /// * [Model::set_user_input()] + /// * [Model::update_cell_with_number()] + /// * [Model::update_cell_with_bool()] + /// * [Model::update_cell_with_formula()] pub fn update_cell_with_text(&mut self, sheet: u32, row: i32, column: i32, value: &str) { let style_index = self.get_cell_style_index(sheet, row, column); let new_style_index; @@ -1173,6 +1214,28 @@ impl Model { /// Updates the value of a cell with a boolean value /// It does not change the style + /// + /// # Examples + /// + /// ```rust + /// # use ironcalc_base::model::Model; + /// # fn main() -> Result<(), Box> { + /// let mut model = Model::new_empty("model", "en", "UTC")?; + /// let (sheet, row, column) = (0, 1, 1); + /// model.set_user_input(sheet, row, column, "TRUE".to_string()); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "TRUE".to_string()); + /// + /// model.update_cell_with_bool(sheet, row, column, false); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "FALSE".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// See also: + /// * [Model::set_user_input()] + /// * [Model::update_cell_with_number()] + /// * [Model::update_cell_with_text()] + /// * [Model::update_cell_with_formula()] pub fn update_cell_with_bool(&mut self, sheet: u32, row: i32, column: i32, value: bool) { let style_index = self.get_cell_style_index(sheet, row, column); let new_style_index = if self.workbook.styles.style_is_quote_prefix(style_index) { @@ -1188,6 +1251,28 @@ impl Model { /// Updates the value of a cell with a number /// It does not change the style + /// + /// # Examples + /// + /// ```rust + /// # use ironcalc_base::model::Model; + /// # fn main() -> Result<(), Box> { + /// let mut model = Model::new_empty("model", "en", "UTC")?; + /// let (sheet, row, column) = (0, 1, 1); + /// model.set_user_input(sheet, row, column, "42".to_string()); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "42".to_string()); + /// + /// model.update_cell_with_number(sheet, row, column, 23.0); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "23".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// See also: + /// * [Model::set_user_input()] + /// * [Model::update_cell_with_text()] + /// * [Model::update_cell_with_bool()] + /// * [Model::update_cell_with_formula()] pub fn update_cell_with_number(&mut self, sheet: u32, row: i32, column: i32, value: f64) { let style_index = self.get_cell_style_index(sheet, row, column); let new_style_index = if self.workbook.styles.style_is_quote_prefix(style_index) { @@ -1204,6 +1289,30 @@ impl Model { /// Updates the formula of given cell /// It does not change the style unless needs to add "quoting" /// Expects the formula to start with "=" + /// + /// # Examples + /// + /// ```rust + /// # use ironcalc_base::model::Model; + /// # fn main() -> Result<(), Box> { + /// let mut model = Model::new_empty("model", "en", "UTC")?; + /// let (sheet, row, column) = (0, 1, 1); + /// model.set_user_input(sheet, row, column, "=A2*2".to_string()); + /// model.evaluate(); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "=A2*2".to_string()); + /// + /// model.update_cell_with_formula(sheet, row, column, "=A3*2".to_string()); + /// model.evaluate(); + /// assert_eq!(model.get_cell_content(sheet, row, column)?, "=A3*2".to_string()); + /// # Ok(()) + /// # } + /// ``` + /// + /// See also: + /// * [Model::set_user_input()] + /// * [Model::update_cell_with_number()] + /// * [Model::update_cell_with_bool()] + /// * [Model::update_cell_with_text()] pub fn update_cell_with_formula( &mut self, sheet: u32, @@ -1225,11 +1334,37 @@ impl Model { Ok(()) } - /// Sets a cell parametrized by (`sheet`, `row`, `column`) with `value` + /// Sets a cell parametrized by (`sheet`, `row`, `column`) with `value`. + /// /// This mimics a user entering a value on a cell. + /// /// If you enter a currency `$100` it will set as a number and update the style - /// Note that for currencies/percentage there is only one possible style - /// The value is always a string, so we need to try to cast it into numbers/booleans/errors + /// Note that for currencies/percentage there is only one possible style + /// The value is always a string, so we need to try to cast it into numbers/booleans/errors + /// + /// # Examples + /// + /// ```rust + /// # use ironcalc_base::model::Model; + /// # use ironcalc_base::cell::CellValue; + /// # fn main() -> Result<(), Box> { + /// let mut model = Model::new_empty("model", "en", "UTC")?; + /// model.set_user_input(0, 1, 1, "100$".to_string()); + /// model.set_user_input(0, 2, 1, "125$".to_string()); + /// model.set_user_input(0, 3, 1, "-10$".to_string()); + /// model.set_user_input(0, 1, 2, "=SUM(A:A)".to_string()); + /// model.evaluate(); + /// assert_eq!(model.get_cell_value_by_index(0, 1, 2), Ok(CellValue::Number(215.0))); + /// assert_eq!(model.formatted_cell_value(0, 1, 2), Ok("215$".to_string())); + /// # Ok(()) + /// # } + /// ``` + /// + /// See also: + /// * [Model::update_cell_with_formula()] + /// * [Model::update_cell_with_number()] + /// * [Model::update_cell_with_bool()] + /// * [Model::update_cell_with_text()] pub fn set_user_input(&mut self, sheet: u32, row: i32, column: i32, value: String) { // If value starts with "'" then we force the style to be quote_prefix let style_index = self.get_cell_style_index(sheet, row, column); diff --git a/base/src/new_empty.rs b/base/src/new_empty.rs index 81f0725..52cc0b2 100644 --- a/base/src/new_empty.rs +++ b/base/src/new_empty.rs @@ -17,7 +17,7 @@ use crate::{ utils::ParsedReference, }; -pub use chrono_tz::Tz; +use chrono_tz::Tz; pub const APPLICATION: &str = "IronCalc Sheets"; pub const APP_VERSION: &str = "10.0000"; @@ -28,7 +28,7 @@ pub const IRONCALC_USER: &str = "IronCalc User"; /// \ , / , * , ? , : , [ , ]. fn is_valid_sheet_name(name: &str) -> bool { let invalid = ['\\', '/', '*', '?', ':', '[', ']']; - return !name.is_empty() && name.chars().count() <= 31 && !name.contains(&invalid[..]); + !name.is_empty() && name.chars().count() <= 31 && !name.contains(&invalid[..]) } impl Model { diff --git a/base/src/test/engineering/test_complex.rs b/base/src/test/engineering/test_complex.rs index 19dd430..8d7daee 100644 --- a/base/src/test/engineering/test_complex.rs +++ b/base/src/test/engineering/test_complex.rs @@ -79,7 +79,7 @@ fn fn_imcos() { model.evaluate(); - assert_eq!(model._get_text("A1"), "-6.58066304055116+7.58155274274654i"); + assert_eq!(model._get_text("A1"), "-6.58066304055116+7.58155274274655i"); } #[test] diff --git a/base/src/test/mod.rs b/base/src/test/mod.rs index c2fbbf2..a33aa35 100644 --- a/base/src/test/mod.rs +++ b/base/src/test/mod.rs @@ -47,6 +47,7 @@ mod test_fn_offset; mod test_number_format; mod test_escape_quotes; +mod test_extend; mod test_fn_type; mod test_frozen_rows_and_columns; mod test_get_cell_content; diff --git a/base/src/test/test_extend.rs b/base/src/test/test_extend.rs new file mode 100644 index 0000000..d918f96 --- /dev/null +++ b/base/src/test/test_extend.rs @@ -0,0 +1,106 @@ +#![allow(clippy::unwrap_used)] + +use crate::{ + expressions::types::{Area, CellReferenceIndex}, + test::util::new_empty_model, +}; + +#[test] +fn extend_to_basic() { + let mut model = new_empty_model(); + model._set("A1", "=B1*SUM(F5:H10)"); + + model.evaluate(); + + // A1 + let (sheet, row, column) = (0, 1, 1); + + // extend from A1 to A5 + let (target_row, target_column) = (5, 1); + let result = model + .extend_to(sheet, row, column, target_row, target_column) + .unwrap(); + assert_eq!(&result, "=B5*SUM(F9:H14)"); + + // extend from A1 to E1 + let (target_row, target_column) = (1, 5); + let result = model + .extend_to(sheet, row, column, target_row, target_column) + .unwrap(); + assert_eq!(&result, "=F1*SUM(J5:L10)"); +} + +#[test] +fn extend_to_no_formula() { + let mut model = new_empty_model(); + model._set("A1", "Hey Jude!"); + + model.evaluate(); + + // A1 + let (sheet, row, column) = (0, 1, 1); + + // extend from A1 to A5 + let (target_row, target_column) = (5, 1); + let result = model + .extend_to(sheet, row, column, target_row, target_column) + .unwrap(); + assert_eq!(&result, "Hey Jude!"); + + // extend from A1 to E1 + let (target_row, target_column) = (1, 5); + let result = model + .extend_to(sheet, row, column, target_row, target_column) + .unwrap(); + assert_eq!(&result, "Hey Jude!"); +} + +#[test] +fn extend_copied_value_basic() { + let mut model = new_empty_model(); + let source = CellReferenceIndex { + sheet: 0, + row: 1, + column: 1, + }; + let target = CellReferenceIndex { + sheet: 0, + row: 30, + column: 1, + }; + let result = model + .extend_copied_value("=B1*D4", &source, &target) + .unwrap(); + assert_eq!(&result, "=B30*D33"); + + let result = model + .extend_copied_value("don't make it sad", &source, &target) + .unwrap(); + assert_eq!(&result, "don't make it sad"); +} + +#[test] +fn move_cell_value_to_area_basic() { + let mut model = new_empty_model(); + let source = CellReferenceIndex { + sheet: 0, + row: 3, + column: 1, + }; + let target = CellReferenceIndex { + sheet: 0, + row: 50, + column: 1, + }; + let area = Area { + sheet: 0, + row: 1, + column: 1, + width: 5, + height: 4, + }; + let result = model + .move_cell_value_to_area("=B1", &source, &target, &area) + .unwrap(); + assert_eq!(&result, "=B48"); +}