Punching through uniffi to expose the cursor API

[munhitsu]

exposing the Cursor API

[alexjg]

Nice! The code LGTM. We may want a little more context in the docs about when one might need a cursor etc, @heckj thoughts?

[heckj]

A minor fiddly bit on the how the test is constructed, but otherwise the content looks good. This PR is aimed at that alpha branch though, but anything incoming should be aimed at the main branch, and after it's landed, I can cherry pick the relevant commit back in the alpha branch and cut a new XCFramework and pre-release 0.5.x version.

I'm not fussed about the relative lack of documentation - I'm right in the middle of a big rebuild of the documentation, so it will be easy for me to integrate this in after we land the PR.

[heckj]

I know a lot of the legacy tests in this repo use the force unwrapping of try statements (try!), but as a general pattern its far easier to diagnose test errors if the test itself is throwing, and then you don't need to wrap the try with !.

[heckj]

Question about Cursor - I get how it works based on the tests provided, but wanted to verify a few details:

• Cursor works for both .Text objects and .List objects - it just happens to be more obviously useful for Text cursor tracking
• Cursor also updates its position if/when you invoke "insert" to add an item to a list
• There is no "default" cursor that you can retrieve from either Text or List objects - you have to manually set it at some point in time, and it updates with the changes from there
• If a cursor is near the end of a list, and you spliceText/delete the last word, including where the cursor previously pointed, the cursor position updates to the UTF-8 index end of the text

And a question - as much for @munhitsu as @alexjg - right now we leave the whole tracking of a UTF-8view of a Swift String to the developer to manage the positioning in and out, ignoring the Character indexes (which point to full glyphs, not UTF8 index positions). Would it make sense to have an initializer on Cursor, referencing the Character Index within the String of the .Text object, that we automagically convert to a UTF-8 position when initializing the cursor to better developer ergonomics?

[alexjg]

Correct on all four points. The idea of a "default" cursor is interesting, that would be the start of the sequence?

As to the character index stuff, that makes a lot of sense. Can it be done efficiently? Do you not need to track the state of the "current" version of the text in order to translate to UTF-8 indexes?

[heckj]

The idea of a "default" cursor is interesting, that would be the start of the sequence?

That was sort of the idea that I was starting with, and maybe exposing Cursor as an additional property on the higher-level AutomergeText object, initializing it to index 0 as a starting point. That said, I'm not sure if that makes sense in the scenario where you've created a .Text object, but not added any data into it yet. The cursor would, at that point, be at an invalid position as far as I could see. (Haven't tried anything experimental yet, just thinking through it)

As to the character index stuff, that makes a lot of sense. Can it be done efficiently? Do you not need to track the state of the "current" version of the text in order to translate to UTF-8 indexes?

My biggest concern is the whole "one glyph being multiple UTF-8 code points" scenario with String and UTF-8 positions. I think it makes a HUGE amount of sense to let the cursor shift with Automerge's updates, but when initializing a cursor from a Swift string value, using the character index from the current-value of string to convert into the UTF-8 view to get that appropriate index. If I recall correctly, there's a conversion method within String that lets you convert String.Index to String.UTF8View.Index pretty easily.

[heckj]

@munhitsu I'm closing this PR and replacing it with #70, which targets the main branch. I cherry picked your commits over to that branch, then added some additional documentation.

[munhitsu]

If ever you want to get back to the idea of having the default cursor then bear in mind that UITextField thinks in terms of NSRange. This means 2 cursors.
Using the Cursor in anger made me also realise that spliceText would benefit from having variant with cursor as an argument, but this work should start from rust implementation...

Thank you for the merge!

[heckj]

I think I'll snag that into a future enhancement issue, thanks @munhitsu