# Internal (built-in) functions

The function performs a task and then returns control to the calling task. When it returns control, it also returns a value to the calling code. There are many internal (built-in) functions that are included in the software, such as the string and math functions. Using functions can simplify the steps of a macro. For example, the macro is required to put a formatted date string into the current window, it needs two steps as the following:

1. Format datetime "12/1/2013 06:00", and populate variable "v_datestr" with the result.
2. Put text "%v_datestr%"

By using function "format_date", it just needs one step.

1. Put text "%=format_date("12/1/2013 06:00")%"

Many categories of built-in functions are supported. These functions let you perform mathematical calculations, string manipulation, date calculations, and other kinds of data transformations directly in an expression.

#### Using function

1. The functions can only be used in the expression.

Put text "20 + RAND( 0, 100 )" //Incorrect

Put text "%=20 + RAND( 0, 100 )% //Correct

2. The functions' name in an expression is not case-senseitive.

The following calls are both correct.

mid( "This is a sample", 5 ) //return the string "is a sample"

MID( "This is a sample", 5 ) //return the string "is a sample"

3. The function can be used in the parameter expression.

The following calls are both correct.

CHOOSE( IF( 20 > 1, 1, 2 ), "OK", "FAILED" ) //return the string "OK"

CHAR( CINT( 65.2343 ) ) //return the string "A"

#### Function definition (prototype)

Reading and understanding a function's prototype is important to realize what a function returns or if a function works directly on a passed in value. Each function in the manual is documented for quick reference. You should know how to read function definitions (prototypes) before using them. The syntax for function prototype is as follows:

Returned datatype functionname( [parameters list] )

Function definitions tell us what type of value will be returned, and the function needs how many parameters. For example, the definition for the function mid is the below:

string mid( string, num_pos, [number] )

Explanation of the function definition

PartDescription
StringThe data type this function returns, which is a string.
midThe function name
( string, pos_num, [number] )The function requires a string as the first parameter, the second parameter should be a number, and the third parameter is an optional parameter.

#### Function parameters (arguments)

When you call a function, you need pass along some value to it, these values are called parameters or arguments. These parameters will be used inside the function. Multiple parameters should be separated by commas (,).

mid( "This is a sample", 5, 5 )

Optional parameters The definition of a function can specify that its parameters are required or that they are optional. Any call must provide arguments for all required parameters, but can omit arguments for optional parameters. All optional parameters are seen in [ brackets ], see the definition of the function mid as the example as the follow:

string mid( string, position_number, [length] )

The following calls to mid are both correct:

mid( "This is a sample", 4, 4 ) //return "is a"

mid( "This is a sample", 4 ) //return "is a sample"

Variable-length parameter lists Sometimes the number of input arguments is not known when the function is defined. In the definition of the function, If three dots ... appears at the end of a function parameter list it indicates that the function takes a variable number of input arguments. Let's look the definition about max.

Number max( number1, number2, [number3 ... ] )

So that, you can use the function max as the following:

max( 3, 2 ) //return 3

max( 3, 2, 1, 6 ) //return 6