You are here:

QuickString

QuickString functions are designed to work on shorter strings, up to 255 characters in length. Everything is explicitly written to work with PString-formatted strings, with a byte with the length in the beginning. QuickString::Convert and QuickString::GetLength are the only functions available that work with ASCIIZ strings.

In all cases, if a string would go longer than 255 characters, it is truncated to 255 characters. Also, the destination string must have enough memory available to store the result.

In version 0.1, this is by far the largest portion of QuickOS, occupying nearly 2.5KB with the faster functions enabled. In the future, there will be configuration options to toggle certain parts of this library, since only rarely would a program need every feature available in it.

Functions

General Manipulation

QuickString::GetLength

Gets the length of an ASCIIZ string.

QuickString::Convert

Converts an ASCIIZ string to a PString or vice versa.

QuickString::Join

Adds one string to the end of another.

QuickString::Copy

Copies a string to another string.

Substring Functions

QuickString::Substring

Gets a portion of a string.

QuickString::Right

Gets a number of the right-most characters from a string.

QuickString::Left

Gets a number of the left-most characters from a string.

Update Functions

QuickString::ToUpper

Converts a string to upper case.

QuickString::ToLower

Converts a string to lower case.

QuickString::AddSeparator

Adds a separator character every X characters.

QuickString::Pad

Pads a string on the left, right, or both sides.

QuickString::Reverse

Reverses a string.

Search Functions

QuickString::FindChar

Searches for a character in a string.

QuickString::Find

Searches for a string in another string.

QuickString::Compare

Compares two strings.

Number to String Functions

QuickString::UInt8ToString

Converts an unsigned byte to a string.

QuickString::UInt16ToString

Converts an unsigned word to a string.

QuickString::UInt32ToString

Converts an unsigned dword to a string.

QuickString::SInt8ToString

Converts a signed byte to a string.

QuickString::SInt16ToString

Converts a signed word to a string.

QuickString::SInt32ToString

Converts a signed dword to a string.

QuickString::Int8ToHex

Converts a byte to a hex string.

QuickString::Int16ToHex

Converts a word to a hex string.

QuickString::Int32ToHex

Converts a dword to a hex string.

String to Number Functions

These are huge, complicated, and very slow. They're designed for rare usage when the user types in a number.

QuickString::StringToInt8

Converts a string to a byte.

QuickString::StringToInt16

Converts a string to a word.

QuickString::StringToInt32

Converts a string to a dword

Zero Page Values

QuickString::ZP_Internal

4 bytes, Internal data for strings. Do not use this.

Values

QuickString::Flags

Byte, Output flags.

QUICKSTRING_FLAGS::PadBiasLeft: Set to bias "Both" in Pad to the left. Clear to prefer to the right.

QuickString::FromFlags

Byte, Flags to use with the StringTo* functions.

Default: QUICKSTRING_FROMFLAGS::Decimal | QUICKSTRING_FROMFLAGS::IgnoreComma

QUICKSTRING_FROMFLAGS::Clamp: Set to clamp on overly large values. Otherwise, the low bytes of the result will be returned. 32-bit values are always clamped on overflow.
QUICKSTRING_FROMFLAGS::Signed: Set to convert to a signed value. Only works when converting to Decimal.

Only one of the following may be used to specify radix:

QUICKSTRING_FROMFLAGS::Decimal: Read a decimal value.
QUICKSTRING_FROMFLAGS::Hexadecimal: Read a hexadecimal value. Same as QUICKSTRING_FROMFLAGS::Hex.
QUICKSTRING_FROMFLAGS::Hex: Read a hexadecimal value. Same as QUICKSTRING_FROMFLAGS::Hexadecimal.
QUICKSTRING_FROMFLAGS::Binary: Read a binary value.
QUICKSTRING_FROMFLAGS::FormatMask: Used to mask these values, esp. when clearing flags.

Only one of the following may be used to specify what characters are ignored:

QUICKSTRING_FROMFLAGS::IgnoreComma

Ignore only the comma character (see QuickString::AutoComma).

eg, "1,2 3 Something 4" will return 12

QUICKSTRING_FROMFLAGS::AbortAlphaNum

Abort only on invalid alpha numeric characters.

eg, "1,2 3 Something 4" will return 123

QUICKSTRING_FROMFLAGS::IgnoreInvalid

Completely ignore all invalid characters.

eg, "1,2 3 Something 4" will return 1234

QUICKSTRING_FROMFLAGS::AbortInvalid

Abort immediately on hitting any invalid character.

eg, "1,2 3 Something 4" will return 1

QUICKSTRING_FROMFLAGS::InvalidMask

Used to mask these values, esp. when clearing flags.

QuickString::AutoComma

Byte, The auto comma character to use when converting integers to strings or strings to integers. This is not included if all *Int*ToString and StringToInt* functions are not included.

Use 0 to disable and ignore auto commas.

Default: ','

Configuration

Configuration is done in a Config/String.inc under the QuickString_Config scope.

Enable Functions

For each of these, a 0 means to not include it, a 1 means to include the small implementation, and a 2 means to include the fast but larger implementation if available.

Currently only TOUPPERLOWER, UINT16TOSTRING, and UINT32TOSTRING have fast implementations available.

General

QuickString_Config::GETLENGTH

Is QuickString::GetLength included?

QuickString_Config::CONVERT

Is QuickString::Convert included?

QuickString_Config::JOIN

Is QuickString::Join included?

QuickString_Config::COPY

Is QuickString::Copy included?

QuickString_Config::SUBSTRING

Are QuickString::Substring, QuickString::Right, and QuickString::Left included?

Updates

QuickString_Config::TOUPPERLOWER

