Language Intrinsics

From HLKitWiki
Jump to: navigation, search

Context: HL KitKit 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)