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.get_opt((0, 0)).map(|cell| cell.symbol());
let symbol = buf.get_opt(Position::new(0, 0)).map(|cell| cell.symbol());

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

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

Partially addresses #1011

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.2%. Comparing base (bf20369) to head (a7dbc24).

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #1084     +/-   ##
=======================================
- Coverage   94.3%   94.2%   -0.1%     
=======================================
  Files         61      61             
  Lines      14771   14826     +55     
=======================================
+ Hits       13930   13977     +47     
- Misses       841     849      +8     

☔ 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
	}
	}

[EdJoPaTo]

Increase readability by clarifying what exactly is implemented here inline. When first reading this I thought there is yet another ratatui trait. (same for IndexMut)

Suggested change

	impl<P: Into<Position>> Index<P> for Buffer {
	impl<P: Into<Position>> std::ops::Index<P> for Buffer {

[joshka]

I changed this back to just Index as the trait has to be in scope for links to a trait defined method in a doc comment to resolve correctly.

[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.

[EdJoPaTo]

Not sure whether I would keep this comment… either Index is used or cell. The latter has easy viewable documentation, so this comment doesn't provide much use. It would be more useful on using the index but documenting it is harder there 🤔

[joshka]

Replacing this with some better docs in the next commit.

[joshka]

7e0b6e4

[EdJoPaTo]

This and other methods here could get a #[must_use].

[joshka]

Done

[EdJoPaTo]

area and content also look like must_use candidates… Guess we should get that lint enabled for the full repo

[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.