` | `Optional` locale As `Locale` = `Nil` | Text | | ## Method descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

Text.BeginsWith **BeginsWith**(other As Text, options As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As `Boolean` Determines whether the beginning of this Text instance matches the other Text when compared using the specified comparison options and locale. Returns True if other matches the beginning of the Text, False if it does not. By default this performs a case-insensitive comparison. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the options parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised when options are invalid (currently not 0 or 1).

Warning

An `InvalidArgumentException` will be raised when other is an empty Text value.

Check the beginning characters of some \`Text\`: ``` xojo Dim t As Text t = "All we have to decide is what to do with the time that is given to us." If t.BeginsWith("All") Then Label1.Text = "Text starts with 'All'." End If ```

forsearch

Text.Characters **Characters** As Xojo.Core.Iterable Returns an iterator that yields a Text value for each character, in order of first to last. Reverse the \`Text\`: ``` xojo Dim t As Text = "Hello, World!" Dim reverse As Text For Each c As Text In t.Characters reverse = c + reverse Next ' reverse = "!dlroW ,olleH" ```

forsearch

Text.Codepoints **Codepoints** As Xojo.Core.Iterable Returns an iterator that returns UInt32 values for each Unicode scalar value that comprises the Text. Look for Unicode 65: ``` xojo Dim myText As Text = "Once Upon A Time" For Each codePoint As UInt32 In myText.Codepoints If codePoint = 65 Then ' It is "A" End If Next ```

forsearch

