fast_xlsx 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0642c1f4069d2b6537757d873ed2e591ddd3c7dab25f4bd1c867fad4fe8f0ead
-  data.tar.gz: d0b7696cc3ee573ec02821a3b210ef34ce68fb821c83666f2fa0938c8bbabc16
+  metadata.gz: 5f9a163e801092064c80b6b921d5ca3c75987420652654809e0fea86d957be4e
+  data.tar.gz: e96a6a4b451d600c982291d1a391787f767f4c4d7bf4126f309e8608de7dba76
 SHA512:
-  metadata.gz: 40fbd10f5ad43e8fc7a6bedccdc68cee4a324fa5ae9586dd7e9281272c6c2b1a465049c53fd67f042c9dffe00ca7c21c1512d4e1ffcbd01e2ea5ce52dc658938
-  data.tar.gz: 5a6ca0279e195f3b109d23f0bf1afbed5680c6f6fd844aa0e30411468e1f8d7203680d30bba838cdb15b2dfac1f9c170a9b9576ed5db0650439c331fd2ff11be
+  metadata.gz: 3bca3c0050c69442f2688c02def0a9733a0495f3059c28e539591751b01e36f7f2eecacad4d889d783c944dd4e17b61a26f1143939a955ca1b9a51432232a1f8
+  data.tar.gz: '09c47cee091843afb86a244e489b502df740bdea08633a06c9bdf8308c5a10a98ac7135d7ca62a8f6f0816bbda2ed1e52d88a7d2155e004672b116eb4ebc622b'

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [1.1.0] - 2026-11-03
+
+### Added
+
+- `Worksheet#embed_image` places an image in a cell, where it fits the cell and moves and sizes with it (Excel 365's "Place in Cell"; older Excel shows `#VALUE!`). It takes a path or an IO like `insert_image`, plus `alt_text:` and `format:`. It raises `FastXlsx::Error` in `memory: :constant` and `:low` mode, which rust_xlsxwriter does not support for embedded images.
+- `conditional_format` types `:top` and `:bottom` (`value:` count, or a percentage with `percent: true`), `:average` (`criteria: :above`, `:below`, `:above_or_equal`, `:below_or_equal`, and `std_dev: 1..3`), `:duplicate`, `:unique`, `:blank`, `:not_blank`, `:error`, `:not_error`, and `:date` (`criteria: :yesterday`, `:today`, `:tomorrow`, `:last_7_days`, `:last_week`, `:this_week`, `:next_week`, `:last_month`, `:this_month`, `:next_month`).
+- `conditional_format` type `:icon_set`, with `icons:` (e.g. `:three_arrows`, `:five_boxes`; default `:three_traffic_lights`), `reverse: true` and `icons_only: true`.
+- Custom colors for data bars and color scales: `type: :data_bar, color: "#63BE7B"`, and `type: :color_scale, colors: [min, max]` or `[min, mid, max]`. `colors: 2` and `3` work as before. A data bar's `color:` sets both its fill and its border.
+
+### Deprecated
+
+- `colors:` on `conditional_format` `type: :data_bar` was always ignored; it now prints a warning and will raise `ArgumentError` in 2.0. Use `color:` for the bar color.
+
 ## [1.0.0] - 2026-10-18
 
 The first stable release, with the same API as 0.8.1. From now on fast_xlsx follows Semantic Versioning: no breaking change before 2.0, and anything to be removed first prints a deprecation warning for at least one minor release.

data/Cargo.lock

@@ -207,9 +207,9 @@ checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
 [[package]]
 name = "magnus"
-version = "0.9.2"
+version = "0.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
+checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -353,9 +353,9 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rust_xlsxwriter"
-version = "0.100.0"
+version = "0.101.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c44904ffb6c57b148ffcc8ce3011c28bc49b97e1a8343b2d632283cd566e1393"
+checksum = "49aa1d1558e9465f5053bf9fb5361fe75db827c6a4423d5e5fe72096622f8908"
 dependencies = [
  "tempfile",
  "zip",

data/README.md

@@ -254,7 +254,7 @@ ws.autofilter(0..100, 0..3)   # rows and columns, each an Integer or a Range
 ws.merge_range(0, 0..3, "Q3 report", title) # row 1, columns A–D
 ```
 
-Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
+Methods that take one cell (`write`, `write_comment`, `insert_image`, `embed_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
 
 `autofit` only sees rows still in memory, so in `:constant` / `:low` memory mode it ignores rows already written to disk; set widths with `column_width` instead.
 
@@ -315,8 +315,14 @@ ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :<, value: 0, format:
 ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :between, value: [1, 10], format: red)
 ws.conditional_format(0, 0, 99, 0, type: :text, criteria: :contains, value: "error", format: red)
 ws.conditional_format(0, 0, 99, 3, type: :formula, value: "=$D1>100", format: red)
-ws.conditional_format(0, 2, 99, 2, type: :data_bar)
-ws.conditional_format(0, 2, 99, 2, type: :color_scale)            # 3-color; colors: 2 for 2-color
+ws.conditional_format(0, 1, 99, 1, type: :top, value: 10, format: red)  # or :bottom; percent: true for a %
+ws.conditional_format(0, 1, 99, 1, type: :average, criteria: :below, std_dev: 1, format: red)
+ws.conditional_format(0, 0, 99, 0, type: :duplicate, format: red)
+ws.conditional_format(0, 4, 99, 4, type: :date, criteria: :last_7_days, format: red)
+ws.conditional_format(0, 2, 99, 2, type: :data_bar)                       # or color: "#63BE7B"
+ws.conditional_format(0, 2, 99, 2, type: :color_scale)                    # 3-color; colors: 2 for 2-color
+ws.conditional_format(0, 2, 99, 2, type: :color_scale, colors: %w[#F8696B #FFEB84 #63BE7B]) # min, mid, max
+ws.conditional_format(0, 2, 99, 2, type: :icon_set, icons: :three_arrows) # reverse: true, icons_only: true
 ```
 
 | `type` | `criteria` | `value` |
@@ -324,7 +330,14 @@ ws.conditional_format(0, 2, 99, 2, type: :color_scale)            # 3-color; col
 | `:cell` | `:==`, `:!=`, `:>`, `:>=`, `:<`, `:<=`, `:between`, `:not_between` | number or string; `[min, max]` for the range criteria |
 | `:text` | `:contains`, `:not_contains`, `:begins_with`, `:ends_with` | string |
 | `:formula` | — | formula string, relative to the top-left cell |
+| `:top`, `:bottom` | — | how many, 1–1000 (default 10); with `percent: true`, a percentage 1–100 |
+| `:average` | `:above` (default), `:below`, `:above_or_equal`, `:below_or_equal`; `std_dev: 1`, `2` or `3` with `:above`/`:below` | — |
+| `:duplicate`, `:unique`, `:blank`, `:not_blank`, `:error`, `:not_error` | — | — |
+| `:date` | `:yesterday`, `:today`, `:tomorrow`, `:last_7_days`, `:last_week`, `:this_week`, `:next_week`, `:last_month`, `:this_month`, `:next_month` | — |
 | `:data_bar`, `:color_scale` | — | — |
+| `:icon_set` | — | — |
+
+Colors are `"#RRGGBB"` or `0xRRGGBB`. `:data_bar` takes `color:`, which sets both the bar's fill and its border; `:color_scale` takes `colors:`, either `2` or `3` or the 2 or 3 colors from minimum to maximum. `:icon_set` takes `icons:` (default `:three_traffic_lights`): `:three_arrows`, `:three_arrows_gray`, `:three_flags`, `:three_traffic_lights`, `:three_traffic_lights_with_rim`, `:three_signs`, `:three_symbols_circled`, `:three_symbols`, `:three_stars`, `:three_triangles`, `:four_arrows`, `:four_arrows_gray`, `:four_red_to_black`, `:four_histograms`, `:four_traffic_lights`, `:five_arrows`, `:five_arrows_gray`, `:five_histograms`, `:five_quadrants`, `:five_boxes`; `reverse: true` reverses their order and `icons_only: true` hides the cell values.
 
 ### Data validation
 
@@ -350,6 +363,7 @@ ws.write_comment(0, 0, "Checked by finance", author: "Zac")   # Excel shows it a
 ws.insert_image(0, 0, "logo.png")                                  # top-left corner in A1
 ws.insert_image(0, 5, StringIO.new(blob.download), scale: 0.5, x_offset: 10, y_offset: 4, alt_text: "Logo")
 ws.insert_image(10, 0, "chart.png", width: 320, height: 180)       # pixel size; one of them keeps the aspect ratio
+ws.embed_image("B12", "photo.png", alt_text: "Photo", format: { align: :center }) # in the cell, sized with it (Excel 365; not in memory: :constant/:low)
 ```
 
 A String is always treated as a path, so wrap raw bytes (such as Active Storage's `blob.download`) in a `StringIO`.

data/ext/fast_xlsx/Cargo.toml

@@ -14,7 +14,7 @@ magnus = { version = "0.9", features = ["rb-sys"] }
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
 # No "zlib" feature: without it zip compresses with zlib-rs, which saves
 # 20-30% faster than the system zlib (and needs no C library).
-rust_xlsxwriter = { version = "0.100.0", features = ["constant_memory"] }
+rust_xlsxwriter = { version = "0.101.0", features = ["constant_memory"] }
 
 [build-dependencies]
 rb-sys-env = "0.2.2"

data/ext/fast_xlsx/src/lib.rs

@@ -10,8 +10,12 @@ use magnus::{
 };
 use rust_xlsxwriter::{
     Color, ConditionalFormat, ConditionalFormat2ColorScale, ConditionalFormat3ColorScale,
+    ConditionalFormatAverage, ConditionalFormatAverageRule, ConditionalFormatBlank,
     ConditionalFormatCell, ConditionalFormatCellRule, ConditionalFormatDataBar,
-    ConditionalFormatFormula, ConditionalFormatText, ConditionalFormatTextRule,
+    ConditionalFormatDate, ConditionalFormatDateRule, ConditionalFormatDuplicate,
+    ConditionalFormatError, ConditionalFormatFormula, ConditionalFormatIconSet,
+    ConditionalFormatIconType, ConditionalFormatText,
+    ConditionalFormatTextRule, ConditionalFormatTop, ConditionalFormatTopRule,
     ConditionalFormatValue, DataValidation, DataValidationRule, FormatAlign, FormatBorder,
     FormatScript, FormatUnderline, IgnoreError, IntoDataValidationValue, IntoExcelData, XlsxError,
 };
@@ -1675,15 +1679,6 @@ impl Worksheet {
         lc: u16,
         options: RHash,
     ) -> Result<Obj<Self>, Error> {
-        check_keys(
-            ruby,
-            options,
-            &["type", "criteria", "value", "format", "colors"],
-            "conditional_format",
-        )?;
-        let format = opt::<&Format>(ruby, options, "format")?;
-        let value = raw_opt(ruby, options, "value");
-        let criteria = raw_opt(ruby, options, "criteria");
         let kind = choice(
             ruby,
             "conditional format type",
@@ -1694,8 +1689,72 @@ impl Worksheet {
                 ("formula", "formula"),
                 ("data_bar", "data_bar"),
                 ("color_scale", "color_scale"),
+                ("top", "top"),
+                ("bottom", "bottom"),
+                ("average", "average"),
+                ("duplicate", "duplicate"),
+                ("unique", "unique"),
+                ("blank", "blank"),
+                ("not_blank", "not_blank"),
+                ("error", "error"),
+                ("not_error", "not_error"),
+                ("date", "date"),
+                ("icon_set", "icon_set"),
             ],
         )?;
+        // Each type takes only the options it uses, except the types released
+        // before :top etc., which keep ignoring unused options (SemVer).
+        let allowed: &[&str] = match kind {
+            "top" | "bottom" => &["type", "value", "percent", "format"],
+            "average" => &["type", "criteria", "std_dev", "format"],
+            "date" => &["type", "criteria", "format"],
+            "duplicate" | "unique" | "blank" | "not_blank" | "error" | "not_error" => {
+                &["type", "format"]
+            }
+            "icon_set" => &["type", "icons", "reverse", "icons_only"],
+            // colors: is deprecated on :data_bar; the Ruby wrapper warns and drops it.
+            "data_bar" => &["type", "criteria", "value", "format", "color"],
+            _ => &["type", "criteria", "value", "format", "colors"],
+        };
+        check_keys(ruby, options, allowed, &format!("conditional_format :{kind}"))?;
+        let format = opt::<&Format>(ruby, options, "format")?;
+        let value = raw_opt(ruby, options, "value");
+        let criteria = raw_opt(ruby, options, "criteria");
+        // A whole number in `range`: other numbers raise ArgumentError with
+        // `hint`, non-numbers TypeError.
+        let whole = |v: Value, name: &str, range: std::ops::RangeInclusive<f64>, hint: &str| {
+            let n = f64::try_convert(v)?;
+            if n.fract() == 0.0 && range.contains(&n) {
+                Ok(n as u16)
+            } else {
+                Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!("invalid {name} {}: {hint}", v.inspect()),
+                ))
+            }
+        };
+        // A color for the options added after 1.0, which raise TypeError for a
+        // non-color type (Format keeps its released ArgumentError).
+        let new_color = |c: Value| {
+            if Integer::from_value(c).is_none() && RString::from_value(c).is_none() {
+                return Err(Error::new(
+                    ruby.exception_type_error(),
+                    format!("invalid color {}: use \"#RRGGBB\" or 0xRRGGBB", c.inspect()),
+                ));
+            }
+            color(ruby, c)
+        };
+        // true or false (nil when not given); other values raise TypeError.
+        let flag = |name: &str| {
+            let v = raw_opt(ruby, options, name);
+            if v.to_bool() && !v.is_kind_of(ruby.class_true_class()) {
+                return Err(Error::new(
+                    ruby.exception_type_error(),
+                    format!("invalid {name} {}: use true or false", v.inspect()),
+                ));
+            }
+            Ok(v.to_bool())
+        };
         // Built before taking the lock: building converts Ruby values.
         type AddRule = Box<dyn FnOnce(&mut rust_xlsxwriter::Worksheet) -> Result<(), XlsxError>>;
         fn rule<T: ConditionalFormat + Send + Sync + 'static>(
@@ -1705,14 +1764,21 @@ impl Worksheet {
             Box::new(move |ws| ws.add_conditional_format(fr, fc, lr, lc, &cf).map(|_| ()))
         }
         let range = (fr, fc, lr, lc);
+        // The rule for a conditional format that takes format:.
+        macro_rules! formatted {
+            ($cf:expr) => {
+                rule(
+                    range,
+                    match format {
+                        Some(f) => $cf.set_format(&f.0.format),
+                        None => $cf,
+                    },
+                )
+            };
+        }
         let add_rule = match kind {
             "cell" => {
-                let mut cf =
-                    ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?);
-                if let Some(f) = format {
-                    cf = cf.set_format(&f.0.format);
-                }
-                rule(range, cf)
+                formatted!(ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?))
             }
             "text" => {
                 let text = String::try_convert(value)?;
@@ -1732,31 +1798,204 @@ impl Worksheet {
                     2 => ConditionalFormatTextRule::BeginsWith(text),
                     _ => ConditionalFormatTextRule::EndsWith(text),
                 };
-                let mut cf = ConditionalFormatText::new().set_rule(text_rule);
-                if let Some(f) = format {
-                    cf = cf.set_format(&f.0.format);
-                }
-                rule(range, cf)
+                formatted!(ConditionalFormatText::new().set_rule(text_rule))
+            }
+            "formula" => formatted!(
+                ConditionalFormatFormula::new().set_rule(String::try_convert(value)?.as_str())
+            ),
+            "top" | "bottom" => {
+                let percent = raw_opt(ruby, options, "percent").to_bool();
+                let max = if percent { 100.0 } else { 1000.0 };
+                let n = if value.is_nil() {
+                    10
+                } else {
+                    whole(value, &format!("{kind} value"), 1.0..=max, &format!("use 1..{max}"))?
+                };
+                let top_rule = match (kind, percent) {
+                    ("top", false) => ConditionalFormatTopRule::Top(n),
+                    ("top", true) => ConditionalFormatTopRule::TopPercent(n),
+                    (_, false) => ConditionalFormatTopRule::Bottom(n),
+                    (_, true) => ConditionalFormatTopRule::BottomPercent(n),
+                };
+                formatted!(ConditionalFormatTop::new().set_rule(top_rule))
+            }
+            "average" => {
+                use ConditionalFormatAverageRule as A;
+                // The rule without std_dev, and its 1, 2 and 3 std_dev variants.
+                let above = (
+                    A::AboveAverage,
+                    Some([
+                        A::OneStandardDeviationAbove,
+                        A::TwoStandardDeviationsAbove,
+                        A::ThreeStandardDeviationsAbove,
+                    ]),
+                );
+                let (plain, deviations) = if criteria.is_nil() {
+                    above
+                } else {
+                    choice(
+                        ruby,
+                        "average criteria",
+                        criteria,
+                        &[
+                            ("above", above),
+                            (
+                                "below",
+                                (
+                                    A::BelowAverage,
+                                    Some([
+                                        A::OneStandardDeviationBelow,
+                                        A::TwoStandardDeviationsBelow,
+                                        A::ThreeStandardDeviationsBelow,
+                                    ]),
+                                ),
+                            ),
+                            ("above_or_equal", (A::EqualOrAboveAverage, None)),
+                            ("below_or_equal", (A::EqualOrBelowAverage, None)),
+                        ],
+                    )?
+                };
+                let std_dev = raw_opt(ruby, options, "std_dev");
+                let hint = "use 1, 2 or 3, with criteria :above or :below";
+                let average_rule = match (std_dev.is_nil(), deviations) {
+                    (true, _) => plain,
+                    (false, Some([one, two, three])) => {
+                        match whole(std_dev, "std_dev", 1.0..=3.0, hint)? {
+                            1 => one,
+                            2 => two,
+                            _ => three,
+                        }
+                    }
+                    (false, None) => {
+                        return Err(Error::new(
+                            ruby.exception_arg_error(),
+                            format!("invalid std_dev {}: {hint}", std_dev.inspect()),
+                        ))
+                    }
+                };
+                formatted!(ConditionalFormatAverage::new().set_rule(average_rule))
+            }
+            "duplicate" => formatted!(ConditionalFormatDuplicate::new()),
+            "unique" => formatted!(ConditionalFormatDuplicate::new().invert()),
+            "blank" => formatted!(ConditionalFormatBlank::new()),
+            "not_blank" => formatted!(ConditionalFormatBlank::new().invert()),
+            "error" => formatted!(ConditionalFormatError::new()),
+            "not_error" => formatted!(ConditionalFormatError::new().invert()),
+            "date" => {
+                use ConditionalFormatDateRule as D;
+                let period = choice(
+                    ruby,
+                    "date criteria",
+                    criteria,
+                    &[
+                        ("yesterday", D::Yesterday),
+                        ("today", D::Today),
+                        ("tomorrow", D::Tomorrow),
+                        ("last_7_days", D::Last7Days),
+                        ("last_week", D::LastWeek),
+                        ("this_week", D::ThisWeek),
+                        ("next_week", D::NextWeek),
+                        ("last_month", D::LastMonth),
+                        ("this_month", D::ThisMonth),
+                        ("next_month", D::NextMonth),
+                    ],
+                )?;
+                formatted!(ConditionalFormatDate::new().set_rule(period))
             }
-            "formula" => {
-                let mut cf =
-                    ConditionalFormatFormula::new().set_rule(String::try_convert(value)?.as_str());
-                if let Some(f) = format {
-                    cf = cf.set_format(&f.0.format);
+            "data_bar" => {
+                let bar = ConditionalFormatDataBar::new();
+                match raw_opt(ruby, options, "color") {
+                    c if c.is_nil() => rule(range, bar),
+                    c => rule(range, bar.set_fill_color(new_color(c)?)),
                 }
-                rule(range, cf)
             }
-            "data_bar" => rule(range, ConditionalFormatDataBar::new()),
-            _ => match opt::<u8>(ruby, options, "colors")?.unwrap_or(3) {
-                2 => rule(range, ConditionalFormat2ColorScale::new()),
-                3 => rule(range, ConditionalFormat3ColorScale::new()),
-                n => {
-                    return Err(Error::new(
+            "icon_set" => {
+                use ConditionalFormatIconType as I;
+                let icons = raw_opt(ruby, options, "icons");
+                let icon_type = if icons.is_nil() {
+                    I::ThreeTrafficLights
+                } else {
+                    choice(
+                        ruby,
+                        "icons",
+                        icons,
+                        &[
+                            ("three_arrows", I::ThreeArrows),
+                            ("three_arrows_gray", I::ThreeArrowsGray),
+                            ("three_flags", I::ThreeFlags),
+                            ("three_traffic_lights", I::ThreeTrafficLights),
+                            ("three_traffic_lights_with_rim", I::ThreeTrafficLightsWithRim),
+                            ("three_signs", I::ThreeSigns),
+                            ("three_symbols_circled", I::ThreeSymbolsCircled),
+                            ("three_symbols", I::ThreeSymbols),
+                            ("three_stars", I::ThreeStars),
+                            ("three_triangles", I::ThreeTriangles),
+                            ("four_arrows", I::FourArrows),
+                            ("four_arrows_gray", I::FourArrowsGray),
+                            ("four_red_to_black", I::FourRedToBlack),
+                            ("four_histograms", I::FourHistograms),
+                            ("four_traffic_lights", I::FourTrafficLights),
+                            ("five_arrows", I::FiveArrows),
+                            ("five_arrows_gray", I::FiveArrowsGray),
+                            ("five_histograms", I::FiveHistograms),
+                            ("five_quadrants", I::FiveQuadrants),
+                            ("five_boxes", I::FiveBoxes),
+                        ],
+                    )?
+                };
+                rule(
+                    range,
+                    ConditionalFormatIconSet::new()
+                        .set_icon_type(icon_type)
+                        .reverse_icons(flag("reverse")?)
+                        .show_icons_only(flag("icons_only")?),
+                )
+            }
+            _ => {
+                // colors: is how many (2 or 3), or the colors from minimum to maximum.
+                let colors = raw_opt(ruby, options, "colors");
+                let list = match RArray::from_value(colors) {
+                    Some(items) => {
+                        let mut list = Vec::with_capacity(items.len());
+                        each_entry(items, |_, c| {
+                            list.push(new_color(c)?);
+                            Ok(())
+                        })?;
+                        Some(list)
+                    }
+                    None => None,
+                };
+                let invalid = || {
+                    Error::new(
                         ruby.exception_arg_error(),
-                        format!("invalid colors {n}: use 2 or 3"),
-                    ))
+                        format!(
+                            "invalid colors {}: use 2 or 3, or an Array of 2 or 3 colors",
+                            colors.inspect()
+                        ),
+                    )
+                };
+                match list.as_deref() {
+                    Some(&[min, max]) => rule(
+                        range,
+                        ConditionalFormat2ColorScale::new()
+                            .set_minimum_color(min)
+                            .set_maximum_color(max),
+                    ),
+                    Some(&[min, mid, max]) => rule(
+                        range,
+                        ConditionalFormat3ColorScale::new()
+                            .set_minimum_color(min)
+                            .set_midpoint_color(mid)
+                            .set_maximum_color(max),
+                    ),
+                    Some(_) => return Err(invalid()),
+                    None => match opt::<u8>(ruby, options, "colors")?.unwrap_or(3) {
+                        2 => rule(range, ConditionalFormat2ColorScale::new()),
+                        3 => rule(range, ConditionalFormat3ColorScale::new()),
+                        _ => return Err(invalid()),
+                    },
                 }
-            },
+            }
         };
         rb_self.with_ws(|ws| add_rule(ws).map_err(xerr))?;
         Ok(rb_self)
@@ -1911,6 +2150,54 @@ impl Worksheet {
         Ok(rb_self)
     }
 
+    fn embed_image(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        row: u32,
+        col: u16,
+        bytes: RString,
+        alt_text: Option<String>,
+        format: Option<&Format>,
+    ) -> Result<Obj<Self>, Error> {
+        // rust_xlsxwriter numbers embedded images only when saving, and panics
+        // if it writes the cell to disk before that.
+        if rb_self.flushes_rows {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                "embed_image is not supported in constant_memory / low_memory mode",
+            ));
+        }
+        // SAFETY: the bytes are copied into the Image before any Ruby code runs.
+        let mut image = Image::new_from_buffer(unsafe { bytes.as_slice() }).map_err(xerr)?;
+        if let Some(alt_text) = alt_text {
+            image = image.set_alt_text(alt_text);
+        }
+        let tables = rb_self.table_formats.borrow();
+        let rows = rb_self.formatted_rows.borrow();
+        let columns = rb_self.formatted_columns.borrow();
+        // As in write(): an image is never a date, so with no format of its
+        // own it takes its table column's, if any.
+        let format = Self::format_for(
+            &tables,
+            &rows,
+            &columns,
+            row,
+            col,
+            format.map(|f| &*f.0),
+            &CellValue::Empty,
+        );
+        rb_self.with_ws(|ws| {
+            match format {
+                Some(f) => ws.embed_image_with_format(row, col, &image, f),
+                None => ws.embed_image(row, col, &image),
+            }
+            .map(|_| ())
+            .map_err(xerr)
+        })?;
+        rb_self.advance(row);
+        Ok(rb_self)
+    }
+
     fn insert_chart(
         ruby: &Ruby,
         rb_self: Obj<Self>,
@@ -2287,6 +2574,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     ws.define_method("name", method!(Worksheet::name, 0))?;
     ws.define_method("_write_comment", method!(Worksheet::write_comment, 4))?;
     ws.define_method("_insert_image", method!(Worksheet::insert_image, 4))?;
+    ws.define_method("_embed_image", method!(Worksheet::embed_image, 5))?;
     ws.define_method("_insert_chart", method!(Worksheet::insert_chart, 3))?;
     ws.define_method("_add_table", method!(Worksheet::add_table, 5))?;
     ws.define_method(

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/fast_xlsx.rb

@@ -269,6 +269,13 @@ module FastXlsx
     end
     private :_write_ref
 
+    # [row, col, image bytes] from insert_image's and embed_image's (*cell, source).
+    def image_args(args)
+      row, col, (source, *) = CellRange.cell(args, 1..1)
+      [row, col, source.respond_to?(:read) ? source.read : File.binread(source)]
+    end
+    private :image_args
+
     # Writes one cell: ws["B2"] = 42 or ws[1, 1] = 42. Use {#write} to give
     # it a format.
     # @overload []=(ref, value)
@@ -330,14 +337,30 @@ module FastXlsx
     # Highlights cells in the range by rule; see the README for each type's
     # options.
     # @param range a cell range (see {Worksheet})
-    # @param type [Symbol] :cell, :text, :formula, :data_bar or :color_scale
-    # @option options [Symbol] :criteria e.g. :>, :between, :contains
-    # @option options [Numeric, String, Array] :value
+    # @param type [Symbol] :cell, :text, :formula, :top, :bottom, :average,
+    #   :duplicate, :unique, :blank, :not_blank, :error, :not_error, :date,
+    #   :data_bar, :color_scale or :icon_set
+    # @option options [Symbol] :criteria e.g. :>, :between, :contains,
+    #   :below (:average), :last_7_days (:date)
+    # @option options [Numeric, String, Array] :value (:top and :bottom: how many, default 10)
     # @option options [Format, Hash] :format
-    # @option options [Integer] :colors 2 or 3 (:color_scale)
+    # @option options [Boolean] :percent value is a percentage (:top, :bottom)
+    # @option options [Integer] :std_dev 1, 2 or 3 standard deviations (:average)
+    # @option options [Integer, Array] :colors 2 or 3, or the 2 or 3 colors
+    #   ("#RRGGBB" or 0xRRGGBB) from minimum to maximum (:color_scale)
+    # @option options [String, Integer] :color bar fill and border color,
+    #   "#RRGGBB" or 0xRRGGBB (:data_bar)
+    # @option options [Symbol] :icons e.g. :three_arrows, :five_boxes; default
+    #   :three_traffic_lights (:icon_set)
+    # @option options [Boolean] :reverse reverse the order of the icons (:icon_set)
+    # @option options [Boolean] :icons_only hide the cell values (:icon_set)
     # @return [self]
     def conditional_format(*range, type:, **options)
       options[:format] = Format._coerce(options[:format]) if options.key?(:format)
+      if type == :data_bar && options.key?(:colors)
+        warn "fast_xlsx: colors: is ignored on :data_bar and will raise in 2.0; use color:", uplevel: 1
+        options.delete(:colors)
+      end
       _conditional_format(*CellRange.split(range).first, { type: type, **options })
     end
 
@@ -370,9 +393,20 @@ module FastXlsx
     # @return [self]
     # @raise [FastXlsx::Error] for data that isn't a supported image
     def insert_image(*args, **)
-      row, col, (source, *) = CellRange.cell(args, 1..1)
-      bytes = source.respond_to?(:read) ? source.read : File.binread(source)
-      _insert_image(row, col, bytes, { ** })
+      _insert_image(*image_args(args), { ** })
+    end
+
+    # Embeds a PNG, JPEG, GIF or BMP image in the cell, where it fits the cell
+    # and moves and sizes with it (Excel 365's "Place in Cell"; older Excel
+    # shows #VALUE!). Not available in memory: :constant or :low mode.
+    # @overload embed_image(*cell, source, alt_text: nil, format: nil)
+    #   @param source [String, #read] a file path or an IO
+    #   @param alt_text [String, nil]
+    #   @param format [Format, Hash, nil] the cell's format, e.g. to center the image
+    # @return [self]
+    # @raise [FastXlsx::Error] for data that isn't a supported image, or in those modes
+    def embed_image(*args, alt_text: nil, format: nil)
+      _embed_image(*image_args(args), alt_text, Format._coerce(format))
     end
 
     # Inserts a chart with its top-left corner in the cell.

data/sig/fast_xlsx.rbs

@@ -124,9 +124,18 @@ module FastXlsx
                    | (indexes rows, indexes cols, cell value, ?format? format) -> self
                    | (*cell_range | cell args, format: format?) -> self
     def conditional_format: (*cell_range range,
-                             type: :cell | :text | :formula | :data_bar | :color_scale,
+                             type: :cell | :text | :formula | :top | :bottom | :average | :duplicate | :unique
+                                 | :blank | :not_blank | :error | :not_error | :date | :data_bar | :color_scale
+                                 | :icon_set,
                              ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
-                             ?format: format, ?colors: 2 | 3) -> self
+                             ?format: format, ?percent: bool, ?std_dev: 1 | 2 | 3,
+                             ?colors: 2 | 3 | Array[Format::color], ?color: Format::color,
+                             ?icons: icon_type, ?reverse: bool, ?icons_only: bool) -> self
+    type icon_type = :three_arrows | :three_arrows_gray | :three_flags | :three_traffic_lights
+                   | :three_traffic_lights_with_rim | :three_signs | :three_symbols_circled | :three_symbols
+                   | :three_stars | :three_triangles | :four_arrows | :four_arrows_gray | :four_red_to_black
+                   | :four_histograms | :four_traffic_lights | :five_arrows | :five_arrows_gray
+                   | :five_histograms | :five_quadrants | :five_boxes
     def data_validation: (*cell_range range,
                           type: :list | :whole_number | :decimal | :text_length,
                           ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
@@ -138,6 +147,8 @@ module FastXlsx
                        ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
                     | (String cell, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
                        ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
+    def embed_image: (Integer row, Integer col, String | _Reader source, ?alt_text: String?, ?format: format?) -> self
+                   | (String cell, String | _Reader source, ?alt_text: String?, ?format: format?) -> self
     type chart_series = { values: String, ?categories: String, ?name: String }
 
     def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Zac