KL MText

## Description

The MText module provides text objects that can contain a changing amount of text. Commands can be invoked to manipulate/modify the text. MText is suitable for constructing a body of text by appending a piece at a time.

MText uses Unicode, an industry standard allowing computers to consistently represent and exchange text in any of the world's writing systems and languages. Unicode defines more than 100,000 different characters, providing a standardized digital representation for each.

Internally, MText stores the text in 1 of 3 Unicode formats:

* UTF8 -- 1 byte (8 bits) per character for standard Latin characters (A-Z). 2 to 4 bytes for other characters.
* UTF16-BE -- 2 bytes (16 bits) per character for most characters. 4 bytes for unusual or less common characters.
* UTF16-LE -- Same as UTF16-BE except with the 2 bytes in a 16-bit value being in the other order. BE = Big Endian order. LE = Little Endian order.

The maximum amount of text that can be stored in a text object is an indefinitely large amount. Storing a megabyte of text is no problem. Storing 100 megabytes of text is theoretically possible but would probably be slow, inefficient, and impractical.

The text objects store only plain text. They do not store "rich" text with various styles such as different colors, fonts, bold, italic etc.

## MText::Create

### Description

This command creates an empty text object, and sets the specified variable to contain a reference to the new text object.

\*\*\*\* TO DO: How to create a text object in UTF16 format, rather than the default UTF8 format.

### Pedantic Details

* Any existing reference in the outTxt variable is removed and replaced by the reference to the new text object.
* If creation of the new object fails, the outTxt variable is unchanged.
* The reference is set to be a non-subset reference (but can subsequently be changed to a subset).

## MText::Append

### Description

This command appends the contents of the inSrcText object to the inDstTxt object.

### Pedantic Details

* The inSrcTxt reference and object are never modified by this command.
* If this command fails, the inDstTxt reference and the object are (or appear) unchanged.
* If the inDstTxt object reference is a subset, this command will append to the end of the subset, not to the end of the entire text. Thus it may actually be inserting into the middle of the text, if the subset ends before the end of the text. In other words, it inserts at the subset end.
* The subset range of inDstTxt is expanded to include the appended new text.
* Fails if the subset range of inDstTxt starts or ends beyond the end of the text. Acceptable if is exactly at end.
* If the inSrcTxt object reference is a subset, only the subset range is used (only the subset will be appended to inDstTxt).
* If the subset range of inSrcTxt is invalid, then the non-existent portion of the subset is ignored (the valid/existent portion is appended). Does not fail.
* If inSrcTxt is empty or a null reference, it is interpreted as an attempt to append nothing, and inDstTxt is not changed. Does not fail.

### Errors

 MText::kError::IncorrectObjectType
 MText::kError::InvalidSubset
 MText::kError::MaxLimit
 MMemory::kError::Insufficient

## MText::AppendChar

### Description

This command appends a character to the specified text object. Characters are specified by number. For example, in the Unicode standard, the latin capital letter 'A' is number 65 (hex 0x41), and the infinity symbol is number 8734 (hex 0x221E).

### Pedantic Details

* The "inChar" parameter is not provided encoded in UTF8 or UTF16. It is provided simply as the number of a Unicode character.
* If this command fails, the reference and the object are (or appear) unchanged.
* If the object reference is a subset, this command will append to the end of the subset, not to the end of the entire text. Thus it may actually be inserting into the middle of the text, if the subset ends before the end of the text. In other words, it inserts at the subset end.
* The subset range is expanded to include the appended new character.
* Fails if the subset range starts or ends beyond the end of the text. Acceptable if is exactly at end.

### Errors

 MText::kError::IncorrectObjectType
 MText::kError::InvalidSubset
 MText::kError::MaxLimit
 MMemory::kError::Insufficient

## MText::AppendInt

### Parameters

 inIntVal
 inNumFmt
RNumberFormat

### Description

This command converts an integer value (a whole number) to text and appends it to the specified text object. The inNumFmt parameter controls how the integer value is converted to text. It can be number formatting options, or it can be a reference to a number format object that you created for full/precise/customized control over the formatting.

\*\*\*\* TO DO: Document the number format options. Document number format objects.

### Pedantic Details

* Operates slightly differently if the variable passed for inIntVal is signed versus unsigned.
* There are multiple versions of this command, depending on the type of inIntVal and whether inNumFmt is number format options or an object.
* If this command fails, the reference and the object are unchanged.
* Behavior regarding subsets is the same as MText::AppendChar.