Class

Xojo.Core.TextEncoding

Warning

This item was deprecated in version 2020r2. Please use TextEncoding as a replacement.

Description

An encoding represents a way of converting text to and from raw bytes. Encodings are created from IANA character set names or the shared properties for the very common encodings. Use this class to convert Text to specific encodings and to convert Text to and from MemoryBlocks.

Methods

Name

Parameters

Returns

Shared

ConvertDataToText

data As MemoryBlock, allowLossy As Boolean = False

String

ConvertTextToData

value As String, allowLossy As Boolean = False

MemoryBlock

FromIANAName

name As String

TextEncoding

Property descriptions

Xojo.Core.TextEncoding.ASCII

ASCII As TextEncoding

Returns the ASCII text encoding.

This property is read-only.

Xojo.Core.TextEncoding.IANAName

IANAName As Text

The encoding's name as specified in IANA's Character Sets document.

This property is read-only.

Xojo.Core.TextEncoding.UTF16

UTF16 As TextEncoding

Returns the UTF-16 text encoding.

This property is read-only.

Xojo.Core.TextEncoding.UTF16BigEndian

UTF16BigEndian As TextEncoding

Returns the UTF-16 text encoding with each code unit stored as big endian.

This property is read-only.

Xojo.Core.TextEncoding.UTF16LittleEndian

UTF16LittleEndian As TextEncoding

Returns the UTF-16 text encoding with each code unit stored as little endian.

This property is read-only.

Xojo.Core.TextEncoding.UTF32

UTF32 As TextEncoding

Returns the UTF-32 text encoding. This is an alias for either UTF32LittleEndian or UTF32BigEndian depending on the endianness of the target.

This property is read-only.

Xojo.Core.TextEncoding.UTF32BigEndian

UTF32BigEndian As TextEncoding

Returns the UTF-32 text encoding with each code unit stored as big endian.

This property is read-only.

Xojo.Core.TextEncoding.UTF32LittleEndian

UTF32LittleEndian As TextEncoding

Returns the UTF-32 text encoding with each code unit stored as little endian.

This property is read-only.

Xojo.Core.TextEncoding.UTF8

UTF8 As TextEncoding

Returns the UTF-8 text encoding.

This property is read-only.

Xojo.Core.TextEncoding.Windows1252

Windows1252 As TextEncoding

Returns the Windows 1252 (ISO Latin-1) text encoding.

This property is read-only.

Method descriptions

Xojo.Core.TextEncoding.ConvertDataToText

ConvertDataToText(data As MemoryBlock, allowLossy As Boolean = False) As String

Converts a chunk of data in a MemoryBlock to Text.

Converts a chunk of data to Text. If the data is not valid for this encoding (e.g. overlong UTF-8 sequences), an exception is raised. The allowLossy parameter can be used to override this behavior. If it is True, any invalid input is replaced with the Unicode replacement character (U+FFFD).

Warning

A NilObjectException will be raised if data is Nil.

Warning

A RuntimeException will be raised if data is not valid for the encoding and allowLossy is False or if data has an unknown size.

This code takes data that came in on a MemoryBlock from an Xojo.Net.HTTPSocket event and converts it to UTF8 Text:

Var jsonData As Text = Xojo.Core.TextEncoding.UTF8.ConvertDataToText(content)

Xojo.Core.TextEncoding.ConvertTextToData

ConvertTextToData(value As String, allowLossy As Boolean = False) As MemoryBlock

Converts a text value to bytes in a MemoryBlock.

If the value cannot be represented accurately in this encoding, an exception is raised. The allowLossy parameter can be used to override this behavior. If it is True, any characters that cannot be represented are replaced with a question mark. For example, Emoji is not representable in the ASCII encoding.

If the encoding is UTF-16 or UTF-32, the resulting data will begin with a byte order mark. If the byte order mark is not desired, the encoding should specify an explicit big endian or little endian (e.g. using UTF32LittleEndian).

Warning

A RuntimeException will be raised if value cannot be represented accurately in the encoding and allowLossy is False.

Convert text to UTF-8 data:

Var t As Text = "Jåbberwøcky"
Var utf8Data As Xojo.Core.MemoryBlock
utf8Data = Xojo.Core.TextEncoding.UTF8.ConvertTextToData(t)

Xojo.Core.TextEncoding.FromIANAName

FromIANAName(name As String) As TextEncoding

Returns an encoding given its IANA name as specified in IANA's Character Sets document.

Gets the US ASCII encoding from its name:

Var encoding As Xojo.Core.TextEncoding
encoding = Xojo.Core.TextEncoding.FromIANAName("US-ASCII")

Compatibility

All project types on all supported operating systems.

See also

Object parent class; Locale, MemoryBlock, TextInputStream, TextOutputStream classes; String data type

TextEncoding class; Encodings module