Mercurial > hg > xemacs-beta

comparison man/lispref/functions.texi @ 398:74fd4e045ea6 r21-2-29

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-29
author cvs
date Mon, 13 Aug 2007 11:13:30 +0200
parents 376386a54a3c
children 697ef44129c6
comparison
equal deleted inserted replaced
397:f4aeb21a5bad 398:74fd4e045ea6
678 @node Mapping Functions 678 @node Mapping Functions
679 @section Mapping Functions 679 @section Mapping Functions
680 @cindex mapping functions 680 @cindex mapping functions
681 681
682 A @dfn{mapping function} applies a given function to each element of a 682 A @dfn{mapping function} applies a given function to each element of a
683 list or other collection. XEmacs Lisp has three such functions; 683 list or other collection. XEmacs Lisp has several such functions;
684 @code{mapcar} and @code{mapconcat}, which scan a list, are described 684 @code{mapcar} and @code{mapconcat}, which scan a list, are described
685 here. For the third mapping function, @code{mapatoms}, see 685 here. @xref{Creating Symbols}, for the function @code{mapatoms} which
686 @ref{Creating Symbols}. 686 maps over the symbols in an obarray.
687
688 Mapping functions should never modify the sequence being mapped over.
689 The results are unpredictable.
687 690
688 @defun mapcar function sequence 691 @defun mapcar function sequence
689 @code{mapcar} applies @var{function} to each element of @var{sequence} 692 @code{mapcar} applies @var{function} to each element of @var{sequence}
690 in turn, and returns a list of the results. 693 in turn, and returns a list of the results.
691 694
692 The argument @var{sequence} may be a list, a vector, or a string. The 695 The argument @var{sequence} can be any kind of sequence; that is, a
693 result is always a list. The length of the result is the same as the 696 list, a vector, a bit vector, or a string. The result is always a list.
694 length of @var{sequence}. 697 The length of the result is the same as the length of @var{sequence}.
695 698
696 @smallexample 699 @smallexample
697 @group 700 @group
698 @exdent @r{For example:} 701 @exdent @r{For example:}
699 702
714 (defun mapcar* (f &rest args) 717 (defun mapcar* (f &rest args)
715 "Apply FUNCTION to successive cars of all ARGS. 718 "Apply FUNCTION to successive cars of all ARGS.
716 Return the list of results." 719 Return the list of results."
717 ;; @r{If no list is exhausted,} 720 ;; @r{If no list is exhausted,}
718 (if (not (memq 'nil args)) 721 (if (not (memq 'nil args))
719 ;; @r{apply function to @sc{CAR}s.} 722 ;; @r{apply function to @sc{car}s.}
720 (cons (apply f (mapcar 'car args)) 723 (cons (apply f (mapcar 'car args))
721 (apply 'mapcar* f 724 (apply 'mapcar* f
722 ;; @r{Recurse for rest of elements.} 725 ;; @r{Recurse for rest of elements.}
723 (mapcar 'cdr args))))) 726 (mapcar 'cdr args)))))
724 @end group 727 @end group
736 Between each pair of result strings, @code{mapconcat} inserts the string 739 Between each pair of result strings, @code{mapconcat} inserts the string
737 @var{separator}. Usually @var{separator} contains a space or comma or 740 @var{separator}. Usually @var{separator} contains a space or comma or
738 other suitable punctuation. 741 other suitable punctuation.
739 742
740 The argument @var{function} must be a function that can take one 743 The argument @var{function} must be a function that can take one
741 argument and return a string. 744 argument and return a string. The argument @var{sequence} can be any
745 kind of sequence; that is, a list, a vector, a bit vector, or a string.
742 746
743 @smallexample 747 @smallexample
744 @group 748 @group
745 (mapconcat 'symbol-name 749 (mapconcat 'symbol-name
746 '(The cat in the hat) 750 '(The cat in the hat)