HSLStrLib

https://github.com/theonetruenerd/VenusPackages/blob/main/HSLStrLib.pkg

HSL String Library provides the following functions:

• StrAsciiToStr()

• StrConcat2()

• StrConcat4()

• StrConcat8()

• StrConcat12()

• StrEvaluateExpr()

• StrFillLeft()

• StrFillRight()

• StrFind()

• StrFStr()

• StrFStrEx()

• StrFVal()

• StrGetLength()

• StrGetType()

• StrHexIStr()

• StrIsDigit()

• StrIStr()

• StrIVal()

• StrLeft()

• StrMakeLower()

• StrMakeLowerCopy()

• StrMakeUpper()

• StrMakeUpperCopy()

• StrMid()

• StrReplace()

• StrReverseFind()

• StrRight()

• StrSpanExcluding()

• StrStrToAscii()

• StrTrimLeft()

• StrTrimRight()

StrAsciiToStr(variable asciiCode)

Converts the given ASCII Code (an integer) to a character (string).

Parameters:

asciiCode (Integer) – The ASCII code to convert

Returns:

The ASCII code as a string

Return type:

String

StrConcat2(variable Var1, variable Var2)

Combines two strings into a new string

Parameters:

• Var1 (String) – The first string to be combined

• Var2 (String) – The second string to be combined

Returns:

The combined string of Var1 + Var2

Return type:

String

StrConcat4(variable Var1, variable Var2, variable Var3, variable Var4)

Combines four strings into a new string

Parameters:

• Var1 (String) – The first string to be combined

• Var2 (String) – The second string to be combined

• Var3 (String) – The third string to be combined

• Var4 (String) – The fourth string to be combined

Returns:

The combined string of Var1 + Var2 + Var3 + Var4

Return type:

String

StrConcat8(variable Var1, variable Var2, variable Var3, variable Var4, variable Var5, variable Var6, variable Var7, variable Var8)

Combines eight strings into a new string

Parameters:

• Var1 (Variable) – The first string to be combined

• Var2 (Variable) – The second string to be combined

• Var3 (Variable) – The third string to be combined

• Var4 (Variable) – The fourth string to be combined

• Var5 (Variable) – The fifth string to be combined

• Var6 (Variable) – The sixth string to be combined

• Var7 (Variable) – The seventh string to be combined

• Var8 (Variable) – The eighth string to be combined

Returns:

The combined string of Var1 + Var2 + Var3 + Var4 + Var5 + Var6 + Var7 + Var8

Return type:

String

StrConcat12(variable Var1, variable Var2, variable Var3, variable Var4, variable Var5, variable Var6, variable Var7, variable Var8, variable Var9, variable var10, variable var11, variable var12)

Combines twelve strings into a new string

Parameters:

• Var1 (Variable) – The first string to be combined

• Var2 (Variable) – The second string to be combined

• Var3 (Variable) – The third string to be combined

• Var4 (Variable) – The fourth string to be combined

• Var5 (Variable) – The fifth string to be combined

• Var6 (Variable) – The sixth string to be combined

• Var7 (Variable) – The seventh string to be combined

• Var8 (Variable) – The eighth string to be combined

• Var9 (Variable) – The ninth string to be combined

• Var10 (Variable) – The tenth string to be combined

• Var11 (Variable) – The eleventh string to be combined

• Var12 (Variable) – The twelfth string to be combined

Returns:

The combined string of Var1 + Var2 + Var3 + Var4 + Var5 + Var6 + Var7 + Var8 + Var9 + Var10 + Var11 + Var12

Return type:

Variable

StrEvaluateExpr(variable expression)

This function evaluates an expression within a string. All variables involved must have global scope.

Params expression:

The expression to evaluate as a string

Returns:

The value of the expression if the function succeeds, otherwise a runtime error

Return type:

Variable

StrFillLeft(variable str, variable character, variable width)

This function fills leading characters to the string

Params str:

