# Difference between revisions of "Language Intrinsics"

(→Examples) |
(→Intrinsic Functions) |
||

Line 115: | Line 115: | ||

|number empty(string str) | |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. | 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 | |today |

## Revision as of 01:57, 12 May 2009

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".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) ~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)