feat(buffer): add Buffer::get_opt, get_mut_opt and index implementations

[joshka]

Code which previously called buf.get(x, y) or buf.get_mut(x, y) can
now use index operators, or be transitioned to buf_get_opt or
buf.get_mut_opt for safe access that avoids panics.

The new methods accept Into<Position> instead of x and y
coordinates, which makes them more ergonomic to use.

let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));

let cell = buf[(0, 0)];
let cell = buf[Position::new(0, 0)];

let symbol = buf.cell((0, 0)).map(|cell| cell.symbol());
let symbol = buf.cell(Position::new(0, 0)).map(|cell| cell.symbol());

buf[(0, 0)].set_symbol("🐀");
buf[Position::new(0, 0)].set_symbol("🐀");

buf.cell_mut((0, 0)).map(|cell| cell.set_symbol("🐀"));
buf.cell_mut(Position::new(0, 0)).map(|cell| cell.set_symbol("🐀"));

The existing get() and get_mut() methods are marked as deprecated.
I'd anticipate these are widely used and we should leave these methods
around on the buffer for a very long time (perhaps 3-4 major releases rather
than the normal 2).

Partially addresses #1011

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.2%. Comparing base (7a48c5b) to head (903eea1).

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #1084     +/-   ##
=======================================
- Coverage   94.2%   94.2%   -0.1%     
=======================================
  Files         60      60             
  Lines      14511   14566     +55     
=======================================
+ Hits       13672   13722     +50     
- Misses       839     844      +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[EdJoPaTo]

Is there a reason why this was not done with pos_of too?

#1049:

ratatui/src/buffer/buffer.rs

Lines 241 to 250 in 30a6fb2

	pub const fn pos_of_opt(&self, i: usize) -> Option<(u16, u16)> {
	if i < self.area.area() as usize {
	Some((
	self.area.x + (i as u16) % self.area.width,
	self.area.y + (i as u16) / self.area.width,
	))
	} else {
	None
	}
	}

[joshka]

Is there a reason why this was not done with pos_of too?

I don't think pos_of should be part of the API, and I'd prefer not to make it worse. (note the new index_of_opt method is private)

[kdheepak]

This looks good to me but maybe we can get more reviewers on this?

PR title + description should be updated.

[EdJoPaTo]

I like the usage of the Index trait. It is still panicking like before but should have the same performance.

[joshka]

I actually intended to put the deprecation of the existing methods in #1123, but accidentally pushed the commit to this PR. Happy to do it either way (though it would be easier at this point to just keep it in this PR and update the main PR comment.