The string to be modified

Params character:

The user-defined character to be filled

Params width:

The width to be filled

Returns:

The modified string

Return type:

Variable

StrFillRight(variable str, variable character, variable width)

This function fills trailing characters to the string

Params str:

The string to be modified

Params character:

The user-defined character to be filled

Params width:

The width to be filled

Returns:

The modified string

Return type:

Variable

StrFind(variable str, variable subStr)

This function searches the string for the first match of the sub-string.

Params str:

The string to be searched

Params subStr:

The substring to be searched for

Returns:

The zero-based index of the first character in this string object that matches the requested sub-string or characters. -1 if the sub-string is not found.

Return type:

Integer

StrFStr(variable number)

This function converts the floating point number input into the corresponding character string.

Params number:

The float to be converted into a string

Returns:

The string form of the float

Return type:

Variable

StrFStrEx(variable number, variable languageSpecific, variable precision)

This function converts the floating point number input into the corresponding character string

Params number:

The float to be converted into a string.

Params languageSpecific:

Boolean which specifies whether the decimal symbol in the Regional Settings should be used to write the string representation of the floating point number.

Params precision:

The total number of significant digits to be used for the floating-point display

Returns:

The string representation of the floating point number

Return type:

Variable

StrFVal(variable str)

Converts the sequence of digits, contained in the character string str, into the corresponding floating point number. Conversion aborts at the first character in str, which is not a digit or not one of the characters +, -, e, E.

Params str:

The string to be converted

Returns:

THe float representation of the input string. Null if the string cannot be converted. DBL_MAX if the conversion results in an overflow. DBL_MIN if the conversion results in an underflow.

Return type:

Float or variable

StrGetLength(variable str)

Returns the number of characters in a string object (without ‘0’).

Params str:

The string being read

Returns:

The length of the string

Return type:

Integer

StrGetType(variable var)

This function retrieves the type of the value of a variable

Params var:

A reference to a variable (int, float or string)

Returns:

One of the following string-valued constants that indicates the type of the value of a variable. i = hslInteger, f = hslFloat, s = hslString, null = no type

Return type:

Variable

StrHexIStr(variable number)

Converts the input integer into the corresponding hexadecimal character string

Params number:

The integer to be converted

Type:

Integer

Returns:

The hexadecimal string representation of the integer

Return type:

String

StrIsDigit(variable character)

The StrIsDigit function determines if the specified input string (which should be a character) is a digit or not.

Params character:

The input character to be a tested, as a string

Returns:

Boolean showing whether the character is a digit (1) or not (0)

Return type:

Boolean

StrIsStr(variable number)

The StrIStr function converts the input integer into the corresponding character string

Params number:

The integer to be converted

Returns:

The string representation of the integer number

Return type:

Variable

StrIVal(variable str)

The StrIVal function converts the input sequence of digits into the corresponding integer. The input string is treated as a decimal, unless it begins with an 0x in which case it is interpreted as hexadecimal. Conversion aborts at the first character in the input which is neither a digit nor one of the characters “+” or “-“.

Params str:

The input sequence of digits to be converted

Returns:

The numeric value of the sequence of digits contained in the character string, as an integer. Null if the character string cannot be converted into a number. LONG_MAX = 2147483647 if the conversion results in an overflow. LONG_MIN = -2147483647 - 1 if the conversion results in an underflow.

Return type:

Variable

StrLeft(variable str, variable count)

The StrLeft function extracts the first (leftmost) characters of a string and returns a copy of the extracted substring. The number of characters extracted is equal to the input variable “count”. If “count” is longer than the string, the entire string is returned.

Params str:

The input string from which the substring is to be extracted

Params count:

The number of characters to be extracted

Returns:

A string containing a copy of the specified range of characters. Can be an empty string.

Return type:

Variable

StrMakeLower(variable str)

The StrMakeLower function converts the original string to its lowercase form.

Params str:

The string to be converted

Returns:

