# General Functions

This section describes basic BullScript functions used to make decisions, refer to other data bars, call other scripts and input data.

## AllFalse

**Usage**

ALLFALSE(EXPR, N)

- expr
- A yes/no (boolean) expression that is evaluated every bar.
- n
- The number of bars over which
*expr*is evaluated.

**Description**

If *expr* has evaluated to ‘false’ *every* bar over the last *n* bars (including the current bar) then this function returns ‘true’. Otherwise, if *expr* has evaluated to ‘true’ on one or more of the last *n* bars then this function ‘false’.

That is, the *allfalse* function determines whether *expr* has returned all ‘false’ results.

This can be a useful function for determining if a signal or condition has failed to trigger recently.

**Example 1**

Consider a security that consistently closed higher every day for the last ten days:

- allfalse(C<=prev(C),10) returns true, because the close was never lower, or equal.
- alltrue(C>prev(C),10) is equivalent, and returns true, because the close was higher every day.

Note that the inverse of > is actually <= because if A is not greater than B, then it could either be less than, or equal to B. Similarly, the inverse of < is >=.

**Example 2**

Consider a security that has not cross above its 10 day moving average in the last week: allfalse(cross(C,ma(C,10,S),10) returns true, because the MA was not crossed.

If it had been crossed then the function would have returned false.

**Remarks**

The functions allfalse, alltrue, anytrue, and anyfalse are logically related. The *true* functions test to see if *expr* has returned ‘true’, and the *false* functions test if it has returned ‘false’. The *all* functions test to see if this criteria is met on every bar over the last *n**any bars, and the *functions only require the criteria to be met on at least one bar.

There are some interesting logical relationships. Assuming the same *expr* and *n*

- alltrue(expr,n) = not anyfalse(expr,n) That is, if one is true, the other is always false, and vice versa.
- allfalse(expr,n) = not anytrue(expr,n) That is, if one is true, the other is always false, and vice versa.
- alltrue(expr,n) = allfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- anytrue(expr,n) = anyfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- if alltrue(expr,n) returns true, then anytrue(expr,n) must also return true, but not vice versa.
- if allfalse(expr,n) returns true, then anyfalse(expr,n) must also return true, but not vice versa.
- if anytrue(expr,n) returns false, then alltrue(expr,n) must also return false, but not vice versa.
- if anyfalse(expr,n) returns false, then allfalse(expr,n) must also return false, but not vice versa.

Because people tend to think in terms of what *is* observed rather that what *isn’t* observed, you may find the alltrue and anytrue functions more intuitive to use than the allfalse and anyfalse functions.

**See Also**

AllTrue | AnyFalse| AnyTrue | Boolean data type | False| True

## AllTrue

**Usage**

ALLTRUE(EXPR, N)

- expr
- A yes/no (boolean) expression that is evaluated every bar.
- n
- The number of bars over which
*expr*is evaluated.

**Description**

If *expr* has evaluated to ‘true’ *every* bar over the last *n* bars (including the current bar) then this function returns ‘true’. Otherwise, if *expr* has evaluated to ‘false’ on one or more of the last *n* bars then this function ‘false’.

That is, the *alltrue* function determines whether *expr* has returned all ‘true’ results.

This can be a useful function for determining if some trend has been consistently maintained.

**Example 1**

Consider a security that consistently closed higher every day for the last ten days:

- alltrue(C>prev(C),10) returns true, because the close was higher every day.
- allfalse(C<=prev(C),10) is equivalent, and returns true, because the close was never lower, or equal.

Note that the inverse of > is actually <= because if A is not greater than B, then it could either be less than, or equal to B. Similarly, the inverse of < is >=.

**Example 2**

Consider a security that consistently alternates between closing at $0.40 and $0.41 every day.

allfalse(C<=prev(C),10) returns false, because the close was occasionally less than the previous day

**Remarks**

The functions allfalse, alltrue, anytrue, and anyfalse are logically related. The *true* functions test to see if *expr* has returned ‘true’, and the *false* functions test if it has returned ‘false’. The *all* functions test to see if this criteria is met on every bar over the last *n**any bars, and the *functions only require the criteria to be met on at least one bar.

There are some interesting logical relationships. Assuming the same *expr* and *n*

- alltrue(expr,n) = not anyfalse(expr,n) That is, if one is true, the other is always false, and vice versa.
- allfalse(expr,n) = not anytrue(expr,n) That is, if one is true, the other is always false, and vice versa.
- alltrue(expr,n) = allfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- anytrue(expr,n) = anyfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- if alltrue(expr,n) returns true, then anytrue(expr,n) must also return true, but not vice versa.
- if allfalse(expr,n) returns true, then anyfalse(expr,n) must also return true, but not vice versa.
- if anytrue(expr,n) returns false, then alltrue(expr,n) must also return false, but not vice versa.
- if anyfalse(expr,n) returns false, then allfalse(expr,n) must also return false, but not vice versa.

Because people tend to think in terms of what *is* observed rather that what *isn’t* observed, you may find the alltrue and anytrue functions more intuitive to use than the allfalse and anyfalse functions.

**See Also**

AllFalse | AnyFalse | AnyTrue | Boolean data type | False | True

## AnyFalse

**Usage**

ANYFALSE(EXPR, N)

- expr
- A yes/no (boolean) expression that is evaluated every bar.
- n
- The number of bars over which
*expr*is evaluated.

**Description**

If *expr* has evaluated to ‘false’ *at least once* over the last *n* bars (including the current bar) then this function returns ‘true’. Otherwise, if *expr* has evaluated to ‘true’ on every single bar over the last *n* bars then this function ‘false’.

That is, the *anyfalse* function determines whether *expr* has returned any ‘false’ results.

This can be a useful function for determining if there has been a failure in some trend.

**Example**

Consider a security that closed higher every day, except on one day over the last week:

anyfalse(C>prev(C),5) returns true, because of that one day.

But if it had closed higher every day, then the same function would have returned false.

**Remarks**

The functions allfalse, allfalse, anytrue, and anyfalse are logically related. The *true* functions test to see if *expr* has returned ‘true’, and the *false* functions test if it has returned ‘false’. The *all* functions test to see if this criteria is met on every bar over the last *n**any bars, and the *functions only require the criteria to be met on at least one bar.

There are some interesting logical relationships. Assuming the same *expr* and *n*

- alltrue(expr,n) = not anyfalse(expr,n) That is, if one is true, the other is always false, and vice versa.
- allfalse(expr,n) = not anytrue(expr,n) That is, if one is true, the other is always false, and vice versa.
- alltrue(expr,n) = allfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- anytrue(expr,n) = anyfalse(not expr,n) That is, switching between the two functions is equivalent to reversing the criteria.
- if alltrue(expr,n) returns true, then anytrue(expr,n) must also return true, but not vice versa.
- if allfalse(expr,n) returns true, then anyfalse(expr,n) must also return true, but not vice versa.
- if anytrue(expr,n) returns false, then alltrue(expr,n) must also return false, but not vice versa.
- if anyfalse(expr,n) returns false, then allfalse(expr,n) must also return false, but not vice versa.

Because people tend to think in terms of what *is* observed rather that what *isn’t* observed, you may find the alltrue and anytrue functions more intuitive to use than the allfalse and anyfalse functions.

**See Also**

AllFalse | AllTrue | AnyTrue | Boolean data type | False | True

## AnyTrue

**Usage**

ANYTRUE(EXPR, N) ALERT(EXPR, N)

- expr
- A yes/no (boolean) expression that is evaluated every bar.
- n
- The number of bars over which
*expr*is evaluated.

**Description**

If *expr* has evaluated to ‘true’ *at least once* over the last *n* bars (including the current bar) then this function returns ‘true’. Otherwise, if *expr* has evaluated to ‘false’ on every single bar over the last *n* bars then this function ‘false’.

That is, the *anytrue* function determines whether *expr* has returned any ‘true’ results.

This can be a useful function for determining if some signal has been triggered recently.

**Example 1**

Consider a security that closed higher some days over the last week:

anytrue(C>prev(C),5) returns true, because the price had increased some days.

But if it had not closed higher on any single day, then the same function would have returned false.

**Example 2**

Consider a security that crossed above its 10 day moving average in the last week:

anytrue(cross(C,ma(C,10,S),5) returns true, because of the cross.

But if it had not not crossed, then the same function would have returned false.

**Remarks**

The functions allfalse, allfalse, anytrue, and anyfalse are logically related. The *true* functions test to see if *expr* has returned ‘true’, and the *false* functions test if it has returned ‘false’. The *all* functions test to see if this criteria is met on every bar over the last *n**any bars, and the *functions only require the criteria to be met on at least one bar.

There are some interesting logical relationships. Assuming the same *expr* and *n*

- if alltrue(expr,n) returns true, then anytrue(expr,n) must also return true, but not vice versa.
- if allfalse(expr,n) returns true, then anyfalse(expr,n) must also return true, but not vice versa.
- if anytrue(expr,n) returns false, then alltrue(expr,n) must also return false, but not vice versa.
- if anyfalse(expr,n) returns false, then allfalse(expr,n) must also return false, but not vice versa.

*is* observed rather that what *isn’t* observed, you may find the alltrue and anytrue functions more intuitive to use than the allfalse and anyfalse functions.

**See Also**

AllFalse | AllTrue | AnyFalse | Boolean data type | False | True

## Bar Number

**Usage**

barnumber

**Description**

Counting left to right, the number of the bar currently being calculated by BullScript. The left-most bar is bar number 1. The bar number of the right-most bar is the same as the number of bars loaded.

Note that this function is related to the amount of data loaded, not the data currently visible on the screen. That is, scroll to the far left of the chart to find bar number 1. When used in BullScan, this function depends on the amount of data loaded, as specified on the Advanced tab.

**Example**

The code below will return 1 for the 10 left-most bars of the chart, then return 5 thereafter.

if(barnumber<=10, 1, 5);

## BarsSince

**Usage**

BARSSINCE(EXPR)

- n
- A boolean expression that evaluates to true or false.

**Description**

Returns the number of bars since *expr* was true. This can be used to determine the number of bars since some event occurred.

**Example**

barssince( cross(C, ma(C,10,S)) ) returns the number of bars since the close crossed above its 10 day moving average.

## Expression

**Usage**

EXPRESSION([MESSAGE[,DEFAULT]])

- message
- A description for the expression parameter.
- default
- One of Open, High, Low, Close, Volume, Value, Trades.

**Description**

Allows the current formula to take an expression as a parameter, and returns that expression. If the formula is being run as an indicator, *message* will be displayed in a dialog, and selection of the expression to use will be allowed. *Default* sets what the default expression in the dropdown will be.

**Example**

a := expression(“Enter the expression to run the formula over”);

b := expression(“Select field to use as stop level”, Low);

**See Also**

## ExtFml

**Usage**

EXTFML(name[,args,...])

- name
- The DLL and function name, separated by a dot.
- args
- Zero or more arguments specific to the external function.

**Description**

The ExtFml allows BullScript to call functions in 3rd party plug-ins, such as the TradeSim DLL.

External function DLL must be placed in a “External Function DLLs” folder, underneath the BullCharts program folder. To call a function, the name parameter contains the name of the DLL (without the .dll extension), followed by a dot, then the function to be called.

**Remarks**

The order of calculations is slightly different when external functions are called. Normally BullScript performs running through a date series, however when an external function is called, the entire data series is first calculated for each argument, then the external function is calculated for the entire data series. This means that the previous function generally cannot be used with external functions.

BullScript normally returns an undefined result if a calculation (such as a divide by zero) cannot be performed. External functions may behave in other ways. If an external function reports an error, it will be displayed to the screen.

**Example**

ExtFml(“TradeSim.Rand”); calls the Rand function in TradeSim.DLL, which will return a pseudo-random number. You must have TradeSim installed for this example to work.

**See Also**

For more information, refer to manual for the 3rd party plug-in.

## False

**Usage**

FALSE

**Description**

Use false as a parameter to a function that requires a boolean expression, when you want that parameter to always use the boolean value false.

**Example**

if (false, open, close) will always return the close price. This can be useful when testing and debugging your scripts as you can force a part of your program to behave in a particular way.

**See Also**

AllFalse | AllTrue | AnyFalse | AnyTrue | Boolean data type | True

## FirstValue

**Usage**

FIRSTVALUE(EXPR)

- expr
- The data to consider. eg Close.

**Description**

Returns the first *defined* value that *expr* takes. That is the left-most value on the chart, or the earliest value in history.

**Example**

100*C/firstvalue(C) calculates a simple relative performance indicator by comparing the current closing price to the first closing price on the chart.

## Formula

**Usage**

FORMULA(NAME[,ARG1,ARGn])

- name
- The name or alias of the formula to call
- args
- Values for any expressions or inputs to pass to the formula.

**Description**

Evaluates the formula given in *name*, with the given parameters passed to the formula and returns the result. This is useful for calling custom indicators when there is a space in the name.

**Example** **1**

formula(“My Indicator”,8) calls the “My Indicator” formula, and sets the first input to 8.

**Example** **2**

formula(“macd”,12,26,9) is equivalent to macd(12,26,9).

**See Also**

## Future

**Usage**

FUTURE(EXPR,N)

- expr
- An expression that will be calculated
*n*bars ahead from now. - n
- The number of bars to look ahead.

**Description**

Returns the value of* expr*, n bars from now. Unfortunately, undefined if there is insufficient data.

The future function is equivalent to the MetaStock ref function. future(-x) is equivalent to hist(x). For easier reading it is recommended that the hist function be used when negative values would traditionally be used for ref. That is, use hist(C,1) to get yesterdays closing price, rather than future(C,-1) or ref(C,-1).

Using the future function has the effect of shifting expr to the left on the chart by n bars.

**Example**

future(C,1) returns the close for the following bar, the bar to the right. It also returns undefined on the last bar of the charts, as the future is unknown.

**See Also**

Hist, Future and Previous | Hist

## Hist

**Usage**

HIST(EXPR,N)

- expr
- An expression that will be calculated
*n*bars previous. - n
- The number of bars to look ahead.

**Description**

Returns the value of* expr*, as at n bars ago. Equivalent to the MetaStock Ref function, except the value of n is negated in MetaStock.

The hist function requires n days of historical data to calculate.

ref(x,-n) is equivalent to hist(x,n) for any x and n.

**Example**

C-hist(C,14) returns the change over the last 14 bars.

**See Also**

Hist, Future and Previous | Future | Previous

## If

**Usage**

IF(TEST,EXPR1,EXPR2)

- text
- A boolean expression that returns either ‘true’ or ‘false’.
- expr1
- Will be evaluated and returned if
*test*returns true. - expr2
- Will be evaluated and returned if
*test*returns false.

**Description**

Returns *expr1* if test is true, otherwise returns *expr2*. The if function can also be used test for multiple cases by embedding consecutive ifs. Refer to the examples.

**Example**

if(OPEN > CLOSE, OPEN, CLOSE) returns the greater of open and close. Note: In practice the max function would be used for this calculation.

if(CLOSE => 5 AND CLOSE <= 10, 500, 0) returns 500 if the closing price is between 5 and 10 inclusive, otherwise it returns 0.

if(Volume >= 1000000 OR Trades >= 5000, 1, 0) returns 1 if either Volume is at least one million, or trades if greater than 5000, otherwise 0 is returned. Note that if both volume and trades are greater than their respective levels then 1 is still returned. This is called an inclusive OR.

if(C > hist(H,1), “Above”, if(C < hist(L,1), “Below”, “Within”))

This example returns the text Above, Below or Within to indicate how todays close relates to yesterdays range. Note that a second if function has been put inside the first one. It is said to be nested. If the close is not above, then it moves on to test for below and within.

if(condition1, result1,

if(condition2, result2,

if(condition3, result3,

if(condition4, result4,

result5))))

This example shows an convenient way to lay out nested if functions (remember that BullScript ignores line-ends).* condition1* is checked first. It could be Close>Open, for example, or anything else that returns true/false. If *condition1* returns true, then* result1*is immediately returned. Otherwise, it moves on to* condition2*. If that is true, then *result2* is returned, and so on. If none of the conditions are met then the value *result5* is returned. Note that the number of brackets on the last line matches the number of if statements.

In the above two examples, if has always been nested in the third parameter. It it also possible to nest it in the second or first, but these are generally not recommended as it will make the script more confusing to understand.

## Input

**Usage**

INPUT(MESSAGE[,DEFAULT,MINIMUM,MAXIMUM])

- message
- A description for the input parameter.
- default
- The default value for this parameter.
- minimum
- The minimum allowable value for this parameter.
- maximum
- The maximum allowable value for this parameter.

**Description**

The input function causes a message to be shown in the indicator window, and a textbox for a number to be entered. The input then returns the entered number to BullScript.

*Default* is the value that will be used if none is given, and minimum and maximum are the *minimum* and *maximum* allowed values.

In addition to allowing the indicator to being customised from the indicator window, other custom indicators can also specify the value to use for this input by passing a parameter when calling this script.

It is recommended any input be stored in a variable to allow it to be used in several places, and to keep the script tidy.

**Example**

n := input(“Enter the length of the moving average”,14,7,52);

ma(C,n,SIMPLE);

## InputMA

**Usage**

INPUTMA(MESSAGE[,DEFAULT])

- message
- A description for the input parameter.
- default
- The default value for this parameter. See the Ma function for a list of allowable values.

**Description**

The inputma method causes a dropdown to be shown in the indicator window that lists various methods of calculating moving averages (such as simple, exponential, etc). The inputma returns the selected method as a special data type, which can then be stored in a variable and/or used in a later call to the ma function.

In addition to allowing the indicator to being customised from the indicator window, other custom indicators can also specify the value to use for this input by passing a parameter when calling this script.

**Example**

n := input(“Enter the moving average length”,14,7,52);

method := inputma(“Enter the moving average method”,SIMPLE);

ma(C,n,method);

**See Also**

Input | MA enum data type | Ma function

## InputROC

**Usage**

INPUTROC(MESSAGE[,DEFAULT])

- message
- A description for the input parameter.
- default
- The default value for this parameter. May be either Percent, or Points.

**Description**

The inputroc method causes a dropdown to be shown in the indicator window that lists the different methods of calculating rate of change. The inputroc returns the selected method as a special data type, which can then be stored in a variable and/or used in a later call to the roc function.

In addition to allowing the indicator to being customised from the indicator window, other custom indicators can also specify the value to use for this input by passing a parameter when calling this script.

**Example**

n := input(“Enter the ROC length”,14,7,52);

method := inputroc(“Enter the ROC method”,PERCENT);

roc(C,n,method);

**See Also**

Input | ROC enum data type | ROC function

## InputSymbol

**Usage**

InputSymbol(MESSAGE[,DEFAULT])

- message
- A description for the input parameter.
- default
- The default symbol (security code) to use.

**Description**

Allows the current formula to take a symbol (security code) as a parameter. A textbox will appear in the indicator window where the symbol can be entered. This can then be passed to the LoadSymbol function to load data from that security.

The inputsymbol and inputtext functions behave in a similar manner. However, future versions of BullCharts may extend the inputsymbol to allow other datasources (such as Metastock data) to be loaded. Therefore it is recommended that inputsymbol be used where the input is a security code, and inputtext is used for any other textual parameters.

**Example**

text := inputtext(“Enter message”,”Demo”);

[linestyle=text; target=price; textalign=top,right]

if(barnumber=lastvalue(barnumber), text, undefined);

C;

**See Also**

InputText | Input | LoadSymbol

## InputText

**Usage**

InputText(MESSAGE[,DEFAULT])

- message
- A description for the input parameter.
- default
- The default value for this parameter.

**Description**

Allows the current formula to take some text (also called a string) as a parameter, and returns that text. If the formula is being run as an indicator, *message* will be displayed in a dialog window. *Default* is the value that will be used if none other is given.

Note: If you need to input a symbol (security code) to pass to the loadsymbol function, or similar, then use the InputSymbol function instead.

**Example**

text := inputtext(“Enter message”,”Demo”);

[linestyle=text; target=price; textalign=top,right]

if(barnumber=lastvalue(barnumber), text, undefined);

C;

**See Also**

## IsDefined

**Usage**

ISDEFINED(EXPR)

- expr
- The data to be checked.

**Description**

Checks to see if *expr* has valid data. If *expr* is a normal number or string, IsDefined returns true. But if it is the special undefined value then it returns false.

This function always returns the opposite result to IsUndefined.

**Example**

tmp := Volume / (High – Low);

if ( isdefined(tmp), tmp, 0 );

The tmp variable above might be undefined if high and low are the same value, because that would mean a division by zero, which is not possible. IsDefined is used to check if the result is OK, and if its not then zero is returned.

**See Also**

## IsUndefined

**Usage**

ISUNDEFINED(EXPR)

- expr
- The data to be checked.

**Description**

Checks to see if *expr* is the special undefined value. This function always returns the opposite result to IsDefined.

**Example**

tmp := Volume / (High – Low);

if ( isundefined(tmp), 0, tmp );

The tmp variable above might be undefined if high and low are the same value, because that would mean a division by zero, which is not possible. IsUndefined is used to check if the result is undefined. If tmp is undefined then zero is returned.

**See Also**

## Last Value

**Usage**

LASTVALUE(EXPR)

- expr
- The data to be evaluated on the last bar.

**Description**

Returns the value of *expr* as it would be calculated on the last (right-most) bar of the chart.

**Example**

lastvalue(barnumber) returns the total number of data points in the chart.

lastvalue(C) returns the close for the last bar on the chart.

## LoadSymbol

**Usage**

LoadSymbol(SYMBOL,EXPRESSION)

- symbol
- The symbol or code of the security to load.
- expression
- The calculation that should be made and returned for that security.

**Description**

Causes BullScript to stop processing the security it is currently working on, and load a different security instead. This security switch only occurs within the loadsymbol function. That is *expression*is calculated as if *symbol* were the current symbol, and the result is returned. BullScript reverts back to the original security after the loadsymbol function.

When used in conjunction with Security.SectorIndex, LoadSymbol can be used to create powerful BullScans.

Important Notes:

- The loadsymbol function is not currently supported on live or intraday charts. It will only load daily, weekly and longer data.
- The loadsymbol expression may not refer to previously defined variables. The result of doing this is undefined.
- If the security being processed has more or less data than the security loaded with loadsymbol then the loadsymbol function will pad extra empty bars, or remove bars from the loaded data so that it aligns with the data of the original security. This can affect the result of various functions. It is recommended that loadsymbol only be on securities with complete data sets.

**Example 1**

{ A simple RSC calculation }

symb := inputsymbol(“Security”,”XAO”);

Close / LoadSymbol(symb, Close);

**Example 2**

{ A simple weighted index }

{ this may become slow if you use too many securities }

LoadSymbol(“NAB”,C) * 0.1 +

LoadSymbol(“ANZ”,C) * 0.3 +

LoadSymbol(“CBA”,C) * 0.2 +

LoadSymbol(“WBC”,C) * 0.4;

**Example 3**

{ Simple RSC of a security against its sector index }

C / LoadSymbol(Security.SectorIndex, C);

**See Also**

InputSymbol | Security.SectorIndex

## Param

**Usage**

PARAM([MESSAGE,DEFAULT,MINIMUM,MAXIMUM])

- message
- A description for the input parameter.
- default
- The default value for this parameter.
- minimum
- The minimum allowable value for this parameter.
- maximum
- The maximum allowable value for this parameter.

**Description**

Allows the current formula to take a dynamic number as a parameter, and returns that number. If the formula is being run as an indicator, *message* will be displayed in a dialog, and selection of the expression to use will be allowed. *Default* is the value that will be used if none is given, and *minimum* and *maximum* are the minimum and maximum allowed values.

Param differs from input in that param accepts a number that may change, for example a Close price. Input accepts only numbers that do not change, and thus are useful for giving to functions that require an unchanging number.

**Example**

CLOSE*param(“Enter the amount to multiply close by”)

**See Also**

## Previous

**Usage**

PREVIOUS([SEED[,N]]) PREV([SEED[,N]])

- seed
- The initial value if previous bars are available.
- n
- The number of bars to look back.

**Description**

Calculates the value of the current formula as it was *n* bars ago, or returns *seed* if there are less than *n* bars available. If *n* is not given, 1 is used. If *seed *is not given, 0 is used. An expression (eg Close) may be used for *seed*.

Previous is often used without specifying either the seed or n to simply refer to the previous result.

Note that most indicators that use the previous function are sensitive to the amount of data that has been loaded into BullScript (as the calculation for each day relies on the previous). Take particular care when developing scans that directly or indirectly rely on previous that there is enough data loaded for an accurate result.

Be aware that because some values such as 1/3 cannot be truly represented by the data format BullScript uses internally, rounding error can accumulate in calculations, despite the high precision used in storing numbers.

**Example**

0.20*close + 0.80*previous(close) is a manual calculation of an exponential moving average. It works by adding 20% of todays close to 80% of what the exponential moving average was yesterday. Note that the (close) after previous ensures that the first bar of the chart will return a result equal to that first close.

**See Also**

Hist, Future and Previous | Hist

## Requires

**Usage**

REQUIRES(EXPR)

- expr
- The expression being examined.

**Description**

Returns the number of historical data points (in addition to the current data point) required to calculate *expr*.

**Example**

requires(ma(C,10,S)) returns 9 (as 10 bars are required, counting the current bar) requires(hist(C,7)) returns 7 (as it returns the result 7 bars prior to the current.) requires(C) returns 0 (as no additional data is required) requires(hist(C,3)+hist(C,5)) returns 5. requires(ma(ma(C,5),6)) returns 9 (as this is (5-1) + (6-1) )

## Trigonometric Functions

**Usage**

SIN(ANGLE) COS(ANGLE) TAN(ANGLE) ASIN(RATIO) ACOS(RATIO) ATAN(RATIO) HSIN(ANGLE)orSINH(ANGLE) HCOS(ANGLE)orCOSH(ANGLE) HTAN(ANGLE)orTANH(ANGLE)

- angle
- An angle, specified in degrees.
- ratio
- A number for which the inverse angle will be calculated.

**Description**

The standard trigonometric functions, which relate the ratio of sides of a triangle to angles of a triangle. Angles are always expressed in degrees.

The trigonometric functions calculate the relationship between the relative lengths of the sides of a triangle and the angles within that triangle. Refer to a mathematics textbook for further details.

NOTE: To convert radians to degrees, use: rad*180/PI. For example, atan(1)*180/Pi.

**Example**

cos(30) returns 0.866

## True

**Usage**

TRUE

**Description**

Use true as a parameter to a function that requires a boolean expression, when you want that parameter to always use the boolean value true.

**Example**

if (true, open, close) will always return the open price. This can be useful when testing and debugging your scripts as you can force a part of your program to behave in a particular way.

**See Also**

AllFalse | AllTrue | AnyFalse | AnyTrue | Boolean data type | False

## Undefined

**Usage**

UNDEFINED

**Description**

Undefined is a special data value used when a result cannot be calculated, or that a result is not meaningful in the current context.

The two most common reasons for an undefined result are that either there is insufficient data to perform the requested calculation (for example, a 10-day moving average will return undefined for the first 9 days), or because some value has been divided by zero (which is quite common when performing calculations involving the trading range, or volume).

The undefined keyword can be used to indicate that you don’t want a result to be defined for some reason or another. It is used to force BullCharts to not draw a line on the chart at a certain point.

**Example**

if (count<=100, undefined, ma(C,10) will draw a 10 day moving average – but the line will not be drawn for the first 100 bars of the chart.

The Darvas boxes, for example, return undefined between boxes to inform BullCharts not to draw anything in this area.

**See Also**

## ValueWhen

**Usage**

VALUEWHEN(N,EXPR1,EXPR2)

- n
- The number of times counted back. Eg: Use 1 to find the most recent time expr1 was true.
- expr1
- A boolean expression that returns true/false. This is the condition that is checked.
- expr2
- The result to be returned.

**Description**

Calculates the value of *expr2*, as at the *n*th most recent time that *expr1* was true.

**Example**

valuewhen(4, cross(C,ma(C,14)), typical) returns the typical price as at the 4^{th} most recent time that the close price crossed over its 14-period simple moving average.

## Wait

**Usage**

WAIT(EXPR,N)

**Description**

Waits *n* additional days before returning the result of *expr*. Useful when trying to exactly copy an indicator that does not start immediately. Some of Wilder’s indicators behave this way.

Wait can also be passed a negative value, indicating that results should be returned early. This is useful where BullScript is not able to calculate the data requirements correctly. (BullScript calculates data requirements statically, and therefore has difficulty when two paths are being selected based on an if statement).

**Example**

wait(sum(CLOSE,10),2) will return the same result as sum(CLOSE,10), except that the former starts on the 12th bar instead of the 10th.

if(barnumber < 20, ma(C,5), ma(C,20)) will not start until the 20th day because of the rules BullScript uses when calculating data requirements. But by putting it in wait(…,-15) it will start on the 5th day as expected.