A library for parsing to and from A1 spreadsheet notation. A1 notation uses letters A-Z for
columns and a one-based number for the row. So for example at position (0, 0) of a spreadsheet
(the top left corner) is "A1". (1, 1) is "B2", (1, 0) is "B1", etc.
A1sThe most common need is to parse a string:
```rust let a1 = A1::fromstr("A1").unwrap(); // it parses it into an instance: asserteq!(a1, A1 { sheetname: None, reference: RangeOrCell::Cell(Address { column: Column { absolute: false, x: 0 }, row: Row { absolute: false, y: 0 }, }), }); // and can display it back: asserteq!(&a1.to_string(), "A1");
// you can also just call a1_notation::new:
let fromcolatod = a1notation::new("Foo!A:D").unwrap();
asserteq!(fromcolatod,
A1 {
sheetname: Some("Foo".tostring()),
reference: RangeOrCell::ColumnRange {
from: Column { absolute: false, x: 0 },
to: Column { absolute: false, x: 3 },
},
});
asserteq!(&fromcolatod.tostring(), "Foo!A:D"); ```
If you have zero-based coordinates and want to represent them as A1, there are several fns
for instantiating:
```rust // to create a reference to a specific cell: asserteq!(&a1notation::cell(2, 2).to_string(), "C3");
// a reference to an entire column asserteq!(&a1notation::column(5).to_string(), "F:F");
// or an entire row asserteq!(&a1notation::row(5).to_string(), "6:6");
// and finally a range between two cells: asserteq!(&a1notation::range((0, 0), (4, 4)).to_string(), "A1:E5"); ```
Given all the various combinations or cells, ranges, row ranges, column ranges and non-contiguous ranges you can calculate if one reference contains another.
```rust // a column contains any cell in that column: let cola = a1notation::new("A:A").unwrap(); let a1 = a1notation::new("A1").unwrap(); assert!(cola.contains(&a1));
// likewise, a row range contains anything between it: let top5rows = a1notation::new("1:5").unwrap(); let b2 = a1notation::new("B2").unwrap(); assert!(top5rows.contains(&b2));
// and a range between two points works as you'd expect (it forms a rectangle) let c3toj20 = a1notation::new("C3:J20").unwrap(); let d5 = a1notation::new("D5").unwrap(); assert!(c3toj20.contains(&d5)); ```
As much as possible it implements Into/From and AsRef to convert between the various
structs. Generally you can go from more specific to less specific but not the other way
around. You typically should work with A1 structs but you can also use these traits to work
with these lower level ones and cast them upwards.
```rust // an address can act as a column or row using AsRef: let a1 = Address::new(0, 0); asserteq!(&Column::new(0), a1.asref()); asserteq!(&Row::new(0), a1.asref());
// addresses, columns and rows can into() "upwards" to an A1 or RangeOrCell
let colb = Column::new(1);
asserteq!(
RangeOrCell::ColumnRange {
from: Column::new(1),
to: Column::new(1),
},
col_b.into());
asserteq!( A1 { sheetname: None, reference: RangeOrCell::ColumnRange { from: Column::new(1), to: Column::new(1), }, }, col_b.into()); ```
You can move references (and ranges) around:
rust
// A1 -> D1 -> D3 -> C3
assert_eq!(
&a1_notation::cell(0, 0)
.shift_right(3)
.shift_down(2)
.shift_left(1)
.to_string(),
"C3");
You can iterate through the various types of ranges.
```rust
// a cell just emits itself (once)
asserteq!(
a1notation::cell(0, 0)
.iter().map(|r| r.to_string()).collect::
// a column range iterates column-wise
asserteq!(
a1notation::new("D:G").unwrap()
.iter().map(|r| r.to_string()).collect::
// and a row range goes row-wise
asserteq!(
a1notation::new("3:6").unwrap()
.iter().map(|r| r.to_string()).collect::
// a grid-based range goes row-by-row
asserteq!(
a1notation::new("A1:C3").unwrap()
.iter().map(|r| r.to_string()).collect::
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.