A Text object represents a single piece of textual content that flows together. For example, in a document each header and footer is held in a separate text object. Each text object stores both a string (sequence of characters) and the associated attributes (formatting) applied to each character. 

In the context of a Text object an index describes a character location inside the text. These character indexes are zero based, eg: the first character in the text has an index of zero. If you attempt to access an index that is out of bounds then an error will be displayed. Prior to v2.1 an index was considered out of bounds if it was greater than or equal to the length of the text object. As of v2.1 an index equal to the text length is treated as valid and does not trigger an error, but rather returns information relevant to the very end of the text.

Note that any string value is also a Text object and can be treated as such, eg:

$name = 'Izzy'
$characterCount = $name.length

Storage Semantics

If a text object follows value semantics (the default unless otherwise noted) any changes will only affect that single text object, eg:

$text = 'Bunny I'

$otherText = $text

$range = Range.new(5, 2)

$otherText.deleteInRange($range)

# $otherText is now 'Bunny', but $text is still 'Bunny I'

On the other hand, a text object following reference semantics doesn’t have its own storage for the underlying content. Instead, the text object merely refers to a unique content storage, like a document header. This means that any changes to the text object affect not only the document itself, but possibly other variables as well. Consider a document body:

$doc = Document.active

$text = $doc.text # assume the document reads 'Bunny I'

$otherText = $text # both variables refer to the same storage

$range = Range.new(5, 2)

$otherText.deleteInRange($range)

# $otherText and $text are now both 'Bunny'

Not only are both variables $text and $otherText changed by the single delete command, but the contents of the original document have also be changed. If switching to value semantics is desired, so the changes are isolated, a copy of the text object can be made, eg:

$doc = Document.active

$text = $doc.text

$otherText = $text.copy # no longer refers back to the document

All text objects follow value semantics unless noted in the documentation of a command or property that returns the text object. In general, text objects following reference semantics are those that hold unique document content, like a header or table cell.

Text Type Commands

Text.newWithCharacter charValue v1.1

Returns a new Text object (eg: string) that contains the single character given to this command as a numeric value, eg:

$string = Text.newWithCharacter(116) # the letter 't'

Note: this number is the UTF-16 character value, as defined below by the characterAtIndex command. If the given number is part of a surrogate pair, a zero-length string is returned.

Text.newWithCodepoint codepoint v1.1