Small DX changes + more docs

[chanced]

• renames PointerBuf::replace_token to replace, ReplaceTokenError to ReplaceError
• changes PointerBuf::push_back, PointerBuf::push_front, PointerBuf::replace to accept T: Into<Token>
• implements From all integer types for Token
• cleans up and adds docs

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.1%. Comparing base (02e1b95) to head (5e6097b).
Report is 5 commits behind head on main.

Additional details and impacted files

Files with missing lines	Coverage Δ
src/index.rs	100.0% <ø> (ø)
src/pointer.rs	98.1% <100.0%> (+<0.1%)	⬆️
src/token.rs	100.0% <100.0%> (ø)

[chanced]

@asmello any objection to renaming replace_token to replace, ReplaceTokenError to ReplaceError? All other methods omit token so I figured it'd align a bit better. The only hesitation I have is that replace for string types may give a slightly different expectation.

Also, do you have any opposition to me implementing PartialEq<&str> for Token (using the decoded value)?

edit: motivation for the PartialEq was for this doc example:

let ptr = Pointer::from_static("/path/to/value");
let tokens: Vec<_> = ptr.tokens().collect();
assert_eq!(tokens, vec!["path", "to", "value"]);

vs

let ptr = Pointer::from_static("/path/to/value");
let tokens: Vec<_> = ptr.tokens().collect();
assert_eq!(tokens, vec![Token::new("path"), Token::new("to"), Token::new("value")]);

[chanced]

This PR will be the second to last I want to finish.

The next will contain a small change to Component, adding offset as well as adding walk_to / walk_form to Resolve with provided implementations.

[asmello]

Also, do you have any opposition to me implementing PartialEq<&str> for Token (using the decoded value)?

I'm a bit on the fence on this one. While the improved ergonomics is nice, I'm a little afraid people won't realise that it uses the encoded version until they run into an unexpected edge case at runtime. Seems a bit error prone. By forcing straight Token and Token comparison there's no room for error.

I can change my mind on this, if it turns out to be a major pain point, but I'd err on the side of safety at first.

EDIT: forgot to say, happy with the renames, didn't notice the inconsistency 👍

[chanced]

Sounds good to me.

…

On Tue, Jul 9, 2024 at 2:44 PM André Mello ***@***.***> wrote: Also, do you have any opposition to me implementing PartialEq<&str> for Token (using the decoded value)? I'm a bit on the fence on this one. While the improved ergonomics is nice, I'm a little afraid people won't realise that it uses the encoded version until they run into an unexpected edge case at runtime. Seems a bit error prone. By forcing straight Token and Token comparison there's no room for error. I can change my mind on this, if it turns out to be a major pain point, but I'd err on the side of safety at first. — Reply to this email directly, view it on GitHub <#61 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIGFZCVPGJLST2VZB7YNNDZLQVQJAVCNFSM6AAAAABKTH5CM6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMJYGQYDOMJYHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[asmello]

Also worth adding a comment so we remember we deliberately chose not to implement this.

[chanced]

@asmello i went ahead and removed serde from Token.

[asmello]

@asmello i went ahead and removed serde from Token.

Cool, I think that's reasonable. It's not immediately useful and there's ambiguity with encoding. 👍