Language Intrinsics

Context: HL Kit … Kit Reference 

Overview

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.

Intrinsic Functions

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".
decimals	string decimals(number val, number dec) Returns a string that contains the rounded value of val, where dec indicates the number of decimal places at which to perform the rounding (normal rounding is always performed). In addition, if the value requires fewer decimal places than specified, zeroes are appended to bring the value to the full number of decimals. This intrinsic is ideal for formatting currency with a fixed number of decimals, so that "decimals(1.5,2) produces "1.50" instead of the normal "1.5".
ordinal	string ordinal(number val) Returns a string that contains the ordinal value of val. For example, 22 becomes "22nd" and 4444 becomes "4444th".
digitgroup	string digitgroup(number val) Returns a string that contains the comma digit grouped value of val. For example, 1000 becomes "1,000" and 3333.333 becomes "3,333.333".
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).
empty	number empty(string str) Returns a non-zero value if the string str has a length of zero characters, else a value of zero is returned. The "empty" intrinsic is significantly faster than using "length" and comparing it to zero.
plaintext	string plaintext(string str) Returns the string str with all encoded text stripped out. This provides a quick an easy mechanism for converting a string with encoded text (e.g. color usage) to its equivalent without any special formatting.
today	number today() Returns the current date in the proper format utilized by fields that store dates and times which users can edit via "editdate" portals. This provides a convenient mechanism for initializing journal entries and any other situations with the current date.

Examples

Simple examples of how to use each of the various intrinsic functions are provided below.

var str as string
var len as number
var piece as string
var temp as string
var val as number
var total as number
var NewLine as string
var tag_count as number
var link_count as number
str = "hello there world there"

~Get the length of the string, which is 23
len = length(str)

~Extract the first 5 character of the string, which is "hello"
piece = left(str,5)

~Extract the last 5 characters of the string, which is "there"
piece = right(str,5)

~Extract 5 characters from the string, starting at position 6, which is "there"
piece = mid(str,6,5)

~Locate the first occurrance of the string "there" within the string, which
~starts at position 6
val = pos(str,"there")

~Locate the last occurrance of the string "there" within the string, which
~starts at position 18
val = lastpos(str,"there")

~Convert a string to all uppercase, then to all lowercase
temp = uppercase(str)
temp = lowercase(str)

~Get the ASCII value of the first character of the string
val = asc(str)

~Create a string of one character, where that character is an 'A'
piece = chr(65)

~Create a string of one character, where that character is a newline
NewLine = chr(10)

~Compare the two strings, with the first string being less than the second
val = compare(str,"second")

~Replace all instances of "there" with "change"
temp = replace(str,"there","change",0) 

~Extract the integer portion only of –123.45, which is –123
val = int(-123.45)

~Generate a random number between 0 and 9
val = random(10)

~Determine the lower and higher of two values
val = minimum(123.45,val)
val = maximum(123.45,val)

~Calculate 4 squared, which yields 16
val = power(4,2)

~Calculate the square root of 16, which yields 4
val = nthroot(16,2)

~Round the value 4.36 normally to one decimal place, which yields 4.4
val = round(4.36,1,0)

~Get the signed version of a value
temp = signed(-123.45)

~Convert a value to formatted currency
temp = "$" & decimals(1.5,2)

~Generate the ordinal version of a value
temp = ordinal(22)

~Generate the digit grouped version of a value
temp = digitgroup(1000)

~Perform bitwise operations on two values
total = bitwise_and(14,7)
total = bitwise_or(10,3)
total = bitwise_xor(14,7)
total = bitwise_not(9)

~Determine if a string is empty
value = empty(str)