github workflow crates.io

a1_notation

A Rust crate for manipulating and parsing to and from A1 notation. A1 notation is what you typically see in spreadsheets where the first cell (at (0, 0)) is referred to as cell A1 where A represents the first column (0) and 1 represents the first row.

You can parse an A1-notation value using the FromStr trait or the new function:

```rust let b5 = a1_notation::new("B5").unwrap();

asserteq!(b5.x(), Some(1)); asserteq!(b5.y(), Some(4)); ```

Creating a new A1

There are several functions you can use to create an A1:

```rust // from a &str let a1 = a1_notation::new("Foo!A1").unwrap();

asserteq!(A1 { sheetname: Some("Foo".tostring()), reference: RangeOrCell::Cell(Position::Absolute(0, 0)), }, a1); asserteq!("Foo!A1", a1.to_string());

// from an x/y let b2 = a1_notation::cell(1, 1);

asserteq!(A1 { sheetname: None, reference: RangeOrCell::Cell(Position::Absolute(1, 1)), }, b2); asserteq!("B2", b2.tostring());

// a column reference (an x but no y) let colc = a1notation::column(2);

asserteq!(A1 { sheetname: None, reference: RangeOrCell::Cell(Position::ColumnRelative(2)), }, colc); asserteq!("C:C", colc.tostring());

// a row reference (a y but no x) let row4 = a1notation::row(3);

asserteq!("4:4", row4.to_string()); ```

Manipulating an A1

Once you have an A1, you can shift/move it around using shift_up, shift_down, shift_left and shift_right:

```rust let a1 = a1notation::new("A1").unwrap(); asserteq!(a1.shiftdown(2).tostring(), "A3");

let b2 = a1notation::new("B2").unwrap(); asserteq!(b2.shiftdown(2).shiftright(3).shiftup(1).tostring(), "E3"); ```

And explicitly set it's X or Y components or sheetname: ```rust let a1 = a1notation::new("A1").unwrap(); asserteq!("F1", a1.withx(5).to_string());

let c3 = a1notation::new("C3").unwrap(); asserteq!("C6", c3.withy(5).tostring());

let infoosheet = a1notation::new("Foo!B22").unwrap(); // change the sheet name: asserteq!("Bar!B22".tostring(), infoosheet.clone().withsheetname("Bar").tostring()); // or remove it: asserteq!("B22".tostring(), infoosheet.clone().withoutsheetname().to_string()); ```

Builder

You can call the builder to build a more complex reference (with sheet name, range, etc):

```rust let a1absolute = A1::builder() .xy(0, 0) .sheetname("Importantstuff") .build() .unwrap(); // Cell A1 asserteq!(a1absolute.tostring(), "Important_stuff!A1");

let a1relative = A1::builder().x(0).build().unwrap(); // Column A asserteq!(a1relative.tostring(), "A:A");

let a1range = A1::builder() .range() .from(A1::builder().x(0).build().unwrap()) .to(A1::builder().x(3).build().unwrap()) .build() .unwrap(); // Range A:D asserteq!(a1range.tostring(), "A:D"); ```

A1 Reference Examples

Here is a table illustrating A1 references:

| Reference | Meaning | |:----------------|:--------------------------| | "A1" | Cell A1 | | "A1:B5" | Cells A1 through B5 | | "C5:D9,G9:H16"| A multiple-area selection | | "A:A" | Column A | | "1:1" | Row 1 | | "A:C" | Columns A through C | | "1:5" | Rows 1 through 5 | | "1:1,3:3,8:8" | Rows 1, 3, and 8 | | "A:A,C:C,F:F" | Columns A, C, and F |

For more info take a look at the package on crates.io and it's Rust docs.

Additional Reading