Indirection Operators:

C programmers will be familiar with the idea of indirection from the unary & and * operators. The TE language provides a similar mechanism whereby the unary & operator can be applied to a variable name and it returns a pointer to the variable (actually it returns the offset of the variable in the internal variable table assigned by the Telecom Engine).

Once a pointer to a variable has been obtained using the & operator then the unary * operator can then be used to access the variable the this pointer refers to.

For example,

int a, b, c;

main

    b=123;    // assign a value to b

    a = &b;   // a holds the pointer to variable b

    c=*a;    // c is assigned the value of b

    *a=10;   // b is set to 10

endmain

In the above program the variable b is assigned the value 123.     Then the variable a is set to hold a pointer to b.     This will actually be the integer offset into the internal variable table held by the Telecom Engine, so in the above case this will be 1 (a would  be at offset 0, b at 1, c at 2).     Don’t rely on these offset values though since the way variables are stored in the Telecom Engine may change in the future.

The next line sets c to the contents of the variable pointed to by a which in this case is the contents of variable b – i.e. 123.

Finally the contents of the variable pointed to by a is set to the value 10,  so in fact variable b is now set to 10.

The unary * operation is called "dereferencing".

The unary * operator may only be applied to variables or function arguments. The expression (*2),  though is illegal -- it does not mean "variable number two".

The main use this mechanism is to allow a function to alter the value of a variable passed as an argument to a function. In the TE language function arguments are passed "by value".   This means that when a function is called, each function argument is evaluated to a string, and the string values copied to an area of memory that the function can access.    The function therefore only has a copy of the values passed to it and can’t alter the values held in the original variables.

For example, in the following program:

var x:3;

main

    x = "ABC";

    f(x);

    applog("x=",x);

endmain

func f(argument)

    argument="ZYX";   // this is illegal

endfunc

This would result in a compiler error since the function is attempting to change the value of a function argument which is in fact just a copy of the original string that is now stored on the program stack.      If the compiler allowed this value to be changed then it could result in the stack being overwritten if a longer string was assigned.   In fact it doesn’t usually make sense to try and change the value of arguments like this so it has been made illegal in the TE language.     

What is usually required is for the original value of the variable passed to the function to be changed and this is what the indirection operators are for.     Instead of passing a copy of the variable to the function, a pointer to the variable can be passed instead.   For example:

main

    var x:20;

   

    x= "ABC"

    f(&x);     // pass a pointer to the variable x

    applog("x=",x);     // x has now been changed by f()

endmain

func f(arg)

    *arg = "ZYX";    // Use the dereference operator to change the variable pointed to by arg

endfunc

This program will assign the string "ZYX" to variable x, and write this string to the screen.

Note that the unary & operator cannot be applied to function arguments. The following is illegal:

func f(a)

    g(&a);        // Illegal

endfunc

However, variable numbers may (like any other string value) be passed through any number of levels of function calls:

main

var x:50;

    f(&x);

    applog("x=",x); // value of x changed by function g()

endmain

func f(af)

    g(af);

endfunc

func g(ag)

   *ag = "New value";

endfunc

Caution needs to be used when using the indirection operators.   The Telecom Engine provides no protection from meaningless code like:

x = 36;

*x = "ABC";

which would unexpectedly over-write the variable at offset 36 in the TE variable table.