Language Intrinsics
Context: HL Kit … Kit Reference
The scripting language has an assortment of intrinsic (i.e. built-in) functions that can be used for various purposes. Some intrinsic functions operate on strings, while others operate on numbers. Some intrinsic functions return strings, while others return numbers.
The purpose of intrinsic functions is to provide authors with re-usable mechanisms that can be used to perform script operations that arise on a recurring basis. For example, the Kit includes intrinsic functions for searching string, carving up strings, comparing strings, and replacing text within strings. Intrinsics are also included to determine the minimum or maximum of two values, round a number off at a certain level of precision, and generate a random number.
The complete list of intrinsic functions provided by the language is presented below.
length number length(string str)
Returns the number of characters in the string str.
left string left(string str, number num) Returns a new string containing the leftmost num characters of the string str.
right string right(string str, number num) Returns a new string containing the rightmost num characters of the string str.
mid string mid(string str, number start, number num) Returns a new string containing a substring of string str. The new string begins with the character at position start and is num characters in length. Character positions are 0-based, so the first character in a string is at position zero (0).
pos number pos(string str, string search) Return the character position where the string search first appears within str. Character positions are 0-based, so the first character in a string is at position zero (0). If search does not exist within str, a value of –1 is returned.
uppercase string uppercase(string str) Returns a new string that is an upper case version of string str.
lowercase string lowercase(string str) Returns a new string that is an lower case version of string str.
lastpos number lastpos(string str, string search) Return the character position where the string search last appears within str. Character positions are 0-based, so the first character in a string is at position zero (0). If search does not exist within str, a value of –1 is returned.
asc number asc(string str) Returns the ASCII value of the first character of string str.
chr string chr(number val) Returns a new string that consists of a single character, which has an ASCII value of val. For example, 'chr(10)' is the newline character.
compare number compare(string str1, string str2) Compare the two strings str1 and str2. If the strings are identical, the value 0 is returned. If str1 would appear before str2 in an alphabetical sort (based on the ASCII code of each character), a value less than 0 is returned. If str1 would appear after str2 in an alphabetical sort, a value greater than 0 is returned. Note that all uppercase characters are sorted before lowercase characters.
replace string replace(string str, string match, string replace, number maxcount) Searches through the string str and replaces all instances of the string match with the string replace. A maximum number of replacements is given by maxcount, with a value of zero indicating that all matches should be replaced. The converted string is returned, with the original string left untouched.
int number int(number val) Returns a value that represents the integer portion only of val. For example, the integer portion of the value –123.45 would be –123.
random number random(number range) Returns a random integer value between zero and range–1.
minimum number minimum(number val1, number val2) Returns the lower of the two values given.
maximum number maximum(number val1, number val2) Returns the higher of the two values given.
power number power(number val1, number val2) Returns val1 raised to the power of val2 (e.g. x^y). For example, "power(4,2)" would yield 4 squared, which is 16.
nthroot number nthroot(number val, number nth) Returns the nth root of a number, where val is the value to get the root of and nth indicates the root to obtain. For example, "nthroot(16,2)" would yield the square root of 16, which is 4.
round number round(number val, number dec, number dir) Returns the rounded value of val, where dec indicates the number of decimal places at which to perform the rounding and dir indicates how to perform the rounding. If dir is zero, normal rounding is performed (e.g. 0.5-0.99 round up to 1.0 and 0.01-0.49 round down to 0.0). If dir is positive, the value is always rounded up. If dir is negative, the value is always rounded down. For example, "round(4.36,1,0)" would yield 4.4 and "round(4.36,1,-1)" would yield 4.3.
signed string signed(number val) Returns a string that represents the properly signed version of 'val', including a prefix of either '+' or '-'. For example, the signed version of the value 1.42 would be "+1.42", while the signed version of the value -6.23 would be "-6.23".
bitwise_and number bitwise_and(number val1, number val2) Returns the bit-wise "and" of val1 and val2, treating both parameters as integer values for the operation. The bit-wise "and" performs a comparison of the two values, one bit at a time, with the resulting value having a bit value of 1 only if both val1 and val2 have that bit set to 1. For example, "bitwise_and(14,7)" would yield 6, since the two parameters have binary representations of "1110" and "0111", which results in a value with a binary representation of "0110" (or 6).
bitwise_or number bitwise_or(number val1, number val2) Returns the bit-wise "or" of val1 and val2, treating both parameters as integer values for the operation. The bit-wise "or" performs a comparison of the two values, one bit at a time, with the resulting value having a bit value of 1 if either val1 or val2 has that bit set to 1, or if both have the bit set to 1. For example, "bitwise_or(10,3)" would yield 12, since the two parameters have binary representations of "1010" and "0011", which results in a value with a binary representation of "1011" (or 12).
bitwise_xor number bitwise_xor(number val1, number val2) Returns the bit-wise "xor" of val1 and val2, treating both parameters as integer values for the operation. The bit-wise "xor" performs a comparison of the two values, one bit at a time, with the resulting value having a bit value of 1 only if one of val1 and val2 have that bit set to 1 - not both. For example, "bitwise_xor(14,7)" would yield 9, since the two parameters have binary representations of "1110" and "0111", which results in a value with a binary representation of "1001" (or 9).
bitwise_not number bitwise_not(number val) Returns the bit-wise "not" of val, treating the parameter as an integer value for the operation. The bit-wise "not" processes the value, one bit at a time, with the resulting value having each bit possess the opposite value that it started with. This means that any bit with a value of 1 becomes 0, and vice versa. For example, "bitwise_not(9)" would yield 6, since the parameter has a binary representation of "1001", which results in a value with a binary representation of "0110" (or 6).
-The "today()" intrinsic retrieves the current date in the proper format used
-Provides a convenient means of getting today's date for journal entries and such
-Scripting language has an "empty" intrinsic function that takes a single string
as a parameter and returns non-zero if the string is of zero length
-This is much faster than calculating the full length and then comparing it
to a value of zero
