the abs of factor
abs ( expression )
Factor and expression yield integers, numbers, or complexes.
+put abs(a-b) into theDifference ++
The abs function returns the absolute value of its argument.
If the argument is an integer, an integer is returned.
If the argument is a number, a number is returned.
If the argument is a complex, a complex is returned. The returned complex will have a real part of the distance of the passed in complex from the origin, and an imaginary part of zero.
This function is similar to the hypot and radius functions, but takes one numeric argument rather than a list.
the annuity of ( rate , periods )
annuity ( rate , periods )
Rate and periods yield integers, numbers, or complexes.
+put myPayment*annuity(.015,12) into presentValue ++
+put myPayment*annuity(.015,12)*compound(.015,12) ¬ + into futureValue ++
The annuity function is used to calculate the present or future value of an ordinary annuity. Rate is the interest rate per period, and periods is the number of periods over which the value is calculated.
The formula for the annuity function is:
annuity(rate, periods) = (1-((1+rate)^(-periods)))/rate
The annuity function is faster and more accurate than using the above formula.
You can use complex arguments to this function, but what this means exactly is up to the accountants and economists to figure out, not me.
the atan of factor
atan ( expression )
Factor and expression yield integers, numbers, or complexes.
+put atan(theTangent) into theAngle ++
The atan function returns the inverse tangent of its argument.
If the argument is an integer or a number, a number is returned.
If the argument is a complex, a complex is returned.
the average of factor
average ( expression )
Factor and expression yield lists of integers, numbers, or complexes.
+put average(1,3,4) into bill ++
The average function returns the arithmetic mean, or average, of the numeric values passed to it. This is equal to the sum of the passed values divided by the number of values.
If all the values are integers or numbers, a number is returned. If any value is a complex, a complex is returned.
the charToNum of factor
charToNum ( expression )
Factor and expression yield a character.
++put the charToNum of "a" into it -- yields 97 ++
The charToNum function returns the equivalent value of the character passed to it in the text encoding specified by the textEncoding property.
If more than one character is passed, charToNum returns the value of the first character.
the compound of ( rate , periods )
compound ( rate , periods )
Rate and periods yield integers, numbers, or complexes.
+put futureValue/compound(.10,12) into presentValue ++
+put presentValue*compound(.10,12) into futureValue ++
The compound function is used to calculate the present or future value of a compound interest-bearing account. Rate is the interest rate per period, and periods is the number of periods over which the value is calculated.
The formula for the compound function is:
compound(rate, periods) = (1+rate)^periods
The compound function is faster and more accurate than using the above formula.
The following example calculates the value in one year of an account earning 7.5 percent interest compounded monthly:
++on calcInterest + ask "Enter the beginning balance:" with empty + put "Value in 1 year $" & it * compound(.075/12, 12) +end calcInterest ++
You can use complex arguments to this function, but what this means exactly is up to the accountants and economists to figure out, not me.
the cos of factor
cos ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the cos of 2 -- yields -0.416147 ++
The cos function returns the cosine of the angle that is passed to it. The angle must be expressed in radians.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
Radians can be converted to degrees with the toDegrees function, or by multiplying by 180 and dividing by pi. Degrees can be converted to radians with the toRadians function, or by multiplying by pi and dividing by 180.
the modifier date
date ()
Modifier is short, abbreviated, long, or English. The default is short.
+put the last word of the long date into currentYear ++
The date function returns a date representing the current date. There are four forms of the date function:
the short date |
+20/7/93 |
+
the abbrev date |
+Tue 20 Oct 1992 |
+
the long date |
+Tuesday 7 October 1989 |
+
the English date |
+Saturday, February 15, 1986 |
+
The format of the date is dependent on the current locale. This is important if you want to write scripts that work anywhere without modification. You cannot assume that the date function will always return a date in the same format.
To prevent issues caused by differing local date formats, use the seconds or the dateItems to store and perform calculations with dates and times.
the exp of factor
exp ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the exp of 2 -- yields 7.389056 ++
The exp function returns the mathematical exponential of its argument, defined as the constant e, which is approximately 2.7182818284, raised to the power specified by the argument. That is, it returns:
euler^number
The exp function is faster and more accurate than using the above formula.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
the exp1 of factor
exp1 ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the exp1 of 2 -- yields 6.389056 ++
The exp1 function returns 1 less than the mathematical exponential of its argument. That is, it returns:
( euler^number)-1
The exp1 function is faster and more accurate than using the above formula.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
the exp2 of factor
exp2 ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the exp2 of 16 -- yields 65536 ++
The exp2 function returns the value of 2 raised to the power specified by its argument. That is, it returns:
2^number
The exp2 function is faster and more accurate than using the above formula.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
the heapSpace
heapSpace ()
+put the heapSpace into heapOFun ++
In OpenXION, the heapSpace function returns the number of bytes of heap space currently available to the Java virtual machine.
In HyperTalk, the heapSpace function returns the number of bytes of heap space currently available to HyperCard.
To use this function, OpenXION's security settings must allow the SYSTEM_INFO security key. If the required security key is denied, a script error will be triggered.
This page describes the functions supported by HyperTalk.
+absannuityatanaveragecharToNumcompoundcosdateexpexp1exp2heapSpacelengthlnln1log2maxminnumbernumToCharoffsetparamparamCountparamsrandomresultroundsecondssecsserialPortssinsoundspeechsqrtsumsystemVersiontantickstimetruncvalueversionvoicesthe length of factor
length ( expression )
Factor and expression yield strings.
put length("tail") into it -- yields 4
put length("Nu är det slut…") -- yields 15
if the length of word n of steve > 25 ¬
then add 1 to fogIndex
The length function returns the number of characters (including spaces, tabs, line breaks, and other control and formatting characters) in the string passed to it.
The expression length(factor)the number of characters in factor but is more efficient.
the ln of factor
ln ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the ln of 10 -- yields 2.302585 ++
The ln function returns the base-e (natural) logarithm of the number passed to it.
If the argument is a positive integer or number, a number is returned. If the argument is zero, negative infinity is returned. If the argument is a negative integer or number, NaN is returned. To get a complex result, convert the argument to a complex.
If the argument is a complex, a complex is returned.
the ln1 of factor
ln1 ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the ln1 of 10 -- yields 2.397895 ++
The ln1 function returns the base-e (natural) logarithm of 1 plus the number passed to it. That is, it returns:
ln(1+number)
The ln1 function is faster and more accurate than using the above formula.
If the argument is an integer or a number greater than -1, a number is returned. If the argument is -1 exactly, negative infinity is returned. If the argument is an integer or a number less than -1, NaN is returned. To get a complex result, convert the argument to a complex.
If the argument is a complex, a complex is returned.
the log2 of factor
log2 ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the log2 of 10 -- yields 3.321928 ++
The log2 function returns the base-2 (binary) logarithm of the number passed to it.
If the argument is a positive integer or number, a number is returned. If the argument is zero, negative infinity is returned. If the argument is a negative integer or number, NaN is returned. To get a complex result, convert the argument to a complex.
If the argument is a complex, a complex is returned.
the max of factor
max ( expression )
Factor and expression yield any kind of list.
The max function returns the largest element of its arguments. The elements are compared as if by the > operator.
the min of factor
min ( expression )
Factor and expression yield any kind of list.
The min function returns the smallest element of its arguments. The elements are compared as if by the < operator.
the number of factor
number ( expression )
Factor and expression yield chunk expressions, lists, or objects.
++get the number of elements in steve ++
+get the number of words in bill ++
+get the number of andy ++
For chunk expressions, the number function returns the number of chunks in a range.
For lists, the number function returns the number of elements in a list.
For objects, the number function returns the index of an object.
the numToChar of factor
numToChar ( expression )
Factor and expression yield non-negative integers.
+put numToChar(67) into it -- yields C ++
The numToChar function returns the character whose equivalent value in the text encoding specified by the textEncoding property is that of the integer passed to it.
In HyperTalk, numToChar(0) triggers a script error. In XION, numToChar(0) returns null.
the offset of ( needle , haystack )
offset ( needle , haystack )
Haystack and needle yield strings.
The offset function returns the index of the first appearance of the string needle in the string haystack, starting at 1. If needle cannot be found in haystack, zero is returned.
This function is case-insensitive. For a case-sensitive version of this function, see csOffset. For a regular expression-based version of this function, see regOffset.
This function is similar to instr, but the arguments are in reverse order.
the param of factor
param ( expression )
Factor and expression yield integers.
+if param(1) is empty then answer ¬ + "The first parameter is null." ++
The param function returns a parameter value from the parameter list passed to the currently executing handler. The parameter returned is the nth parameter, where n is the integer passed to the function. The value of param(0) is the message name.
The following example sums the arguments passed to it, regardless of how many there are. In other words, it is functionally equivalent to the sum function:
+function addUp + put 0 into total + repeat with i = 1 to the paramCount + add param(i) to total + end repeat + return total +end addUp ++
the paramCount
paramCount ()
+if the paramCount < 3 then ¬ + put "I need at least three arguments." ++
The paramCount function returns the number of parameters passed to the currently executing handler.
The following example multiplies the arguments passed to it, regardless of how many there are. In other words, it is functionally equivalent to the product function:
+function theProduct + put 1 into total + repeat with i = 1 to the paramCount + multiply total by param(i) + end repeat + return total +end theProduct ++
the params
params ()
+put the params ++
In XION, the params function returns a list of the parameters passed to the currently executing handler, not including the message name. In other words, the params looks like:
parameter,parameter,parameter,...
In HyperTalk, the params function returns a string containing the message name and the entire parameter list passed to the currently executing handler. The returned string is suitable for the do keyword (if the handler is a message handler) or the value function (if the handler is a function handler). In other words, the params looks like:
messageName "parameter","parameter","parameter",...
or:
+ functionName("parameter","parameter","parameter",...)
the random of factor
random ( expression )
Factor and expression yield integers.
The random function returns a random integer between 1 and the specified integer, inclusive. If the specified integer is less than 1, the random function always returns 1.
The following example draws 10 unique random numbers between 1 and 100:
++on drawRandom + put empty into randomList + repeat until the number of items in randomList is 10 + get random of 100 + if (the itemdelimiter & it & the itemdelimiter) is not in ¬ + (the itemdelimiter & randomList & the itemdelimiter) then + put it & the itemdelimiter after randomList + end if + end repeat + delete last char of randomList + put randomList +end drawRandom ++ + diff --git a/Docs/hyp/2.2/fn/result.html b/Docs/hyp/2.2/fn/result.html new file mode 100644 index 00000000..2a38c377 --- /dev/null +++ b/Docs/hyp/2.2/fn/result.html @@ -0,0 +1,32 @@ + + +
the result
result ()
+if the result is not empty then answer "Try again." ++
The result function returns the return value of the last command executed. Most built-in commands only set the result if the command was executed unsuccessfully; otherwise, the result is set to empty. A user-defined command can set the result with a return statement. The answer and ask commands use the result to tell the script if the user cancelled a prompt instead of choosing a proper response.
the round of factor
round ( expression )
Factor and expression yield integers, numbers, or complexes.
+put round(steve) into bill ++
The round function returns the given value rounded towards the nearest integer. If the given value is an integer, the given value is returned. Otherwise, the given value is rounded to the nearest integer. If the fractional part of the given value is exactly .5, the given value is rounded towards unsigned infinity, or away from zero.
The following table illustrates the behavior of the round function:
| argument | +result | +
|---|---|
| 2 | +2 | +
| 1.75 | +2 | +
| 1.5 | +2 | +
| 1.25 | +1 | +
| 1 | +1 | +
| 0.75 | +1 | +
| 0.5 | +1 | +
| 0.25 | +0 | +
| 0 | +0 | +
| -0.25 | +0 | +
| -0.5 | +-1 | +
| -0.75 | +-1 | +
| -1 | +-1 | +
| -1.25 | +-1 | +
| -1.5 | +-2 | +
| -1.75 | +-2 | +
| -2 | +-2 | +
If the given value is a complex, the real and imaginary parts of the complex number are each rounded individually.
The following table shows the correspondences among the various roundingMethods, rounding functions, and division operators:
+rounding parameter |
+function | +operator | +java.math.RoundingMode |
+
|---|---|---|---|
to ceiling |
+ceil |
++ | CEILING |
+
to floor |
+floor |
+div / mod |
+FLOOR |
+
up / to infinity |
+aug |
++ | UP |
+
down / to zero |
+trunc |
+quot / rem |
+DOWN |
+
to nearest |
+round |
++ | HALF_UP |
+
to even |
+rint |
++ | HALF_EVEN |
+
The following table illustrates the behavior of the rounding functions side-by-side:
+| argument | +ceil |
+floor |
+aug |
+trunc |
+round |
+rint |
+
|---|---|---|---|---|---|---|
| 2 | +2 | +2 | +2 | +2 | +2 | +2 | +
| 1.75 | +2 | +1 | +2 | +1 | +2 | +2 | +
| 1.5 | +2 | +1 | +2 | +1 | +2 | +2 | +
| 1.25 | +2 | +1 | +2 | +1 | +1 | +1 | +
| 1 | +1 | +1 | +1 | +1 | +1 | +1 | +
| 0.75 | +1 | +0 | +1 | +0 | +1 | +1 | +
| 0.5 | +1 | +0 | +1 | +0 | +1 | +0 | +
| 0.25 | +1 | +0 | +1 | +0 | +0 | +0 | +
| 0 | +0 | +0 | +0 | +0 | +0 | +0 | +
| -0.25 | +0 | +-1 | +-1 | +0 | +0 | +0 | +
| -0.5 | +0 | +-1 | +-1 | +0 | +-1 | +0 | +
| -0.75 | +0 | +-1 | +-1 | +0 | +-1 | +-1 | +
| -1 | +-1 | +-1 | +-1 | +-1 | +-1 | +-1 | +
| -1.25 | +-1 | +-2 | +-2 | +-1 | +-1 | +-1 | +
| -1.5 | +-1 | +-2 | +-2 | +-1 | +-2 | +-2 | +
| -1.75 | +-1 | +-2 | +-2 | +-1 | +-2 | +-2 | +
| -2 | +-2 | +-2 | +-2 | +-2 | +-2 | +-2 | +
the seconds
seconds ()
+put (the seconds-startTime) into runTime ++
The seconds function returns an integer representing the number of seconds since midnight, January 1, 1904, known as the Mac OS epoch.
the secs
secs ()
+put (the seconds-startTime) into runTime ++
The secs function returns an integer representing the number of seconds since midnight, January 1, 1904, known as the Mac OS epoch.
the serialPorts
serialPorts ()
+put the serialPorts ++
The serialPorts function returns a lineEnding-delimited list of communications ports. These are the possible values of the dialingPort property, which determines the port used to dial phone numbers with a modem.
In HyperTalk, this function existed but was undocumented.
+ To use the serialPorts function, OpenXION's security settings must allow the SYSTEM_INFO security key. If the required security key is denied, a script error will be triggered.
the sin of factor
sin ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the sin of 2 -- yields 0.909297 ++
The sin function returns the sine of the angle that is passed to it. The angle must be expressed in radians.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
Radians can be converted to degrees with the toDegrees function, or by multiplying by 180 and dividing by pi. Degrees can be converted to radians with the toRadians function, or by multiplying by pi and dividing by 180.
the sound
sound ()
+put the sound ++
+wait until the sound is "done" ++
The sound function returns the name of the instrument currently playing on the current soundChannel, or the string "done" if no instrument is currently playing.
The "done" string is a literal; it is not a constant like zero or true. In HyperTalk code, the "done" literal is often left unquoted, but in XION this is highly discouraged.
the speech
speech ()
+put the speech ++
+wait until the speech is "done" ++
The speech function returns the currently generated speech text, or the string "done" if no speech is currently being generated.
The "done" string is a literal; it is not a constant like zero or true. In HyperTalk code, the "done" literal is often left unquoted, but in XION this is highly discouraged.
the sqrt of factor
sqrt ( expression )
Factor and expression yield integers, numbers, or complexes.
+put sqrt(opposite^2 + adjacent^2) into hypotenuse ++
The sqrt function returns the square root of its argument.
If the argument is an integer or a number, a number is returned. If the integer or number is negative, NaN is returned. To get a complex result, convert the argument to a complex.
If the argument is a complex, a complex is returned.
the sum of factor
sum ( expression )
Factor and expression yield lists of integers, numbers, or complexes.
+get sum(1,2,3,4) ++
The sum function returns the sum of a list of numeric values passed to it.
If all the values are integers or numbers, a number is returned. If any value is a complex, a complex is returned.
This is the infinite-arity version of the + operator.
the systemVersion
systemVersion ()
+put the systemVersion ++
The systemVersion function returns the version of the operating system. You might use this to determine whether a script will run correctly under that version of the operating system.
In HyperTalk, the resulting value of this function is a number. In XION, the resulting value of this function cannot be guaranteed to be anything other than a string.
OpenXION gets the value of this function from the os.version system property.
To use this function, OpenXION's security settings must allow the SYSTEM_INFO security key. If the required security key is denied, a script error will be triggered.
the tan of factor
tan ( expression )
Factor and expression yield integers, numbers, or complexes.
+put the tan of 2 -- yields -2.185040 ++
The tan function returns the tangent of the angle that is passed to it. The angle must be expressed in radians.
If the argument is an integer or a number, a number is returned. If the argument is a complex, a complex is returned.
Radians can be converted to degrees with the toDegrees function, or by multiplying by 180 and dividing by pi. Degrees can be converted to radians with the toRadians function, or by multiplying by pi and dividing by 180.
the ticks
ticks ()
+put the ticks into dog ++
The ticks function returns the number of ticks (sixtieths of a second) since an implementation-specific reference point in time.
In HyperTalk, the reference point is the last time the computer was turned on or restarted. In OpenXION 1.3 and earlier, the reference point is roughly the release date of the interpreter. In OpenXION 1.4 and later, the reference point is the time when the JVM was started. The XION Scripting Language Standard states only that the reference point must remain constant during the same instance of the interpreter program.
+the modifier time
time ()
Modifier is short, abbreviated, long, or English. The default is short.
+put the time ++
The time function returns a date representing the current time. There are three forms of the time function:
the short time or the abbrev time |
+12.34 PM |
+
the long time |
+12.34.56 PM |
+
the English time |
+12:34:56 PM |
+
The format of the time is dependent on the current locale. This is important if you want to write scripts that work anywhere without modification. You cannot assume that the time function will always return a time in the same format.
To prevent issues caused by differing local time formats, use the seconds or the dateItems to store and perform calculations with dates and times.
the trunc of factor
trunc ( expression )
Factor and expression yield integers, numbers, or complexes.
put trunc(steve) into bill
The trunc function returns the given value rounded towards zero. If the given value is an integer, the given value is returned. Otherwise, the given value is rounded to the integer with the next lowest absolute value and the same sign. In other words, the trunc function returns the integer part of the given value, discarding the fractional part, regardless of sign.
The following table illustrates the behavior of the trunc function:
| argument | +result | +
|---|---|
| 2 | +2 | +
| 1.75 | +1 | +
| 1.5 | +1 | +
| 1.25 | +1 | +
| 1 | +1 | +
| 0.75 | +0 | +
| 0.5 | +0 | +
| 0.25 | +0 | +
| 0 | +0 | +
| -0.25 | +0 | +
| -0.5 | +0 | +
| -0.75 | +0 | +
| -1 | +-1 | +
| -1.25 | +-1 | +
| -1.5 | +-1 | +
| -1.75 | +-1 | +
| -2 | +-2 | +
If the given value is a complex, the real and imaginary parts of the complex number are each rounded individually.
The following table shows the correspondences among the various roundingMethods, rounding functions, and division operators:
+rounding parameter |
+function | +operator | +java.math.RoundingMode |
+
|---|---|---|---|
to ceiling |
+ceil |
++ | CEILING |
+
to floor |
+floor |
+div / mod |
+FLOOR |
+
up / to infinity |
+aug |
++ | UP |
+
down / to zero |
+trunc |
+quot / rem |
+DOWN |
+
to nearest |
+round |
++ | HALF_UP |
+
to even |
+rint |
++ | HALF_EVEN |
+
The following table illustrates the behavior of the rounding functions side-by-side:
+| argument | +ceil |
+floor |
+aug |
+trunc |
+round |
+rint |
+
|---|---|---|---|---|---|---|
| 2 | +2 | +2 | +2 | +2 | +2 | +2 | +
| 1.75 | +2 | +1 | +2 | +1 | +2 | +2 | +
| 1.5 | +2 | +1 | +2 | +1 | +2 | +2 | +
| 1.25 | +2 | +1 | +2 | +1 | +1 | +1 | +
| 1 | +1 | +1 | +1 | +1 | +1 | +1 | +
| 0.75 | +1 | +0 | +1 | +0 | +1 | +1 | +
| 0.5 | +1 | +0 | +1 | +0 | +1 | +0 | +
| 0.25 | +1 | +0 | +1 | +0 | +0 | +0 | +
| 0 | +0 | +0 | +0 | +0 | +0 | +0 | +
| -0.25 | +0 | +-1 | +-1 | +0 | +0 | +0 | +
| -0.5 | +0 | +-1 | +-1 | +0 | +-1 | +0 | +
| -0.75 | +0 | +-1 | +-1 | +0 | +-1 | +-1 | +
| -1 | +-1 | +-1 | +-1 | +-1 | +-1 | +-1 | +
| -1.25 | +-1 | +-2 | +-2 | +-1 | +-1 | +-1 | +
| -1.5 | +-1 | +-2 | +-2 | +-1 | +-2 | +-2 | +
| -1.75 | +-1 | +-2 | +-2 | +-1 | +-2 | +-2 | +
| -2 | +-2 | +-2 | +-2 | +-2 | +-2 | +-2 | +
the value of factor
value ( expression )
Factor and expression yield any string.
+put the value of myFormula into myResult ++
The value function evaluates the string passed to it as an XION expression. The string is evaluated as if it were inserted inside parentheses in place of the value function call.
If the string does not form a single valid expression, the string itself is returned.
+ The following example demonstrates the value function:
+on demoValue + put "3 + 4" into expression + put expression -- yields "3 + 4" + put the value of expression -- yields 7 +end demoValue ++
To evaluate arbitrary XION expressions with this function, OpenXION's security settings must allow the DO_AND_VALUE security key. If the required security key is denied, a script error will be triggered.
the version of factor
version ( expression )
Factor and expression yield some object or the name of some component that has a version number.
+ The version function returns the version number of an object or component.
To use this function, OpenXION's security settings must allow the SYSTEM_INFO security key. If the required security key is denied, a script error will be triggered.
the voices
voices ()
+put the voices ++
The voices function returns a lineEnding-delimited list of voices currently available for use with the speak command.