The Boa Programming Guide - Built-In Functions

Boa provides several useful built-in functions. For reference, these functions are described in this section.

Array Functions

new (a: array of basic_type, n: int, v: basic_type) : array of basic_type

Returns a new array of the same type as a, of size n, and with all elements initialized to the value v.

sort (a: array of basic_type) : array of basic_type

Returns the sorted version of an array. Only scalar values can be sorted. Values will be arranged in increasing order.

Date & Time Functions

addday (t: time, n: int [, timezone: string] ) : time

Return the time, n days after the given time t. The value of n may be negative, or n may be absent altogether, in which case n defaults to 1. An optional third argument gives the timezone.

addmonth (t: time, n: int [, timezone: string] ) : time

Return the time, n months after the given time t. The value of n may be negative, or n may be absent altogether, in which case n defaults to 1. An optional third argument gives the timezone.

addweek (t: time, n: int [, timezone: string] ) : time

Return the time, n weeks after the given time t. The value of n may be negative, or n may be absent altogether, in which case n defaults to 1. An optional third argument gives the timezone.

addyear (t: time, n: int [, timezone: string] ) : time

Return the time, n years after the given time t. The value of n may be negative, or n may be absent altogether, in which case n defaults to 1. An optional third argument gives the timezone.

dayofmonth (t: time [, timezone: string] ) : int

The numeric day of the month; for January 17, return 17, etc. An optional second argument names a timezone.

dayofweek (t: time [, timezone: string] ) : int

The numeric day of the week, from Monday=1 to Sunday=7. An optional second argument names a timezone.

dayofyear (t: time [, timezone: string] ) : int

The numeric day of the year. January 1 is day 1. An optional second argument names a timezone.

formattime (format: string, t: time [, timezone: string] ) : string

Return a string containing the time argument formatted according to the format string. The syntax of the format string is the same as in ANSI C strftime. An optional third argument names a timezone.

hourof (t: time [, timezone: string] ) : int

The numeric hour of the day, from 0 to 23. Midnight is 0, 1AM is 1, etc. An optional second argument names a timezone.

minuteof (t: time [, timezone: string] ) : int

The numeric minute of the hour, from 0 to 59. An optional second argument names a timezone.

monthof (t: time [, timezone: string] ) : int

The numeric month of the year. January is 1. An optional second argument names a timezone.

now () : time

Return the current time at the moment of execution. Note that the time value returned does not depend on a timezone.

secondof (t: time [, timezone: string] ) : int

The numeric second of the minute, from 0 to 59. An optional second argument names a timezone.

