13. Functions

WLA supports functions in addition to .MACRO s. Functions are different from .MACRO s as functions always return a value.

13.1. User defined functions

Use .FUNCTION to create your own functions.

13.2. Built-in functions

The following built-in functions can be used where ever a number is expected:

abs(exp)	Returns the positive version of the argument
acos(exp)	The same as ANSI C90 acos()
asc(exp)	Uses .ASCIITABLE to map the supplied value
asin(exp)	The same as ANSI C90 asin()
atan(exp)	The same as ANSI C90 atan()
atan2(exp)	The same as ANSI C90 atan2()
bank()	Returns the current bank (*)
bank(label)	Returns the bank of the supplied label (the same as preceding :)
bankbyte()	Returns the current bank byte, bits 16-23 (*)
bankbyte(label)	Returns the bank byte, bits 16-23, of the supplied label
base()	Returns current base (*)
base(label)	Returns the base of the supplied label
blank(s)	Returns 1 (true) if s is empty or whitespace, 0 (false) otherwise
ceil(exp)	The same as ANSI C90 ceil()
clamp(value, min, max)	Clamps the value between min and max
cos(exp)	The same as ANSI C90 cos()
cosh(exp)	The same as ANSI C90 cosh()
defined(definition)	Returns 1 (true) if the supplied definition exists, 0 (false) otherwise
definedfunction(func)	Returns 1 (true) if the supplied function exists, 0 (false) otherwise
definedmacro(macro)	Returns 1 (true) if the supplied macro exists, 0 (false) otherwise
exists(path)	Returns 1 (true) if the supplied file exists, 0 (false) otherwise
floor(exp)	The same as ANSI C90 floor()
get(keyword1)	Returns value/string depending on what keyword1 is
hibyte(exp)	Returns the high byte, bits 8-15 (the same as preceding >)
hiword(exp)	Returns the high word, bits 16-31
is(keyword2)	Return 0 (false) or 1 (true), see below for “keyword2”
left(len, s)	Returns the leftmost len characters of s
lobyte(exp)	Returns the low byte, bits 0-7 (the same as preceding <)
log(exp)	The same as ANSI C90 log()
log10(exp)	The same as ANSI C90 log10()
loword(exp)	Returns the low word, bits 0-15
match(a, b)	Returns 1 (true) if a and b have matching token types
max(exp1, exp2)	Returns the bigger value
mid(ind, len, s)	Returns len characters of s, starting at index ind
min(exp1, exp2)	Returns the smaller value
org()	Returns the current address since the start of the slot (*)
orga()	Returns the current 16-bit memory address (*)
pow(base, power)	The same as ANSI C90 pow()
random(min, max)	Returns a pseudo random integer like .DBRND [min, max]
right(len, s)	Returns the rightmost len characters of s
round(exp)	The same as ANSI C99 round()
sign(exp)	Return 0 if the supplied value is 0, -1 if negative and 1 if positive
sin(exp)	The same as ANSI C90 sin()
sinh(exp)	The same as ANSI C90 sinh()
slot()	Returns the current slot (*)
sqrt(exp)	Returns the square root of the supplied value
substring(s, ind, len)	Returns a substring of s, starting at index ind, consisting of len characters
tan(exp)	The same as ANSI C90 tan()
tanh(exp)	The same as ANSI C90 tanh()
tcount(s)	Returns the number of tokens in s
xmatch(a, b)	Returns 1 (true) if a and b have the same tokens

Note! Use bankbyte() with WLA-65816 as on that platform the bank (+ base) bits are 16-23. On other platforms bank() works better.

Note! Functions marked with (*) are evaluated in the assembler, so if the linker relocates the code then these functions return possibly wrong values.

Note! match(), xmatch() and tcount() operate on WLA token text supplied as strings or expanded macro arguments. match() compares token types, while xmatch() compares the token text as well.

13.3. Examples of functions

Here’s an example about how these functions can be used

.IF defined(USE_DEBUG) && defined(DEBUG_SHOW) && min(VALUE_A, VALUE_B) > 10

LDX #lobyte(playMusic)          ; instead of (playMusic & $FF)
LDA #bank(playMusic)            ; instead of :playMusic
.DB random(0, 10)               ; defines a byte with value 0-10
.DL (base() << 16) | orga()     ; defines the current 24-bit address

.IF blank("")
.ENDIF

.IF match("lda #1", "foo #2")
.ENDIF

.IF xmatch("lda #1", "lda #1")
.ENDIF

.DB tcount("lda #1,foo")
.DB left(4, "WLA-DX")

.ENDIF

NOTE: random() needs immediate min and max values.

NOTE: If you use e.g., bank(label) inside an .IF then the current bank for the label is given. If WLALINK e.g., changes the label’s .SECTION’s bank for some reason (e.g., the .SECTION is relocated) then .IF is not calculated correctly.

NOTE: bank(), bankbyte(), base() and slot() without arguments use the information the assembler knows, not the linker.

13.4. Keywords

Here are the supported keyword1s for get()

"section.aligment"              ; returns the current .SECTION's alignment (int)
"section.name"                  ; returns the current .SECTION's name (string)
"section.offset"                ; returns the current .SECTION's offset (int)
"section.priority"              ; returns the current .SECTION's priority (int)
"section.type"                  ; returns the current .SECTION's type (string),
                                ;   possible strings being "FREE", "FORCE", "OVERWRITE",
                                ;   "HEADER", "SEMIFREE", "ABSOLUTE", "SUPERFREE",
                                ;   "SEMISUBFREE" and "SEMISUPERFREE"
"label.latest"                  ; returns the latest defined label

Here are the supported keyword2s for is()

"insidesection"                 ; is the parser at this point inside a .SECTION?