Text.Compare **Compare**(other As Text, `Optional` options As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As `Integer` Compares a Text value with another Text value. A non-empty Text is always greater than an empty Text. By default, a case-insensitive comparison is done. Returns a negative integer if the value is less than other, 0 if the two values are equal, and a positive integer if the value is greater than other. By default this performs a case-insensitive comparison. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the options parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised when the specified options are invalid.

Compare two Text values: ``` xojo Dim dog As Text = "Dog" Dim cat As Text = "Cat" Dim result As Integer result = dog.Compare(cat) ' result > 0 ```

forsearch

Text.Empty **Empty** As `Boolean` Returns whether or not the Text has contents. This will always be as fast or faster than checking length against zero. Returns True when the Text is empty, False when it is not. Check if a Text value is empty: ``` xojo Dim t As Text = "" If t.Empty Then t = "Hello" End If ```

forsearch

Text.EndOfLine **EndOfLine** As Text Returns the EndOfLine character for the current platform (Mac, Windows, Linux and iOS). - iOS uses CodePoint 13 - Mac and Linux use CodePoint 10 - Windows uses CodePoint 10 + CodePoint 13

forsearch

Text.EndsWith **EndsWith**(other As Text, `Optional` options As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As `Boolean` Determines if the Text ends with other Text. Returns True if the Text ends with other, False if it does not. By default this performs a case-insensitive comparison. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the compareOptions parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised if the options specified are invalid.

Warning

An `InvalidArgumentException` will be raised if other is an empty Text value.

forsearch

Text.FromCString **FromCString**(str As `CString`, encoding As `TextEncoding`) As Text Creates a new Text object from a CString, interpreting it using the given encoding. This method is `shared`.

forsearch

Text.FromUnicodeCodepoint **FromUnicodeCodepoint**(codepoint As `UInt32`) As Text Creates a new Text object from a single Unicode code point value. This method is `shared`. Visit [Unicode Lookup](http://unicodelookup.com/) to get decimal values to use with this method.

Warning

An `UnsupportedFormatException` will be raised if codepoint is not a Unicode scalar value (i.e. it is a high-surrogate code point or a low-surrogate code point).

Get the EndOfLine character: ``` xojo Dim EOL As Text = Text.FromUnicodeCodepoint(10) ``` Get the trade mark character (™): ``` xojo Dim tradeMark As Text = Text.FromUnicodeCodepoint(8482) ``` Get the pi character (π) using its hex value: ``` xojo Dim piChar As Text = Text.FromUnicodeCodepoint(&h3C0) ```

forsearch

Text.IndexOf **IndexOf**(other As Text, `Optional` compareOptions As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As `Integer` Finds the position of other within the Text beginning with *startPosition*. Returns the zero-based location of *other* within the Text. If *other* is not found, returns -1. By default this performs a case-insensitive comparison. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the compareOptions parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised if the specified options are invalid.

Warning

An `InvalidArgumentException` will be raised if *other* is an empty Text value.

Find the position of the Text "wood": ``` xojo Dim t As Text = "The woodchuck chucked wood." Dim pos As Integer = t.IndexOf("wood") ' pos = 4 ``` Find the position of "wood" beginning with position 10: ``` xojo Dim t As Text = "The woodchuck chucked wood." Dim pos As Integer = t.IndexOf(10, "wood") ' pos = 22 ```

forsearch

Text.Join **Join**(items() As Text, separator As Text) As Text Creates a new Text object by concatenating each item in the items array together. If separator is not empty, it will be inserted between each item when performing the concatenation. If the items array is empty, an empty Text value is returned. This method is `shared`. Create a Text from the array containing "Hello" and "World": ``` xojo Dim words() As Text = Array("Hello", "World") Dim newText As Text newText = Text.Join(words, ",") ' newText = "Hello,World" ```

forsearch

Text.Left **Left**(count As `Integer`) As Text Returns the first count characters of the Text value. Get the 5 left-most characters of the \`Text\`: ``` xojo Dim t As Text = "Hello, World!" Dim hello As Text = t.Left(5) ' hello = "Hello" ```

forsearch

Text.Length **Length** As `Integer` Returns the number of characters in the Text. Get the length of some \`Text\`: ``` xojo Dim t As Text = "Hello, World!" Dim length As Integer = t.Length ' length = 13 ```

forsearch

Text.Lowercase **Lowercase**(`Optional` locale As `Locale` = `Nil`) As Text Creates a new Text value that has its characters lowercased. If locale is non-Nil, it uses the locale's rules when performing the operation. Set Text to lower case: ``` xojo Dim t As Text = "Hello, World!" t = t.Lowercase ' t = "hello, world!" ```

forsearch

Text.Mid **Mid**(start As `Integer`) As Text Returns a portion of the characters in the Text value. The start position is a zero-based. If the Text value is shorter than the requested length of characters, the remaining Text starting at the start is returned. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

Text.Mid **Mid**(start As `Integer`, length As `Integer`) As Text Returns a portion of the characters in the Text value. The start position is a zero-based. If the Text value is shorter than the requested length of characters, the remaining Text starting at the start is returned. Get "World!" from \`Text\`: ``` xojo Dim t As Text = "Hello, World!" t = t.Mid(7) ' t = "World!" ``` Get "World" from \`Text\`: ``` xojo Dim t As Text = "Hello, World!" t = t.Mid(7, 5) ' t = "World" ```

forsearch

Text.Replace **Replace**(find As Text, replace As Text, `Optional` compareOptions As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As Text Creates a new value by replacing the first instances of the find parameter's value with the replacement parameter's value. If the input does not contain the requested value, nothing is replaced and the input is returned. By default this performs a case-insensitive comparison search. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the compareOptions parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised if the options specified are invalid.

Warning

An `InvalidArgumentException` will be raised if find is an empty Text value.

Replace "World" with "Mars": ``` xojo Dim t As Text = "Hello, World!" Dim newText As Text newText = t.Replace("World", "Mars") ' newText = "Hello, Mars!" ```

forsearch

Text.ReplaceAll **ReplaceAll**(find As Text, replacement As Text, `Optional` compareOptions As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As Text Returns a new Text value by replacing all instances of the find parameter's value with the replacement parameter's value. If the input does not contain the requested value, nothing is replaced and the input is returned. By default this performs a case-insensitive comparison search. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the compareOptions parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in.

Warning

A `RuntimeException` will be raised if the options specified are invalid.

Warning

An `InvalidArgumentException` will be raised if find is an empty Text value.

Replaces all instances of "l" with "1": ``` xojo Dim t As Text = "Hello, World!" Dim newText As Text newText = t.ReplaceAll("l", "L") ' newText = "HeLLo, WorLd!" ```

forsearch

Text.Right **Right**(count As `Integer`) As Text Returns the last count characters of the Text value. Get "World!" from \`Text\`: ``` xojo Dim t As Text = "Hello, World!" t = t.Right(6) ' t = "World!" ```

forsearch

Text.Split **Split**(separator As Text, `Optional` compareOptions As `Integer` = 0, `Optional` locale As `Locale` = `Nil`) As Text Returns an array of the portions of the Text that are delimited by separator. If separator is the same as the Text, an empty array is returned. If the Text does not contain separator, an array containing only the original Text value is returned. By default this performs a case-insensitive comparison. To do a case-sensitive comparison, supply the CompareCaseSensitive constant to the compareOptions parameter. By default comparisons are done in an invariant locale (i.e. not dependent on the user's preferences). The locale parameter can be used to specify an explicit locale to do comparisons in. Split provides equivalent functionality to String.NthField.

Warning

A `RuntimeException` will be raised if the options specified are invalid.

Warning

An `InvalidArgumentException` will be raised if find is an empty Text value.

Split the Text into "Hello" and "World": ``` xojo Dim t As Text = "Hello World" Dim words() As Text words = t.Split(" ") ``` Splits the Text into an array with one element for each character: ``` xojo Dim t As Text = "Hello, World!" Dim chars() As Text chars = t.Split ```

forsearch

Text.TitleCase **TitleCase**(`Optional` locale As `Locale` = `Nil`) As Text Returns a new Text value that has its characters titlecased. If the locale parameter is non-Nil, it will use that locale's rules when performing the operation. Convert Text to "Hello, World!": ``` xojo Dim t As Text = "hello, world!" t = t.TitleCase ' t = "Hello, World!" ```

forsearch

Text.ToCString **ToCString**(encoding As `TextEncoding`) As `CString` Creates a CString from a Text with a specific encoding. The CString is immutable and is its own entity with the lifetime not tied to the source Text value. This is provided to make dealing with declares easier. In general, CString is for use with Declare commands and MemoryBlocks.

Warning

A `NilObjectException` will be raised if encoding is Nil.

Warning

An `UnsupportedFormatException` will be raised if the Text is cannot be represented in the given encoding. For example, Emoji is not representable in the ASCII encoding.

Convert Text to CString: ``` xojo Dim t As Text = "Hello, World!" Dim cs As CString = t.ToCString(Xojo.Core.TextEncoding.UTF8) ```

forsearch

Text.Trim **Trim** As Text Trims whitespace, as defined in the Unicode standard, from the beginning and end of the Text. If the value is empty or consists entirely of whitespace, an empty Text is returned. Removes beginning and ending white space: ``` xojo Dim t As Text = " Hello, World! " t = t.Trim ' t = "Hello, World!" ```

forsearch

Text.TrimLeft **TrimLeft** As Text Trims whitespace, as defined in the Unicode standard, from the beginning of the Text. If the value is empty or consists entirely of whitespace, an empty Text is returned. Removes beginning white space: ``` xojo Dim t As Text = " Hello, World! " t = t.TrimLeft ' t = "Hello, World! " ```

forsearch

Text.TrimRight **TrimRight** As Text Trims whitespace, as defined in the Unicode standard, from end of the Text. If the value is empty or consists entirely of whitespace, an empty Text is returned. Removes ending white space: ``` xojo Dim t As Text = " Hello, World! " t = t.TrimRight ' t = " Hello, World!" ```

forsearch

Text.Uppercase **Uppercase**(`Optional` locale As `Locale` = `Nil`) As Text Returns a new Text value that has its characters uppercased. If the locale parameter is non-Nil, it will use that locale's rules when performing the operation. Set Text to upper case: ``` xojo Dim t As Text = "Hello, World!" t = t.Uppercase ' t = "HELLO, WORLD!" ``` ## Notes Const CompareCaseSensitive = 1 Used by methods to specify some methods should compare Text as case sensistive. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Converting text to and from bytes To get the bytes for the Text (using a MemoryBlock), you call TextEncoding.ConvertTextToData using a specific encoding. To convert bytes in a MemoryBlock to Text, you call TextEncoding.ConvertDataToText, specifying the encoding. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Comparing text vs. strings Text is abstract - a series of characters. Bytes are concrete - a series of bits. There are lots of different ways to encode characters into bytes. Most of them are very limited, only defining encodings for some characters, and even when they define encodings for the same characters, they often use different bytes. The only encodings which can represent every character are the Unicode encodings: UTF-8, UTF-16, UTF-32. The old String type tries to represent either Text or bytes or both, and as a result it's complicated and confusing. With Text, this is now very simple: Text is characters, and if you want to convert to or from an array of bytes (or an old-fashioned String), you have to be clear about the encoding you intend to use. When you say that you want to write an ASCII string to a serial port - well, you are actually writing bytes to the serial port, because you are doing something concrete, something that interchanges with other programs or machines. So you would convert the Text to bytes, and you would do so using the ASCII encoding. Conversely, you can translate some bytes, contained in a String or a MemoryBlock, up to a Text value by specifying the encoding that was used to generate them. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Technical information The Text type is an immutable series of Unicode scalar values. The documentation is very deliberate in its use of these terms: character, code point, and scalar value. A character, in this context, refers to an extended grapheme cluster (also known as a user-perceived character). The terms code point and scalar value retain the meaning defined in the Unicode standard. All of the APIs on the Text type operate in characters. For example, if the APIs worked in terms of Unicode code points, it would be possible to corrupt data using Left/Mid/Right if the positions happened to be in the middle of a composed character or grapheme cluster. Working in characters also avoids situations where the length of 'é' can be either 1 or 2. Many of the functions in this API optionally take locales because different locales can have special rules for casing and comparing. The default behavior being to perform the operation in a locale-insensitive manner. Functions that perform comparisons also take option flags that specify how to perform the comparison (e.g. case sensitively). These flags are bit flags that are combined via the bitwise Or operator. If the combination of options is invalid, an exception is thrown. ## Sample code Assign Text to a Label: ``` xojo Dim t As Text t = "Hello, World" MyLabel.Text = t ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Text is available in all project types, so you can also use it in place of String. A Text value can be converted to a String, so code like this works: ``` xojo Dim t As Text = "Hello, World!" MessageBox(t) ' MessageBox takes a String, but this works because Text can be converted to String ``` You can also convert a String with a known encoding to a Text using the String.ToText method: ``` xojo Var s As String = "Hello" Var t As Text = s.ToText ' t = "Hello" ``` ## Compatibility All project types on all supported operating systems. ## See also `TextEncoding` class