Functions (aime)

9 Functions

Functions are the basic blocks of procedural programs, with aime procedural programs consisting solely of function definitions and declarations.

Functions describe complex actions that may be taken over an input set. When called, functions are meant to evaluate to values and/or to have side effects.

Functions have valid aime identifier names, starting with ‘_’ or a letter and continuing with ‘_’ signs, letters and digits.

aime functions are blocks (sequences of instructions) that associate an input collection of values and that may return a value.

The input of a function is a series of values, most often of defined size and value types. The series is described as a sequence of variable declarations and the values are accessed by the function statements by their variable names.

integer
median3(integer a, integer b, integer c)
{
    integer m;

    if (a < b) {
	if (b < c) {
	    m = b;
	} else {
	    if (a < c) {
		m = c;
	    } else {
		m = a;
	    }
	}
    } else {
	if (a < c) {
	    m = a;
	} else {
	    if (b < c) {
		m = c;
	    } else {
		m = b;
	    }
	}
    }

    return m;
}

The function ‘median3’ takes three arguments of type ‘integer’. It determines the median of the input set, i.e. the value that is neither the greatest nor the smallest. The three arguments are prescribed by the function parameters list declaration (‘integer a, integer b, integer c’). The argument values are accessed by the parameter names (‘a’, ‘b’, ‘c’).

Functions that take no arguments are declared as having ‘void’ arguments lists.

integer
thirteen(void)
{
    return 13;
}

void
tr_write(file f, text s, real r)
{
    f_text(f, s);
    f_space(f, 1);
    f_real(f, 8, r);
    f_newline(f);
}

or the close equivalent

void
tr_write(file f, text s, real r)
{
    f_form(f, "~ ~\n", s, r);
}

writes the ‘s’ string, a space, the ‘r’ real and a new line on the ‘f’ file.

When called, the functions are ordinarily passed the (evaluated) values of the expressions that describe their arguments, i.e. the values are copied to a space available to the called function only and when the values of the parameter variables are modified, they are modified in this private space. Functions may nonetheless allow their arguments to be passed by reference and in this case the parameter modification will take effect in the larger scope of the function call. The pass by reference is indicated by the ‘&’ literal sign preceding the parameter name in the function parameters list.

void
zero(integer &a)
{
    a = 0;
}

void
no_effect(integer a)
{
    a = 0;
}

The function ‘zero’ sets it only argument to 0. The ‘no_effect’ function does the same. The latter call has nonetheless no effect on the variable passed as its argument, while the former will have the effect of resetting it, and the program:

integer
main(void)
{
    integer v;

    v = 1;
    no_effect(v);
    o_plan(v, "\n");
    zero(v);
    o_plan(v, "\n");

    return 0;
}

will print:

1
0

Functions may return values. The ‘median3’ function returns the median value in its input set. The ‘tr_write’, ‘zero’ and ‘no_effect’ functions return no value.

Functions returning no value are of the ‘void’ return type.

When functions return a value, the value is given by the last statement, which is a simple statement (not a compound, control statement). The statement giving the return value may be introduced by the ‘return’ keyword.

Whether functions return or not a value, their return type is always fixed and specified.

There are no restrictions on the types and values a function may return (though special aime interpreter builds may place such restrictions). A function may return referable data, data of complex types, the values of internal variables, temporaries, etc.

list
numbers(void)
{
    return list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
}

The function ‘numbers’ returns a list with 10 elements, the numbers 0 through 9 (the type of data is ‘integer’).

text
this_year(void)
{
    date d;

    d.now();

    itoa(d.year);
}

text
this_year_b(void)
{
    date().now.year.itoa;
}

The functions ‘this_year’* returns the current year as a string.

file
output(void)
{
    file().open("/dev/stdout", OPEN_WRITE, 0);
}

The ‘output’ function opens "/dev/stdout" for writing and returns the file object.