Mapping

The list mapping functions all take a function argument fun as the first argument then 1 or 2 list arguments lists. The function argument fun must have as many arguments as there are list arguments. The given list or lists are mapped over or into a new list using fun. The function fun is successively applied to the list or lists and its return value, except for mapc and mapl, is used to construct a new list in the same order as the given lists. For mapc and mapl fun is successively applied for side effect only and the original first list is just returned. For mapcar, maplist, mapcan and mapcon the newly mapped list is returned.

If more that one list is given then the shortest list terminates the mapping.

mapcar fun lists

Function

maplist fun lists

Function

The lists lists are mapped over by fun and the mapped list is returned. mapcar maps over successive elements of the lists which are passed to fun. maplist maps over successive cdrs of the lists which are passed to fun. For example:

     let list1 = list(L("one"), L("two"), L("three"));
     mapcar(L(lengthL), list1) => (3, 3, 5)
     let list2 =
       list(L(" cat"), L(" dogs"), L(" bears"), L(" lions"));
     mapcar(L(stringConcat), list1, list2)
             => ("one cat", "two dogs", "three bears")
     maplist(L(lengthL), list1) => (3, 2, 1)
     maplist(L(identity), list1)
             => (("one" "two" "three") ("two" "three") ("three"))
     

mapc fun lists

Function

mapl fun lists

Function

The lists lists are mapped over by fun and the first list, ie. the second argument, is returned. mapc maps over successive elements of the lists which are passed to fun. mapl maps over successive cdrs of the lists which are passed to fun. For example:

     let list1 = list(L("One"), L("Two"), L("Three"));
     let (*princOne)(let) = &princ;
     mapc(L(princOne),list1);  // Prints on cout: OneTwoThree
     

The mapping functions mapcan and mapcon are the same as mapcar and maplist respectively except that it is as if nconc were applied to the resulting values returned by fun. It is important to notice that because of this the values returned by fun are concatenated together by destructively modifying them. Usually the function fun creates and returns new lists each time being aware that they will be modified by being concatenated together.

mapcan fun lists

Function

mapcon fun lists

Function

The lists lists are mapped over by fun and the values returned by fun are concatenated together, as if by using nconc, and the concatenation is returned. mapcan maps over successive elements of the lists which are passed to fun. mapcon maps over successive cdrs of the lists which are passed to fun.

mapcan and mapcon can be used for combining or filtering. For example:

     // Example of filtering:
     let passNums(let x)
          {if (numberp(x)) return list(x); return Nil;}
     let list1 = list(L(1), S(a), L(2), S(b), L(3), S(c));
     mapcan(L(passNums), list1) => (1 2 3)
     // Example of combining:
     list1 = readFromString("((1 2 3) (4 5 6) (7 8 9 10))");
     mapcan(L(copyList), list1)  => (1 2 3 4 5 6 7 8 9 10)