From d8fed49e795ddb08d1aa519d11c06f6367f6e5a0 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Tue, 14 May 2013 20:00:52 -0700 Subject: * eval.c (eval_init): State argument in random-fixnum should be optional. * txr.1: Documented random functions as well as range and range* --- ChangeLog | 7 +++++ eval.c | 2 +- txr.1 | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 109 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index 56010ae1..598bdc46 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2013-05-14 Kaz Kylheku + + * eval.c (eval_init): State argument in random-fixnum should be + optional. + + * txr.1: Documented random functions as well as range and range* + 2013-05-14 Kaz Kylheku * RELNOTES: Updated in preparation for release. diff --git a/eval.c b/eval.c index 8337fed0..81c7db88 100644 --- a/eval.c +++ b/eval.c @@ -2446,7 +2446,7 @@ void eval_init(void) reg_var(intern(lit("*random-state*"), user_package), &random_state); reg_fun(intern(lit("make-random-state"), user_package), func_n1(make_random_state)); reg_fun(intern(lit("random-state-p"), user_package), func_n1(random_state_p)); - reg_fun(intern(lit("random-fixnum"), user_package), func_n1(random_fixnum)); + reg_fun(intern(lit("random-fixnum"), user_package), func_n1o(random_fixnum, 1)); reg_fun(intern(lit("random"), user_package), func_n2(random)); reg_fun(intern(lit("rand"), user_package), func_n2o(rnd, 1)); diff --git a/txr.1 b/txr.1 index acb8fc45..5c90688b 100644 --- a/txr.1 +++ b/txr.1 @@ -10145,14 +10145,114 @@ returns nil. .SS Variable *random-state* +The *random-state* variable holds an object which encapsulates the state +of a pseudo-random number generator. This variable is the default argument for +the random-fixnum and random functions, so that programs can be written +which are not concerned about the management of random state. + +However, programs can create and manage random states, making it possible to +obtain repeatable sequences of pseudo-random numbers which do not interfere +owith each other. For instance objects or modules in a program can have their +own independent streams of random numbers which are repeatable, independently +of other modules making calls to the random number functions. + +When TXR starts up, the *random-state* variable is initialized with +a newly created random state object, which is produced as if by +the call (make-random-state 42). + .SS Function make-random-state +.TP +Syntax: + + (make-random-state ) + +.TP +Description: + +The make-random-state function creates and returns a new random state, +an object of the same kind as what is stored in the *random-state* variable. + +The seed must be an integer value. + +Note that the sign of the value is ignored, so that negative seed +values are equivalent to their additive inverses. + .SS Function random-state-p -.SS Functions random-fixnum and random +.TP +Syntax: + + (random-state-p ) + +.TP +Description: + +The random-state-p function returns t if is a random state, otherwise it +returns nil. + +.SS Functions random-fixnum, random and rand + +.TP +Syntax: + + (random-fixnum []) + (random ) + (rand []) + +.TP +Description: + +All three functions produce pseudo-random numbers, which are positive integers. + +The numbers are obtained from a WELLS 512 pseudo-random number generator, whose +state is stored in the random state object. + +The random-fixnum function produces a random fixnum integer: a reduced range +integer which fits into a value that does not have to be heap-allocated. + +The random and rand functions produce a value in the range [0, modulus). They +differ only in the order of arguments. In the rand function, the random state +object is the second argument and is optional. If it is omitted, the global +*random-state* object is used. .SS Functions range and range* +.TP +Syntax: + + (range [ [ [ ] ] ]) + (range* [ [ [ ] ] ]) + +.TP +Description: + +The range and range* functions generate a lazy sequence of integers, with a +fixed step between successive values. + +The difference between range and range* is that range* excludes the endpoint. +For instance (range 0 3) generates the list (0 1 2 3), whereas (range* 0 3) +generates (0 1 2). + +All arguments are optional. If the argument is omitted, then it defaults +to 1: each value in the sequence is greater than the previous one by 1. +Positive or negative step sizes are allowed. There is no check for a step size +of zero, or for a step direction which cannot meet the endpoint. + +The argument specifies the endpoint value, which, if it occurs in the +sequence, is excluded from it by the range* function, but included by the range +function. If is missing, then there is no endpoint, and the sequence +which is generated is infinite, regardless of . + +If is omitted, then the sequence begins at zero, otherwise must +be an integer which specifies the initial value. + +The sequence stops if it reaches the endpoint value (which is included in the +case of range, and excluded in the case of range*). However, a sequence with a +stepsize greater than 1 or less than -1 might step over the endpoint value, and +therefore never attain it. In this situation, the sequence also stops, and the +excess value which surpasses the endpoint is excluded from the sequence. + .SH TIME .SS Functions time and time-usec -- cgit v1.2.3