Difference between revisions of "Language Intrinsics"

From HLKitWiki
Jump to: navigation, search
Line 12: Line 12:
 
Returns the number of characters in the 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.
 
|-
 
|-
|
+
|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. There is no need for a bit-wise "or" operation, since that can be readily achieved by simply adding two integer values together. 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).
 
|-
 
|-
 
|
 
|

Revision as of 04:55, 4 December 2008

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

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. There is no need for a bit-wise "or" operation, since that can be readily achieved by simply adding two integer values together. 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).