MText

The Haxial Programming Language

MText Module

Contents

SetinDstTxt, inSrcTxt AppendinDstTxt, inSrcTxt AppendRepeatedinDstTxt, inSrcTxt, inCount AppendCharinTxt, inChar AppendRepeatedCharinTxt, inChar, inCount AppendLineBreakinTxt AppendTabinTxt AppendSpaceinTxt AppendIntinTxt, inIntVal, inOptions AppendDecIntinTxt, inIntVal AppendFloatinTxt, inVal, inOptions AppendTimeinTxt, inTimeStamp, inOptions AppendByteSizeinTxt, inByteSize, inOptions

InsertinDstTxt, inAtOffset, inSrcTxt InsertRepeatedinDstTxt, inAtOffset, inSrcTxt, inCount InsertCharinTxt, inAtOffset, inChar InsertRepeatedCharinTxt, inAtOffset, inChar, inCount ReplaceinDstTxt, inAtOffset, inExistingSize, inSrcTxt

RemoveinTxt, inAtOffset, inSize ClearinTxt ClearAndReuseinTxt TruncateinTxt, inNewSize GetSizeinTxt, outSize IsEmptyinTxt, outResult IsNotEmptyinTxt, outResult PreallocateinTxt, inSize FreeUnusedMemoryinTxt MoveinTxt, inToOffset, inFromOffset, inSize

EqualinTxtA, inTxtB, inOptions, outEqual CompareinTxtA, inTxtB, inOptions, outComparison BeginsWithinTxt, inBeginTxt, inOptions, outResult EndsWithinTxt, inEndTxt, inOptions, outResult

FindinTxt, inStartOffset, inTxtToFind, inOptions, outOffset FindCharinTxt, inStartOffset, inChar, inOptions, outOffset ContainsinTxt, inTxtToFind, inOptions, outResult

ToIntegerinTxt, inOptions, outNum ToFloatinTxt, inOptions, outNum

StoreCharinTxt, ioOffset, inChar LoadCharinTxt, ioOffset, outChar CountCharsinTxt, outCount CountBytesinTxt, inMaxCharCount, outByteCount, outCharCount

ChangeCasesrcTxt, dstTxt, inStyle RemoveLeadTrailWhiteSpacesrcTxt, dstTxt RemoveTruncatedCharinTxt FixLineBreakssrcTxt, dstTxt, inOptions

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

Parameters:

outTxt

RText

The variable to receive the reference to the new text object.

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

Parameters:

inDstTxt	RText	A reference to a text object to modify.
inSrcTxt	RText	A reference to a text object to copy text from.

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::NullObject	inDstTxt is a null reference (no text object).
MText::kError::IncorrectObjectType	The inDstTxt or inSrcTxt object is not an MText object.
MText::kError::InvalidSubset	The subset range of the inDstTxt reference starts or ends beyond the end of the text.
MText::kError::MaxLimit	Adding the new text to the inDstTxt object would exceed the maximum size of a text object.
MMemory::kError::Insufficient	There is not enough free memory to add the text to the inDstTxt object.

MText::AppendChar

Parameters:

inTxt	RText	A reference to a text object to modify.
inChar	char	The Unicode number of the character to append.

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::NullObject	inTxt is a null reference (no text object).
MText::kError::IncorrectObjectType	The inTxt object is not an MText object.
MText::kError::InvalidSubset	The subset range of the inTxt reference starts or ends beyond the end of the text.
MText::kError::MaxLimit	Adding the new character to the text would exceed the maximum size of a text object.
MMemory::kError::Insufficient	There is not enough free memory to add the character to the text.

MText::AppendInt

Parameters:

inTxt	RText	A reference to a text object to modify.
inIntVal	int	The integer value to append.
inNumFmt	uint32 or RNumberFormat	Number format options, or reference to a number format object.

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.

[Documentation main page]