Are QuickString::ToUpper and QuickString::ToLower included?

Supports a fast version:

This only changes the size by 6 bytes without ASCIIZ support. Compare ToUpperLower-Fast.asm to ToUpperLower-Small.asm to see the difference.

Default: 1

Small Version (1)

Size: 48 bytes

Cycles:

(# char * 26 to 31) + 24 (24 if blank) for ToUpper

(# char * 28 to 33) + 28 (28 if blank) for ToLower

Fast Version (2)

Size: 54 bytes (+6)

Cycles: (# char * 21 to 26) + 22 (~16% [Upper]/21% [Lower] faster)

QuickString_Config::ADDSEPARATOR

Is QuickString::AddSeparator included?

QuickString_Config::PAD

Is QuickString::Pad included?

QuickString_Config::REVERSE

Is QuickString::Reverse included?

Comparisons

QuickString_Config::FINDCHAR

Is QuickString::FindChar included?

QuickString_Config::COMPARE

Is QuickString::Compare included?

QuickString_Config::FIND

Is QuickString::Find included?

Requires QuickString_Config::COMPARE and QuickString_Config::FINDCHAR.

Integer to String

QuickScreenScript requires all of these to be included! Be certain they're included if using QuickScreenScript.

If all Int*ToString and StringToInt* functions are not included, QuickString::AutoComma is also not included.

QuickString_Config::UINT8TOSTRING

Is QuickString::UInt8ToString included?

QuickString_Config::SINT8TOSTRING

Is QuickString::SInt8ToString included?

Requires QuickString_Config::UINT8TOSTRING.

QuickString_Config::UINT16TOSTRING

Is QuickString::UInt16ToString included?

Supports a fast version:

Compare ToString-UInt16ToBCD-Fast.asm to ToString-UInt16ToBCD.asm to see the difference.

Default: 1

Small Version (1)

Size: 42 bytes

Cycles: 700

Fast Version (2)

Size: 74 bytes (+32)

Cycles: 497 (29% faster)

QuickString_Config::SINT16TOSTRING

Is QuickString::SInt16ToString included?

Requires QuickString_Config::UINT16TOSTRING.

QuickString_Config::UINT32TOSTRING

Is QuickString::UInt32ToString included?

Supports a fast version:

Compare ToString-UInt32ToBCD-Fast.asm to ToString-UInt32ToBCD.asm to see the difference.

Small Version (1)

Size: 58 bytes

Cycles: 2,268 cycles

Fast Version (2)

Size: 156 bytes (+98)

Cycles: 1,488 cycles (34.4% faster)

QuickString_Config::SINT32TOSTRING

Is QuickString::SInt32ToString included?

Requires QuickString_Config::UINT32TOSTRING.

Integer to Hex

QuickScreenScript requires all of these to be included! Be certain they're included if using QuickScreenScript.

QuickString_Config::INT8TOHEX

Is QuickString::Int8ToHex included?

QuickString_Config::INT16TOHEX

Is QuickString::Int16ToHex included?

QuickString_Config::INT32TOHEX

Is QuickString::Int32ToHex included?

String to Integer

All of these pass through a conversion to a potential 32-bit value, but then have additional handling for the target size. Including any of these will add a lot of code and only a small amount extra for each one included.

If all StringToInt* functions are not included, QuickString::FromFlags is also not included.

QuickString_Config::STRINGTOINT8

Is QuickString::StringToInt8 included?

QuickString_Config::STRINGTOINT16

Is QuickString::StringToInt16 included?

QuickString_Config::STRINGTOINT32

Is QuickString::StringToInt32 included?

Additional Configuration

QuickString_Config::SUPPORTASCIIZ

!!! This is not currently supported and may never actually be supported. !!!

Boolean, >0 to support ASCIIZ.

Not including ASCIIZ support makes things faster and smaller.

NOTE: QuickString::GetLength *ALWAYS* uses ASCIIZ and QuickString::Convert always works the same.

Default: 0

QuickString_Config::AUTOCLEARASCIIZ

Boolean, >0 to auto clear the SourceASCIIZ and DestASCIIZ flags when used.

NOTE: Even with ASCIIZ support disabled, this is still used in QuickString::GetLength.

Default: 0

Flags

QuickString_Config::FLAGS_CENTERBIASLEFT

Boolean, >0 to default to a left bias for centering. 0 to default to a right bias for centering.

This is only used for Pad and is ignored if QuickString_Config::PAD is 0.

To String

QuickString_Config::AUTOCOMMA

Byte, Default auto comma character. Use 0 for no auto commas. See QuickString::AutoComma.

Default: ','

From String

These are used by the StringTo* functions and are ignored if none of them are included.

QuickString_Config::FROMFLAGS_CLAMP

Boolean, >0 to default to clamping.

Default: 0

QuickString_Config::FROMFLAGS_SIGNED

Boolean, >0 to default to signed.

Default: 0

QuickString_Config::FROMFLAGS_FORMAT

Byte, The default format to use to convert strings.

Default: 0

0: Decimal.
1: Hexadecimal.
2: Binary.

QuickString_Config::FROMFLAGS_INVALID

Byte, The default invalid character treatment to use.

Default: 0

0

Ignore only the comma character. See QuickString::AutoComma.

eg, "1,2 3 Something 4" will return 12 if AutoComma is ','.

1

Abort only on invalid alpha numeric characters.

eg, "1,2 3 Something 4" will return 123.

2

Completely ignore all invalid characters.

eg, "1,2 3 Something 4" will return 1234 (if 16-bit or higher).

3

Abort immediate on hitting any invalid character.

eg, "1,2 3 Something 4" will return 1.