What is the difference between SPAN_POINT_MARK and SPAN_MARK_POINT?

Question

I have been reading up on the docs for the Spanned/Spannable class for a project that I am working on. I have been puzzled by the definition and usage of the spans that contain MARK and POINT.

A MARK seems to be defined in the Doc as "attached" to a character's location while a POINT is defined as being "glued" to a character. Thus a MARK won't move when text is changed and a POINT will move with the character it was "glued" to when text is changed.

These definitions seem to show that MARK is synonymous with INCLUSIVE and that POINT is synonymous with EXCLUSIVE.

However, this is not the case as neither SPAN_MARK_MARK nor SPAN_POINT_POINT are synonymous with either SPAN_INCLUSIVE_INCLUSIVEor SPAN_EXCLUSIVE_EXCLUSIVE. In fact, SPAN_INCLUSIVE_INCLUSIVE is the same as SPAN_MARK_POINT and SPAN_POINT_MARK is the same as SPAN_EXCLUSIVE_EXCLUSIVE.

My questions are as follows

1. Why is SPAN_POINT_MARK synonymous with SPAN_EXCLUSIVE_EXCLUSIVE? and why is SPAN_MARK_POINT synonymous with SPAN_INCLUSIVE_INCLUSIVE?

2. Why aren't SPAN_MARK_MARK and SPAN_POINT_POINT synonymous with SPAN_INCLUSIVE_INCLUSIVEand SPAN_EXCLUSIVE_EXCLUSIVE respectively?

3. What are the true definitions of MARK and POINT in this usage?

Answer 1

The way I like to explain MARK vs POINT is by representing them as square brackets at whatever offset they exist in a range of text. The direction the bracket is pointing shows the character that the mark or point is "attached" to.

So for a POINT, you would use the open bracket - it's attached to the character following it. And for a MARK, you would use the close bracket - it's attached to the character preceding it.

Let's look at some examples of each type:

SPAN_MARK_MARK

Inserting at the offset of a 0-length span: The marks remain fixed.

Before: Lorem ]]ipsum dolor sit.
After:  Lorem ]]INSERTipsum dolor sit.

Inserting at the start of a non-0-length span: The inserted text is included in the range of the span.

Before: Lorem ]ipsum] dolor sit.
After:  Lorem ]INSERTipsum] dolor sit.

Inserting at the end of a non-0-length span: The inserted text is excluded from the range of the span.

Before: Lorem ]ipsum] dolor sit.
After:  Lorem ]ipsum]INSERT dolor sit.

You can see from the last two examples, why the SPAN_MARK_MARK flag is synonymous with the SPAN_INCLUSIVE_EXCLUSIVE flag. Text inserted at the start of the span is included in the range, while text inserted at the end is excluded.

SPAN_POINT_POINT

Inserting at the offset of a 0-length span: The points are pushed forward.

Before: Lorem [[ipsum dolor sit.
After:  Lorem INSERT[[ipsum dolor sit.

Inserting at the start of a non-0-length span: The inserted text is excluded from the range of the span.

Before: Lorem [ipsum[ dolor sit.
After:  Lorem INSERT[ipsum[ dolor sit.

Inserting at the end of a non-0-length span: The inserted text is included in the range of the span.

Before: Lorem [ipsum[ dolor sit.
After:  Lorem [ipsumINSERT[ dolor sit.

Again you can see from the last two examples why the SPAN_POINT_POINT flag is synonymous with the SPAN_EXCLUSIVE_INCLUSIVE flag. Text inserted at the start of the span is excluded from the range, while text inserted at the end is included.

SPAN_MARK_POINT

Inserting at the start of the span: The inserted text is included in the range.

Before: Lorem ]ipsum[ dolor sit.
After:  Lorem ]INSERTipsum[ dolor sit.

Inserting at the end of the span: The inserted text is still included in the range.

Before: Lorem ]ipsum[ dolor sit.
After:  Lorem ]ipsumINSERT[ dolor sit.

And thus it has the synonym SPAN_INCLUSIVE_INCLUSIVE - the inserted text is always included in the range of the span.

SPAN_POINT_MARK

Inserting at the start of the span: The inserted text is excluded from the range.

Before: Lorem [ipsum] dolor sit.
After:  Lorem INSERT[ipsum] dolor sit.

Inserting at the end of the span: The inserted text is still excluded from the range.

Before: Lorem [ipsum] dolor sit.
After:  Lorem [ipsum]INSERT dolor sit.

And thus it has the synonym SPAN_EXCLUSIVE_EXCLUSIVE - the inserted text is always excluded from the range of the span.

I think the documentation confuses things by splitting the definitions of some of the synonyms. For example, when describing SPAN_MARK_MARK, they only define its usage in terms of a 0-length span. Then when defining SPAN_INCLUSIVE_EXCLUSIVE (which is a synonym) they only define its usage in terms of non-0-length spans. I think it would have been a lot clearer if they stated up front that they were synonyms, and had a single definition shared by both terms.

Answer 2

They are conceptual concepts and think of them in the order that they appear

From the docs:

MARK and POINT are conceptually located between two adjacent characters. A MARK is "attached" to the character before, while a POINT will stick to the character after. The insertion cursor is conceptually located between the MARK and the POINT. As a result, inserting a new character between a MARK and a POINT will leave the MARK unchanged, while the POINT will be shifted, now located after the inserted character and still glued to the same character after it. Depending on whether the insertion happens at the beginning or the end of a span, the span will hence be expanded to include the new character (when the span is using a MARK at its beginning or a POINT at its end) or it will be excluded. Note that before and after here refer to offsets in the String, which are independent from the visual representation of the text

Your point

These definitions seem to show that MARK is synonymous with INCLUSIVE and that POINT is synonymous with EXCLUSIVE.

isnt really the case. Basically think of mark as the starting marker for the span and point as the endpoint. What happens between these two points(styling, adding more text to styled text and so on) is now classified as inclusive and exclusive and hence directly correlate with them.

Lets look at an example shall we: Lets say we have the following text styled

This is an example text

If we used SPAN_EXCLUSIVE_EXCLUSIVE on the boldface span, and we insert text in the middle of the span, it is still boldface:

This is an unbelievably good example text

But if we insert text at the beginning or the end of the boldface span, the inserted text is not boldface:

This is not an example text

If we use SPAN_INCLUSIVE_EXCLUSIVE, then inserting text at the beginning would be included as part of the span, and we would have:

This is quite an example text isnt it

Now all this is just my interpretation of the docs. Why SPAN_POINT_MARK is synonymous with SPAN_EXCLUSIVE_EXCLUSIVE is something someone from google will have to comment I suppose, but in my opinion, MARK_POINT movement represents inclusion and POINT_MARK represents exclusion. SPAN_POINT_POINT and SPAN_MARK_MARK represent 0 length strings and hence cannot be attributed to inclusion/exclusion.

:EDIT: SPAN_MARK_MARK and SPAN_POINT_POINT are 0 length strings , i.e. the string starts with mark at 0 position and then any subsequent additions appends to the string but the mark position does not change, or the string starts with point position and any subsequent additions to the string moves the point towards the end. These flags essentially signal the starting point a spannable string and hence represent 0 length strings. Then the inclusive,exclusive flags can be used depending on whether the string was mark_mark or point_point to start with. Also SPAN_EXCLUSIVE_INCLUSIVE,When 0-length, behave like marks and SPAN_INCLUSIVE_EXCLUSIVE when 0-length behave like points which is obvious from the way they are defined.Again this is my interpretation of the docs