Text Object - Modifying Text

The following Text object commands allow you to directly modify the text object, or return new text objects that are derived from the existing text.

.deleteInRange rangeObject v1.1

Modifies the text object so all characters and attributes specified by the given Range object are removed. The range must be in-bounds or an error will be displayed.

.replaceInRange rangeObject, value v1.1

Replaces the characters and attributes in the specified Range object with those from the given value, which most probably will be a Text object. If the value is not a Text object, it will be converted to a string with no attributes as needed. The range must be in-bounds for the existing text object or an error will be displayed.

.insertAtIndex charIndex, insertValue v1.1

1. Any kind of Text object. The return value is a Range object describing the inserted text.

2. An Image object (allowed as of v2.0.5). The return value is the Image object that was copied and just added to the text.

3. A CrossReference object. The return value is the CrossReference object that was copied and just added to the text.

4. A FloatingContent object (allowed as of v2.1) that will be anchored to the paragraph containing the given character index. The return value is the FloatingContent object that was copied and added to the text.

5. Any other value type will be converted to a string and inserted as a Text object.

The return value of this command differs depending on the type of value inserted (see above). Note: prior to v2.0.5 this command did not return any value at all.

.append appendValue v2.0.5

Appends the given value to the end of the text. The accepted values and their corresponding return types are just the same as the insertAtIndex command.

.textByAppending value, [value2] ... [valueN] v1.1

Returns a new text object that appends the given value(s) to the existing text object. The given value may be of any type, and will be converted to text as needed.

.textByLowercasing v1.3

Returns a new text object that converts all characters of the existing text object to lowercase.

.textByUppercasing v1.3

Returns a new text object that converts all characters of the existing text object to uppercase.

.textByCapitalizing v1.3

Returns a new text object which has the first letter of each existing word as uppercase and the rest as lowercase.

.textByMatchingCase textTemplate v1.3

Returns a new text object that uses the given text object’s character case as a template. Case conversion occurs on a word-by-word basis. Some examples:

$text = "stormy weather"

$text.textByMatchingCase("Rain rain") # returns "Stormy weather"

$text.textByMatchingCase("Windy WIND") # returns "Stormy WEATHER"

$text.textByMatchingCase("THUNDER") # returns "STORMY WEATHER"

If there are less words in the template than the existing text, then the last word of the template is used for all remaining words.

.textByNormalizing mode v2.0.5

Returns a version of the text which has the same semantic meaning, but where the underlying characters (Unicode code points) have been normalized.

The normalization modes are available "compose" and "decompose". The former will combine a sequence of characters into a single precomposed character when possible, eg: the character 'e' followed by an Acute Accent (U+0301) will be combined into a single precomposed character 'é' (U+00E9). The decompose mode does the inverse when possible.

If an unknown mode is specified, this returns the @undefined value.

.textByIncrementingAllCodepointsBy addValue v1.1

Returns a new text object that has every Unicode code point in the existing text object incremented by the given amount.

.textByDecrementingAllCodepointsBy subtractValue v1.1

Returns a new text object that has every Unicode code point in the existing text object decremented by the given amount.

.transliterateInRange rangeObject, hashMap v1.1

This method potentially modifies all of the characters in the text that fall within the given Range object. Each character in the text is used as a key to find a value in the given Hash object hashMap. If the key exists, the character is replaced with the corresponding hash lookup value. If the key does not exist, the character is left unchanged.

Each key in the hash can be either a string 1 character in length or a numeric character code point. The corresponding value can be a string of any length. An example:

$map = Hash.new

$map{'o'} = 'c'

$map{'n'} = 'e'

$map{0x0074} = 0x006C # 't' becomes 'l'

$map{'c'} = 'az' # 'c' expands to two letter

$map{'y'} = 'u'

$map{'a'} = 'r'

$map{'!'} = '' # delete all exclamations

$text = "cyan ion ent!"

$range = Range.newWithText($text)

$text.transliterateInRange($range, $map)

# text is now "azure ice eel"

.transformInRangeWithICU rangeObject, icuTransform v3.0

This method potentially modifies all of the characters in the text that fall within the given Range object by using the given ICU transformation. If you pass @undefined for the range object, the entire text object will be modified. 

Some examples:

$text = "abcdefghi"

$text.transformInRangeWithICU( @undefined, "[aeiou] Upper" )

# text is now "AbcdEfghI"

$text = "あいう"

$text.transformInRangeWithICU( @undefined, "Hiragana-Latin" )

# text is now "aiu"

.split delimiter v1.1

Divides the text object into an array of subtexts. A division occurs wherever the given delimiter is found in the text. An example:

$text = 'red, blue, green'

$list = $text.split(', ')

# list contains 'red', 'blue', and 'green'

If the delimiter is an empty string (zero length), then the returned array will have one value for each composed character sequence in the original text object. A composed character sequence is one base character possibly followed by one or more combining characters, like an accent. Roughly a composed character sequence is equivalent to one logical letter. An example:

$text = 'abéאֶ'

$list = $text.split('')

# list contains 'a', 'b', 'é', 'אֶ'