Level 5 Functions

Function Comment
access The call access(x,y,z) returns the brick that occupies the cell at location (x,y,z).
traverseWithin Let f denote a function that, when applied to a point (x,y,z), returns a brick (e.g., BLUE or EMPTY). The call

traverseWithin (0,0,0) (10,20,30) f

will traverse all the points in the following set.

{ (0,0,0), (0,0,1), …, (10,20,30) }

For each point (x,y,z) visited, the result of the function call f(x,y,z) (i.e., a brick) will be placed at (x,y,z). No assumptions should be made about the order in which points in the set are visited as the implementation of traverseWithin may change in future versions of Bricklayer.

applyWithin Let f denote a function that, when applied to a point (x,y,z), returns the unit value. User-defined functions that construct LEGO artifacts using Bricklayer functions from Level_1, Level_2, Level_3, or Level_4 are examples of functions that return the unit value. The call

applyWithin (0,0,0) (10,20,30) f

will traverse all the points in the following set.

{ (0,0,0), (0,0,1), …, (10,20,30) }

The function f is applied to each point (x,y,z) visited in the traversal. No assumptions should be made about the order in which points in the set are visited as the implementation of applyWithin may change in future versions of Bricklayer.

iterateZX The function iterateZX visits points in a given xz-range in a specific order. A call to iterateZX has the form shown below.

iterate y (x1,z1) (x2,z2) f

In the above call, the points (x1,z1)/(x2,z2) denote either the lower-left/upper-right or upper-right/lower-left corners of a rectangle in the xz-plane. The value y denotes the y-value of the points to be considered (e.g., (x1,y,z1) and (x2,y,z2)). Lastly, f denotes a function that, when applied to a point (x,y,z), returns a brick (e.g., BLUE or EMPTY).

A concrete example of a call to iterateZX is shown below.

iterateZX 5 (0,0) (2,3) f

In this call, points will be visited in the following order:

(0,5,0), (1,5,0), (2,5,0), (0,5,1), (1,5,1), …, (2,5,3)

Conceptually, one can thing of iterateZX as an Flip Numbers Setodometer with the Z value in the tens position and the X value in the ones position. It is to encourage this conceptual understanding that the function is named iterateZX and not iterateXZ.

Inspecting the Order in which Points are Visited

The program below shows how to instrument a brick function so that it displays (in the commant prompt window) each point to which it is applied. This function can then be passed either totraverseWithin or iterateZX. For the function iterateZX it is guaranteed that future versions Bricklayer will visit points in the same order. However, no such guarantee is given for traverseWithin. Therefore, you should not write programs whose correctness relies on traverseWithin visiting points in a particular order.

Note that functions suitable for applyWithin can be instrumented in a similar manner.

open Level_5;

fun observeIterator (x,y,z) = 
    (
        print ("(x,y,z) = (" ^ 
               Int.toString x ^ "," ^ 
               Int.toString y ^ "," ^ 
               Int.toString z ^ ")\n");
        BLUE
    );

fun test1() = traverseWithin (0,0,0) 
                             (1,2,3) 
                             observeIterator;
fun test2() = iterateZX 5 (0,0) (2,3) observeIterator;
fun test3() = iterateZX 5 (2,3) (0,0) observeIterator;

build (10,10,10); 

test2();

show "order visited";                     

iterateZX_01