7. Built-in and Compiled Functions

There are three types of  functions in Basis. The first, Basis language functions, are also called ``user'' functions. The other kinds are ``built-in'' and ``compiled.''  Built-in functions are a special form of compiled function, either supplied as part of the Basis  parser itself like cos  or iota  or sqrt,  or written by a particularly Basis-skilled code developer. Compiled functions are ordinary Fortran routines whose calling sequence has been ``taught'' to the Basis interpreter.

Built-ins are usually used when it is desired to accept different kinds of Basis objects as arguments and return whatever type of object is appropriate. For example, many numerical-valued built-in functions will accept an arbitrary array of numbers and return an array of the same type, size and shape, whose entries were obtained by applying the function to each entry in the original array. Many of the most useful functions described below are designed to operate specifically on arrays.

For information on any individual function you can use  LIST followed by the name of the particular function. In addition to giving you more information about what the function does, the output will also tell you what (if anything) the function returns, how many arguments it has, what their types are, etc. The Basis reference document also has more complete information. We discuss some of the more useful built-in and  compiled functions in the following sections.

The size or  length of an array is its total number of elements. The  shape of an array is a vector whose components tell how many values the respective subscripts of the array can take on.

In Basis arithmetic, arrays must be of the same size and shape to participate in componentwise binary operations such as  +,  -,  *, and  /. The only exception is that one operand can be an array and the other a scalar, in which case the scalar is broadcast, which means that the operation is applied to the scalar versus every element of the array. Another way of thinking of it is that the scalar is expanded into an array of the same size and shape as the other operand, each element of which has the original scalar value.

Most functions which accept array arguments will also accept scalar arguments along with arrays, in which case they broadcast the scalars as described above.

Some of the functions below which accept array arguments don't care about shape, but only size. In this case they operate on corresponding components of their respective arguments, but you need to know what ``corresponding components'' are when the subscripts have different ranges. This is done in a fairly natural way: arrays in Basis, as Fortran, are stored in  column major order (i.e., the first subscript varies most rapidly as we go through the array in memory). The elements of two arrays of different shape but the same size are said to correspond if they occupy the same relative position in this memory hierarchy.

When a function is called with an argument of the wrong type, or an expression involves mixed numerical types, Basis will perform automatic type  coercion if necessary. For example,


results in the ``3'' being converted to ``3.0'' before the addition operation, and if f(x) is a compiled function expecting a real argument x, then


actually results in


In an array of numerical constants of mixed types, its elements will be  coerced to the highest type in the  hierarchy  integer $ \rightarrow $  real$ \rightarrow $  double$ \rightarrow $  complex.

Likewise, most  built-in functions try to do the right thing. For example,  sqrt(2) means sqrt(2.0).

Doubles are coerced to reals, and thence to integers, by truncation.  Logical  true converts to and from integer 1, and logical  false converts to and from integer 0.