The original string converted to lowercase

Return type:

Variable

StrMakeLowerCopy(variable str)

The StrMakeLowerCopy function returns a copy of the original string converted to lowercase.

Params str:

The string to be copied

Returns:

A copy of the original string converted to lowercase

Return type:

Variable

StrMakeUpper(variable str)

The StrMakeUpper function converts the original string to its uppercase form.

Params str:

The string to be converted

Returns:

The original string converted to uppercase

Return type:

Variable

StrMakeUpperCopy(variable str)

The StrMakeUpperCopy function returns a copy of the original string converted to uppercase.

Params str:

The string to be copied

Returns:

A copy of the original string converted to uppercase

Return type:

Variable

StrMid(variable str, variable first, variable count)

The StrMid function extracts a substring of length “count” characters from the input variable “str”, starting at position “first” which is 0-based. The function returns a copy of the extracted substring.

Params str:

The string from which the substring is to be extracted

Params first:

The first character to be extracted (0-based)

Params count:

The number of characters to be extracted

Returns:

A string containing a copy of the specified range of characters, can be empty

Return type:

Variable

StrReplace(variable str, variable oldSubStr, variable newSubStr)

The StrReplace function searches a string for a specified substring and replaces it with another specified substring.

Params str:

The string to be edited

Params oldSubStr:

The substring to be replaced by newSubStr

Params newSubStr:

The substring to replace oldSubStr

Returns:

The number of replaced instances of oldSubStr. Zero if the string is unchanged.

Return type:

Variable

StrReverseFind(variable str, variable subStr)

The StrReverseFind function searches a string object for the last match of a sub-string

Params str:

The string to be searched

Params subStr:

The substring to be searched for

Returns:

The zero-based index of the last character in this string that matches the requested substring or characters. -1 if the substring is not found.

Return type:

Variable

StrRight(variable str, variable count)

The StrRight function extracts the last (rightmost) characters of a string and returns a copy of the extracted substring. The number of characters extracted is equal to the input variable “count”. If “count” is longer than the string, the entire string is returned.

Params str:

The input string from which the substring is to be extracted

Params count:

The number of characters to be extracted

Returns:

A string containing a copy of the specified range of characters. Can be an empty string.

Return type:

Variable

StrSpanExcluding(variable str, variable subStr)

The StrSpanExcluding function can be used to search the string for the first occurrence of any character in the specified set subStr. StrSpanExcluding extracts and returns all characters preceding the first occurrence of a character from subStr (in other words, the character from subStr and all characters following it in the string, are not returned). If no character from subStr is found in the string, then StrSpanExcluding returns the entire string.

Params str:

The string to be searched

Params subStr:

A string containing the set of characters to be searched for

Returns:

A sub-string containing characters in the string that are not in subStr, beginning with the first character in the string and ending with the first character found in the string that is also in subStr (that is, starting with the first character in the string and up to but excluding the first character in the string that is found subStr). It returns the entire string if no character in subStr is found in the string.

Return type:

Variable

StrStrToAscii(variable character)

The StrStrToAscii function converts the given character (as a string) into an ASCII code (as an integer)

Params character:

The character to convert, inputted as a string

Returns:

The ASCII code for the given character as an integer, -1 if the function fails

Return type:

Variable

StrTrimLeft(variable str, variable character)

The StrTrimLeft function trims leading whitespace characters from the string (removes newline, space, tab, and user-defined characters)

Params str:

The string to trim

Params character:

A string containing user-defined characters to be trimmed (may be empty, in which case only newline, space and tabs will be trimmed)

Returns:

None

Return type:

N/A

StrTrimRight(variable str, variable character)

The StrTrimRight function trims lagging whitespace characters from the string (removes newline, space, tab, and user-defined characters)

Params str:

The string to trim

Params character:

A string containing user-defined characters to be trimmed (may be empty, in which case only newline, space and tabs will be trimmed)

Returns:

None

Return type:

N/A