Introduction to newLISP/Apply and map

= Apply and map: applying functions to lists =
Making functions and data work together.
Often, you'll find that you've got some data stored in a list and you want to apply a function to it. For example, suppose that you've acquired some temperature readings from a space probe, and they're stored in a list called "data":
How are you going to add these numbers up, and then divide by the total, to find the average? Perhaps you think you could use add, which totals a list of floating-point numbers, but you're not working interactively, so you can't edit the code to read like this:
Since we're holding the data in a symbol called "data", we might try this:
but no, this doesn't work, because add wants numbers to add, not a list. You could of course do it the hard way and write a loop that works through each item in the list and increases a running total each time:
 (inc total i))
This works fine. But newLISP has a much more powerful solution, for this and many other problems: you can treat functions as data and data as functions, so you can manipulate functions as easily as you can manipulate your data. You can just 'introduce' add and the data list to each other, and then stand back and let them get on with it.
There are two important functions for doing this: apply and map.
apply.
apply takes a function and a list, and makes them work together:
and this produces the required result. Here we've treated the add function like any other newLISP list, string, or number, using it as an argument to another function. You don't need to quote it (although you can), because apply is already expecting the name of a function.
map.
The other function that can make functions and lists work together is map, which applies a function to each item of a list, one by one. For example, if you wanted to apply the floor function to each element of the data list (to round them down to the nearest integer) you could combine map, floor, and the data as follows:
and the floor function is applied to each element of the data. The results are combined and returned in a new list.
apply and map in more detail.
Both apply and map let you treat functions as data. They have the same basic form:
where "f" is the name of a function and "l" is a list. The idea is that you tell newLISP to process a list using the function you specify.
The apply function uses all the elements in the list as arguments to the function, and evaluates the result.
Here, apply looks at the list, which in this case consists of a single string, and feeds the elements to the function as arguments. The string gets reversed. Notice that you don't have to quote the function but you do have to quote the list, because you don't want newLISP to evaluate it before the designated function gets a chance to consume it.
The map function, on the other hand, works through the list, element by element, like a sergeant major inspecting a row of soldiers, and applies the function to each element in turn, using the element as the argument. However, map remembers the result of each evaluation as it goes, collects them up, and returns them in a new list.
So map looks like a control-flow word, a bit like dolist, whereas apply is a way of controlling the newLISP list evaluation process from within your program, calling a function when and where you want it called, not just as part of the normal evaluation process.
If we adapt the previous example for map, it gives a similar result, although the result is a list, not a string:
Because we've used a list with only one element, the result is almost identical to the apply example, although notice that map returns a list whereas, in this example, apply returns a string: 
The string has been extracted from the list, reversed, and then stored in another list created by map.
In the next example:
you can clearly see that map has applied reverse to each element of the list in turn, and returned a list of the resulting reversed strings.
Write one in terms of the other?
To illustrate the relationship between these two functions, here is an attempt at defining map in terms of apply:
(define (my-map f l , r) 
 ; declare a local variable r to hold the results
 (dolist (e l)
 (push (apply f (list e)) r -1)))
We're pushing the result of applying a function "f" to each list item to the end of a temporary list, and then relying on push returning the list at the end, just as map would do. This works, at least for simple expressions:
This example illustrates why map is so useful. It's an easy way to transform all the elements of a list without the hassle of working through them element by element using a dolist expression.
More tricks.
Both map and apply have more tricks up their sleeves. map can traverse more than one list at the same time. If you supply two or more lists, newLISP interleaves the elements of each list together, starting with the first elements of each list, and passes them as arguments to the function:
Here the first element of each list is passed as a pair to append, followed by the second element of each list, and so on.
This weaving together of strands is a bit like knitting with lists. Or like doing up a zip. 
apply has a trick too. A third argument indicates how many of the preceding list's arguments the function should use. So if a function takes two arguments, and you supply three or more, apply comes back and makes another attempt, using the result of the first application and another argument. It continues eating its way through the list until all the arguments are used up. 
To see this in action, let's first define a function that takes two arguments and compares their lengths:
 (println s1 " is longest so far, is " s2 " longer?") ; feedback
 (if (&gt;= (length s1) (length s2)) ; compare 
 s1
 s2))
Now you can apply this function to a list of strings, using the third argument to tell apply to use up the arguments two strings at a time:
(apply longest '("green" "purple" "violet" "yellow" "orange"
"black" "white" "pink" "red" "turquoise" "cerise" "scarlet"
"lilac" "grey" "blue") 2)
It's like walking along the beach and finding a pebble, and holding on to it until an even better one turns up.
apply also gives you a way of working through a list and applying a function to each pair of items:
 (println {x is } x {, y is } y)) (sequence 0 10) 2)
What's happening here is that the value returned by the println function is the second member of the pair, and this becomes the value of the first element of the next pair.
Lispiness.
This thing about passing around the names of functions as if they were bits of data is very characteristic of newLISP, and it's very useful. You will find many uses for it, sometimes using functions that you don't think will be useful with map. Here, for example, is set working hard under the control of map:
This construction gives you another way to assign values to symbols in parallel, rather than sequentially. (You can use swap as well.)
Some uses of map are simple:
Others can become quite complex. For example, given a string of data in this form, stored in a symbol "image-data": 
the two numbers can be extracted with:
currying.
Some of the built-in newLISP functions do things with other functions. An example is curry, which creates a copy of a two-argument function and creates a single-argument version with a pre-determined first argument. So if a function "f1" was often called like this:
you can use curry to make a new function "f2" that has a ready-to-use built-in "arg1":
now you can forget about that first argument, and just supply the second one to "f2":
Why is this useful? Consider the dup function, which often gets used to insert multiple blank spaces:
Using curry, you can create a new function called, say, "blank", that's a special version of dup that always gets called with a blank space as the string:
Now you can use "(blank n)":
curry can be useful for creating temporary or anonymous functions with map:
(map (fn (x) (pow 2 x)) (sequence 1 10)) ; equivalent
But avoid using curry on destructive functions like inc, for example:
(map (curry inc 3) a-list-of-pairs) ;-&gt; you would expect (5 7 9 11 13), instead you get