User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:macros:dotimes [2019/12/05 03:00]
cl:macros:dotimes [2019/12/07 02:00] (current)
Line 1: Line 1:
 +====== Macro DOTIMES ======
 +
 +====Syntax====
 +  * **dotimes** //(var count-form [result-form]) declaration''​*''​ {tag | statement}''​*''//​ → //​result''​*''//​
 +
 +====Arguments and Values====
 +  * //var// - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​count-form//​ - a //​[[CL:​Glossary:​form]]//​.
 +  * //​result-form//​ - a //​[[CL:​Glossary:​form]]//​.
 +  * //​declaration//​ - a \misc{declare} //​[[CL:​Glossary:​expression]]//;​ \noeval.
 +  * //tag// - a //​[[CL:​Glossary:​go tag]]//; \noeval.
 +  * //​statement//​ - a //​[[CL:​Glossary:​compound form]]//; \evalspecial.
 +  * //results// - if a **[[CL:​Macros:​return]]** or **[[CL:​Macros:​return-from]]** form is executed, the //​[[CL:​Glossary:​values]]//​ passed from that //​[[CL:​Glossary:​form]]//;​ otherwise, the //​[[CL:​Glossary:​values]]//​ returned by the //​result-form//​ or **[[CL:​Constant Variables:​nil]]** if there is no //​result-form//​.
 +
 +====Description====
 +
 +**dotimes** iterates over a series of //​[[CL:​Glossary:​integer|integers]]//​.
 +
 +**dotimes** evaluates //​count-form//,​ which should produce an //​[[CL:​Glossary:​integer]]//​. If //​count-form//​ is zero or negative, the body is not executed. **dotimes** then executes the body once for each //​[[CL:​Glossary:​integer]]//​ from 0 up to but not including the value of //​count-form//,​ in the order in which the //tags// and //​statements//​ occur, with //var// bound to each //​[[CL:​Glossary:​integer]]//​. Then //​result-form//​ is evaluated. At the time //​result-form//​ is processed, //var// is bound to the number of times the body was executed. //Tags// label //​statements//​.
 +
 +An //​[[CL:​Glossary:​implicit block]]// named **[[CL:​Constant Variables:​nil]]** surrounds **dotimes**.
 +
 +**[[CL:​Macros:​return]]** may be used to terminate the loop immediately without performing any further iterations, returning zero or more //​[[CL:​Glossary:​value|values]]//​.
 +
 +The body of the loop is an //​[[CL:​Glossary:​implicit tagbody]]//;​ it may contain tags to serve as the targets of **[[CL:​Special Operators:​go]]** statements. Declarations may appear before the body of the loop.
 +
 +The //​[[CL:​Glossary:​scope]]//​ of the binding of //var// does not include the //​count-form//,​ but the //​result-form//​ is included.
 +
 +It is //​[[CL:​Glossary:​implementation-dependent]]//​ whether **dotimes** //​[[CL:​Glossary:​establish|establishes]]//​ a new //​[[CL:​Glossary:​binding]]//​ of //var// on each iteration or whether it //​[[CL:​Glossary:​establish|establishes]]//​ a binding for //var// once at the beginning and then //assigns// it on any subsequent iterations.
 +
 +====Examples====
 +<​blockquote>​
 +(dotimes (temp-one 10 temp-one)) → 10
 +([[CL:​Macros:​defparameter]] *temp-two* 0) → 0
 +(dotimes (*temp-one* 10 [[CL:​Constant Variables:​t]]) ([[CL:​Macros:​incf]] *temp-two*)) → [[CL:​Constant Variables:​t|T]]
 +*temp-two* → 10 
 +</​blockquote>​
 +
 +Here is an example of the use of **dotimes** in processing strings. We define a function which returns tue if the specified subsequence of the string is a palindrome (reads the same forwards and backwards).
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] palindromep (string &​optional (start 0) (end ([[CL:​Functions:​length]] string))) ​
 +  (dotimes (k ([[CL:​Functions:​floor]] ([[CL:​Functions:​math-subtract|-]] end start) 2) [[CL:​Constant Variables:​t]]) ​
 +    ([[CL:​Macros:​unless]] ([[CL:​Functions:​char-equal]] ([[CL:​Functions:​char]] string ([[CL:​Functions:​math-add|+]] start k)) 
 +            ([[CL:​Functions:​char]] string ([[CL:​Functions:​math-subtract|-]] end k 1)))
 +      ([[CL:​Macros:​return]] [[CL:​Constant Variables:​nil]])))) <​r>​PALINDROMEP</​r>​
 +(palindromep "Able was I ere I saw Elba") <​r>​[[CL:​Constant Variables:​t|T]]</​r>​
 +
 +([[CL:​Macros:​defvar]] *palindrome-1* ​
 +  "A man, a plan, a canal--Panama!"​) <​r>​*PALINDROME-1*</​r>​
 +(palindromep *palindrome-1*) <​r>​[[CL:​Constant Variables:​nil|NIL]]</​r>​
 +([[CL:​Functions:​remove-if-not]] #'​[[CL:​Functions:​alpha-char-p]] *palindrome-1*) ; Remove punctuation. ​
 +<​r>"​AmanaplanacanalPanama"</​r>​
 +(palindromep ([[CL:​Functions:​remove-if-not]] #'​[[CL:​Functions:​alpha-char-p]] *palindrome-1*)) <​r>​[[CL:​Constant Variables:​t|T]]</​r>​
 +
 +([[CL:​Macros:​defvar]] *palindrome-2* ​
 +  "​Unremarkable was I ere I saw Elba Kramer, nu?") <​r>​*PALINDROME-2*</​r>​
 +(palindromep ([[CL:​Functions:​remove-if-not]] #'​[[CL:​Functions:​alpha-char-p]] *palindrome-2*)) <​r>​[[CL:​Constant Variables:​t|T]]</​r>​
 +
 +([[CL:​Macros:​defvar]] *palindrome-3*
 +  "A man, a plan, a cat, a ham, a yak, a yam, a hat, a canal--Panama!"​) <​r>​*PALINDROME-3*</​r>​
 +(palindromep ([[CL:​Functions:​remove-if-not]] #'​[[CL:​Functions:​alpha-char-p]] *palindrome-3*)) <​r>​[[CL:​Constant Variables:​t|T]]</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Macros:​do|Macro DO]]**
 +  * **[[CL:​Macros:​dolist|Macro DOLIST]]**
 +  * **[[CL:​Special Operators:​tagbody|Special Operator TAGBODY]]**
 +
 +====Notes====
 +**[[CL:​Special Operators:​go]]** may be used within the body of **dotimes** to transfer control to a statement labeled by a //tag//.
 +
 +\issue{DECLS-AND-DOC}