Primitives

Primitive functions are called similarly to regular functions, but they are imple- mented outside of the language. Some primitives support multiple types for certain arguments, but in general, if an argument of the wrong type is supplied, the function will return null.

Call()

Call( <function_name string>, <arg_list list> )

Return value

Same as that of the function that is called.

Comments

Calls a function whose name matches the function_name parameter. All scope rules apply normally. Spaces in the function_name parameter are interpreted as the ‘_’ (underscore) character since function names cannot contain spaces.

Example

Call("Format", ["the number is %d", 10]);

is equivalent to:

Format("the number is %d", 10);

Format()

Format (<format string>, <value string or integer>)

Return value

None.

Comments

Format is used to control the way that arguments will print out. The format string may contain conversion specifications that affect the way in which the arguments in the value string are returned. Format conversion characters, flag characters, and field width modifiers are used to define the conversion specifications.

Example

Format("0x%02X", 20);

would yield the string 0x14.

Format can only handle one value at a time, so

Format("%d %d", 20, 30);

would not work properly. Furthermore, types that do not match what is specified in the format string will yield unpredictable results.

Format Conversion Characters

These are the format conversion characters used in CSL:

A conversion specification begins with a percent sign (%) and ends with a conver- sion character. The following optional items can be included, in order, between the % and the conversion character to further control argument formatting:

• Flag characters are used to further specify the formatting. There are five flag characters:

1. A minus sign (-) will cause an argument to be left-aligned in its field. Without the minus sign, the default position of the argument is right-aligned.

2. A plus sign will insert a plus sign (+) before a positive signed integer. This only works with the conversion characters d and i.

3. A space will insert a space before a positive signed integer. This only works with the conversion characters d and i. If both a space and a plus sign are used, the space flag will be ignored.

4. A hash mark (#) will prepend a 0 to an octal number when used with the conversion character o. If # is used with x or X, it will prepend 0x or 0X to a hexadecimal number.

5. A zero (0) will pad the field with zeros instead of with spaces.

• Field width specification is a positive integer that defines the field width, in spaces, of the converted argument. If the number of characters in the argument is smaller than the field width, then the field is padded with spaces. If the argument has more characters than the field width has spaces, then the field will expand to accommodate the argument.

GetNBits()

GetNBits (<bit_source list or raw>, <bit_offset integer>, <bit_count integer>)

Return value

None.

Comments

Reads bit_count bits from bit_source starting at bit_offset. Will return null if bit_offset + bit_count exceeds the number of bits in bit_source. If bit_count is 32 or less, the result will be returned as an integer. Otherwise, the result will be returned in a list format that is the same as the input format. GetNBits also sets up the bit data source and global bit offset used by NextNBits and PeekNBits. Note that bits are indexed starting at bit 0.

Example

raw = 'F0F0';	# 1111000011110000 binary result = GetNBits ( raw, 2, 4 );
Trace ( "result = ", result );

The output would be

result = C	# The result is given in hexadecimal. The result in binary is 1100.

In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value

0xC.

NextNBits()

NextNBits (<bit_count integer>)

Return value

None.

Comments

Reads bit_count bits from the data source specified in the last call to GetNBits, starting after the last bit that the previous call to GetNBits or NextNBits returned. If called without a previous call to GetNBits, the result is undefined. Note that bits are indexed starting at bit 0.

Example

raw = 'F0F0';# 1111000011110000 binary result1 = GetNBits ( raw, 2, 4 ); result2 = NextNBits(5);
result3 = NextNBits(2);
Trace ( "result1 = ", result1, " result2 = ", result2, " result3 = ", result3 );

This will generate this trace output:

result1 = C result2 = 7 result3 = 2

In the call to GetNBits: starting at bit 2, reads 4 bits (1100), and returns the value

0xC.

In the first call to NextNBits: starting at bit 6, reads 5 bits (00111), and returns the value 0x7.

In the second call to NextNBits: starting at bit 11(= 6+5 ), reads 2 bits (10), and returns the value 0x2.

Resolve()

Resolve( <symbol_name string> )

Return value

The value of the symbol. Returns null if the symbol is not found.

Comments

Attempts to resolve the value of a symbol. Can resolve global, constant and local symbols. Spaces in the symbol_name parameter are interpreted as the ‘_’ (underscore) character since symbol names cannot contain spaces.

Example

a = Resolve( "symbol" );

is equivalent to:

a = symbol;

Trace()

Trace( <arg1 any>, <arg2 any>, ...)

Return value

None.

Comments

The values given to this function are given to the debug console (not in release).

Example

list = ["cat", "dog", "cow"]; Trace("List = ", list, "\n");

would result in the output

List = [cat, dog, cow]