DataType

Text

Warning

This item was deprecated in version 2021r1. Please use String as a replacement.

Description

The Text type is used to store textual information (unicode). Text values automatically convert to String.

Methods

Name	Parameters	Returns	Shared
BeginsWith	other As Text, options As Integer = 0, Optional locale As Locale = Nil	Boolean
Characters		Xojo.Core.Iterable
Codepoints		Xojo.Core.Iterable
Compare	other As Text, Optional options As Integer = 0, Optional locale As Locale = Nil	Integer
Empty		Boolean
EndOfLine		Text
EndsWith	other As Text, Optional options As Integer = 0, Optional locale As Locale = Nil	Boolean
FromCString	str As CString, encoding As TextEncoding	Text	✓
FromUnicodeCodepoint	codepoint As UInt32	Text	✓
IndexOf	other As Text, Optional compareOptions As Integer = 0, Optional locale As Locale = Nil	Integer
Join	items() As Text, separator As Text	Text	✓
Left	count As Integer	Text
Length		Integer
Lowercase	Optional locale As Locale = Nil	Text
Mid	start As Integer	Text
	start As Integer, length As Integer	Text
Replace	find As Text, replace As Text, Optional compareOptions As Integer = 0, Optional locale As Locale = Nil	Text
ReplaceAll	find As Text, replacement As Text, Optional compareOptions As Integer = 0, Optional locale As Locale = Nil	Text
Right	count As Integer	Text
Split	separator As Text, Optional compareOptions As Integer = 0, Optional locale As Locale = Nil	Text
TitleCase	Optional locale As Locale = Nil	Text
ToCString	encoding As TextEncoding	CString
Trim		Text
TrimLeft		Text
TrimRight		Text
Uppercase	Optional locale As Locale = Nil	Text

Method descriptions

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:

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

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:

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"

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:

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

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:

Dim dog As Text = "Dog"
Dim cat As Text = "Cat"

Dim result As Integer
result = dog.Compare(cat)

' result > 0

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:

Dim t As Text = ""

If t.Empty Then
  t = "Hello"
End If

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

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.

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.

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 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:

Dim EOL As Text = Text.FromUnicodeCodepoint(10)

Get the trade mark character (™):

Dim tradeMark As Text = Text.FromUnicodeCodepoint(8482)

Get the pi character (π) using its hex value:

Dim piChar As Text = Text.FromUnicodeCodepoint(&h3C0)

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":

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:

Dim t As Text = "The woodchuck chucked wood."
Dim pos As Integer = t.IndexOf(10, "wood") ' pos = 22

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":

Dim words() As Text = Array("Hello", "World")

Dim newText As Text
newText = Text.Join(words, ",") ' newText = "Hello,World"

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:

Dim t As Text = "Hello, World!"
Dim hello As Text = t.Left(5) ' hello = "Hello"

Text.Length

Length As Integer

Returns the number of characters in the Text.

Get the length of some Text:

Dim t As Text = "Hello, World!"
Dim length As Integer = t.Length ' length = 13

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:

Dim t As Text = "Hello, World!"
t = t.Lowercase ' t = "hello, world!"

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.

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:

Dim t As Text = "Hello, World!"
t = t.Mid(7) ' t = "World!"

Get "World" from Text:

Dim t As Text = "Hello, World!"
t = t.Mid(7, 5) ' t = "World"

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":

Dim t As Text = "Hello, World!"

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

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":

Dim t As Text = "Hello, World!"

Dim newText As Text
newText = t.ReplaceAll("l", "L") ' newText = "HeLLo, WorLd!"

Text.Right

Right(count As Integer) As Text

Returns the last count characters of the Text value.

Get "World!" from Text:

Dim t As Text = "Hello, World!"
t = t.Right(6) ' t = "World!"

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":

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:

Dim t As Text = "Hello, World!"

Dim chars() As Text
chars = t.Split

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!":

Dim t As Text = "hello, world!"
t = t.TitleCase ' t = "Hello, World!"

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:

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

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:

Dim t As Text = "   Hello, World!    "
t = t.Trim ' t = "Hello, World!"

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:

Dim t As Text = "   Hello, World!    "
t = t.TrimLeft ' t = "Hello, World!    "

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:

Dim t As Text = "   Hello, World!    "
t = t.TrimRight ' t = "   Hello, World!"

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:

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:

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:

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:

Var s As String = "Hello"
Var t As Text = s.ToText ' t = "Hello"

Compatibility

All project types on all supported operating systems.

Text

Description

Methods

Method descriptions

Notes

Converting text to and from bytes

Comparing text vs. strings

Technical information

Sample code

Compatibility

See also