android - Explain the meaning of Span flags like SPAN_EXCLUSIVE_EXCLUSIVE

Question

Can someone clearly explain with examples what each of the span flags like SPAN_EXCLUSIVE_EXCLUSIVE and SPAN_MARK_MARK mean and when to use what flags?

I do not understand the official documentation when it says:

Spans of type SPAN_EXCLUSIVE_EXCLUSIVE do not expand to include text inserted at either their starting or ending point.

Does "expand to include" refer to edits made after inserting the spans?

Does it mean that these flags do NOT affect Spannables with immutable text?

Answer 1

What the flags don't mean

When I first saw the INCLUSIVE and EXCLUSIVE parts of the Spannable flags, I thought they just told whether or not the span included the start and end index positions of the span. This is not true. Let me illustrate that with the following example.

String myString = "01234";
int start = 1;
int end = 3;
int spanFlag = Spannable.SPAN_INCLUSIVE_INCLUSIVE; // this is what is changing

SpannableString spannableString = new SpannableString(myString);
ForegroundColorSpan foregroundSpan = new ForegroundColorSpan(Color.RED);
spannableString.setSpan(foregroundSpan, start, end, spanFlag);
textView.setText(spannableString);

Here are the results:

SPAN_INCLUSIVE_INCLUSIVE

SPAN_INCLUSIVE_EXCLUSIVE

SPAN_EXCLUSIVE_INCLUSIVE

SPAN_EXCLUSIVE_EXCLUSIVE

They are all the same! The flags don't affect the span. A span always includes the character at its start index and excludes the character at the end index.

What the flags really mean

The INCLUSIVE and EXCLUSIVE parts of the Spannable flags actually tell whether or not the span should include text that is inserted at the start or end positions.

Here is a modified example to illustrate that.

String myString = "01234";
int start = 1;
int end = 3;
int spanFlag = Spannable.SPAN_INCLUSIVE_INCLUSIVE; // this is what is changing

// set the span
SpannableStringBuilder spannableString = new SpannableStringBuilder(myString);
ForegroundColorSpan foregroundSpan = new ForegroundColorSpan(Color.RED);
spannableString.setSpan(foregroundSpan, start, end, spanFlag);

// insert the text after the span has already been set
// (inserting at start index second so that end index doesn't get messed up)
spannableString.insert(end, "x");
spannableString.insert(start, "x");

textView.setText(spannableString);

Here are the results after inserting an x at the end and start indexes:

SPAN_INCLUSIVE_INCLUSIVE

SPAN_INCLUSIVE_EXCLUSIVE

SPAN_EXCLUSIVE_INCLUSIVE

SPAN_EXCLUSIVE_EXCLUSIVE

Notes

• In the second example I had to use a SpannableStringBuilder because the text in a SpannableString is immutable so you can't insert text into it. Thus, the flags are generally meaningless for a SpannableString. However, one could imagine a situation in which the spans from a SpannableString get copied over to a SpannableStringBuilder or Editable, and from there the flags would have meaning.
• See this answer for the difference between SpannableString, SpannableStringBuilder, Editable, and more.