trunctoday (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the day. Useful when creating variables indexed to a particular day, since all times in the day truncated with trunctoday will fold to the same value, which is the first time value in that day. An optional second argument names a timezone.

trunctohour (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the hour. An optional second argument names a timezone.

trunctominute (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the minute. An optional second argument names a timezone.

trunctomonth (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the month. An optional second argument names a timezone.

trunctosecond (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the second. An optional second argument names a timezone.

trunctoyear (t: time [, timezone: string] ) : time

Truncate t to the zeroth microsecond of the year. An optional second argument names a timezone.

yearof (t: time [, timezone: string] ) : int

The numeric year value, such as 2003. An optional second argument names a timezone.

Map Functions

clear (m: map[key_type] of val_type)

Clears all values from the map m.

clone (m: map[key_type] of val_type)

@since 2019-10
Creates a clone of the map m.

haskey (m: map[key_type] of val_type, key: key_type) : bool

Return a boolean reporting whether the key is present in the map m.

keys (m: map[key_type] of val_type) : array of key_type

Return an array holding, in no particular order, the set of keys present in the map m.

lookup (m: map[key_type] of val_type, key: key_type, value: val_type) : val_type

Return the element of the map m indexed by the key or, if there is no such element, the specified default value. Assuming the map, key, and value are defined, equivalent to: def(m[key]) ? m[key] : value

remove (m: map[key_type] of val_type, k: key_type)

Removes the entry for the key k, if it exists in themap.

values (m: map[key_type] of val_type) : array of val_type

Return an array holding, in no particular order, the set of values present in the map m.

Math Functions

abs (x: type) : type

Return the absolute value of the argument. The type must be one of int or float.

acos (x: float) : float

The arc cosine of x.

acosh (d: float) : float

The hyperbolic arc cosine function.

asin (x: float) : float

The arc sine of x.

asinh (d: float) : float

The hyperbolic arc sine function.

atan (x: float) : float

The arc tangent of x.

atan2 (x: float, y: float) : float

The arc tangent of y/x.

atanh (d: float) : float

The hyperbolic arc tangent function.

ceil (x: float) : float

Round x up to the nearest integer.

cos (x: float) : float

The cosine of x.

cosh (x: float) : float

The hyperbolic cosine of x.

exp (x: float) : float

The exponential, base e, of x.

floor (x: float) : float

Round x down to the nearest integer.

highbit (n: int) : int

Return an integer representing the bit position of the highest one bit in n. If n is zero, the result is 0; if n is 1, the result is 1, if n is 15, the result is 4, etc.

isfinite (n: float) : bool

Tests if the value n is not Inf and not NaN.

isinf (n: float) : bool

Tests if the value n is Inf.

isnan (n: float) : bool

Tests if the value n is NaN.

isnormal (n: float) : bool

Tests if the value n is neither 0, subnormal, Inf, or NaN.

log (x: float) : float

The natural logarithm of x.

log10 (x: float) : float

The logarithm base 10 of x.

max (v1: type, v2: type) : type

Return the maximum of v1 and v2. The type must be one of int, time, string, or float.

min (v1: type, v2: type) : type

Return the minimum of v1 and v2. The type must be one of int, time, string, or float.

nrand (n: int) : int

Return a random integer x in the range 0 <= x < n.

pow (x: float, y: float) : float

The exponential, base x, of y.

rand () : float

Return a random floating point number x in the range 0.0 < x < 1.0.

round (x: float) : float

Round x to the nearest integer, but round halfway cases away from zero.

sin (x: float) : float

The sine of x.

sinh (x: float) : float

The hyperbolic sine of x.

sqrt (x: float) : float

The square root of x.

tan (x: float) : float

The tangent of x.

tanh (x: float) : float

The hyperbolic tangent of x.

trunc (x: float) : float

Round to the nearest integer not larger in absolute value than x.

Other Functions

def (v: any_type) : bool

Returns a boolean value according to whether v has a defined value.

hash (v: any_type) : int

The hash function returns a hash of the argument v, which may be of any type.

len (v: any_type) : int

Return the number of elements in v, which must be an array or map or of type string.

  • If string, the value is the number of Unicode characters in the string.
  • If a map, the value is the number of distinct keys present.

Queue Functions

clear (q: queue of val_type)

Clears all values from the queue q.

offer (q: queue of val_type, val: val_type)

Offers the value val to the queue q.

peek (q: queue of val_type) : val_type

Returns the latest value on the queue q without removing it from the queue.

poll (q: queue of val_type) : val_type

Polls the queue q and removes the oldest value and returns it.

values (q: queue of val_type) : array of val_type

Return an array holding the values present in the queue q.

Set Functions

add (s: set of val_type, v: val_type)

Adds the value v to the set.

clear (s: set of val_type)

Clears all values from the set s.

clone (s: set of val_type)

@since 2019-10
Creates a clone of the set s.

contains (s: set of val_type, v: val_type) : bool

Returns if the set contains the value v.

containsall (s1: set of val_type, s2: set of val_type) : bool

Returns if the set s1 contains all of the values in set s2.

difference (s1: set of val_type, s2: set of val_type) : set of val_type

Returns the set s1 with all values from s2 removed.

intersect (s1: set of val_type, s2: set of val_type) : set of val_type

Returns a set containing all values in both the sets s1 and s2.

remove (s: set of val_type, v: val_type)

Removes the value v from the set, if it contains it.

symdiff (s1: set of val_type, s2: set of val_type) : set of val_type

Equivalent to union(difference(s1, s2), difference(s2, s1)).

union (s1: set of val_type, s2: set of val_type) : set of val_type

Returns a set containing all values in either the set s1 or the set s2.

values (s: set of val_type) : array of val_type

Return an array holding the values present in the set s.

Stack Functions

clear (s: stack of val_type)

Clears all values from the stack s.

peek (s: stack of val_type) : val_type

Returns the last value on the stack s without removing it from the stack.

pop (s: stack of val_type) : val_type

Pops the last value off the stack s and returns it.

push (s: stack of val_type, val: val_type)

Pushes the value val onto the stack s.

values (s: stack of val_type) : array of val_type

Return an array holding the values present in the stack s.

String Functions

format (format: string, args: string, ...) : string

Return a string containing the arguments formatted according to the format string. The syntax of the format string is essentially that of ANSI C with the following differences:

  • %b prints a boolean, "true" or "false".
  • %c prints a (u)int as a Unicode character in UTF-8.
  • %k like %c with single quotes and backslash escapes for special characters.
  • %s prints a string as UTF-8.
  • %q like %s with double quotes and backslash escapes for special characters.
  • %t prints a time, in the format of the Unix function ctime without a newline.
  • %T prints the type of the argument; %#T expands user-defined types.
  • %d / %i / %o / %u / %x / %X apply to a (u)int and have no 'l' or 'h' modifiers.
  • %e / %f / %g / %E / %G apply to a float and have no 'l' or 'h' modifiers.

format verbs 'n' and '*' are not supported.

lowercase (str: string) : string

Returns a copy of the given string str with all characters lower-cased.

match (regex: string, str: string) : bool

Search for a match of the regular expression regex within str , and return a boolean value indicating whether a match was found.

matchposns (regex: string, str: string) : array of int

Search for a match of the regular expression regex within str, and return an array consisting of character positions within str defined by the match. Positions 0 and 1 of the array report the location of the match of the entire expression, subsequent pairs report the location of matches of successive parenthesized subexpressions.

matchstrs (regex: string, str: string) : array of string

Search for a match of the regular expression regex within str, and return. The 0th string is the entire match; following elements of the array hold matches of successive parenthesized subexpressions. This function is equivalent to using matchposns to find successive locations of matches and created array slices of str with the indices returned.

regex (t: any_type, base: int) : string

Returns a string holding a regular expression suitable for matching text representing values of the specified type t. For example, regex(int) generates a string to match integer constants (-23, 0x1f, etc.). At the moment, only int and float types are supported. When the type is int, an optional numerical base may be specified for the conversion.

split (s: string, regex: string) : array of string

Slice string s into pieces according to subsequent matches of the regular expression regex. Runs along the regular expression exactly once.

splitall (s: string, regex: string) : array of string

Slice string s into pieces according to subsequent matches of the regular expression regex. Runs along the regular expression until the input string is exhausted.

splitn (n: int, s: string, regex: string) : array of string

Slice string s into pieces according to subsequent matches of the regular expression regex. Runs along the regular expression at most n times.

strfind (needle: string, haystack: string) : int

Search for the first occurrence of the needle within haystack and return the integer index of its first character, or -1 if it does not occur.

strreplace (haystack: string, needle: string, replacement: string, replace_all: bool) : string

Return a copy of string haystack, with non-overlapping instances of needle replaced by replacement. If replace_all is false, only the first found instance is replaced.

strrfind (needle: string, haystack: string) : int

Search for the last occurrence of the needle within haystack and return the integer index of its first character, or -1 if it does not occur.

substring (str: string, start: int [, end: int] ) : string

Returns a substring of str starting at start (inclusive) and ending at end (exclusive). If end is not specified, the length of the string is used.

trim (str: string) : string

Returns a copy of the given string str with all leading and trailing whitespace removed.

uppercase (str: string) : string

Returns a copy of the given string str with all characters upper-cased.

Type Conversion Functions

bool (v: basic_type) : bool

Converts the value v into a boolean value.

float (v: basic_type) : float

Converts the value v into a float value.

int (v: basic_type) : int

Converts the value v into an int value.

string (v: basic_type) : string

Converts the value v into a string value.

time (v: basic_type) : time

Converts the value v into a time value.