[Python-checkins] CVS: python/dist/src/Doc/lib librandom.tex,1.18,1.19

[Tim Peters]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv25276/python/dist/src/Doc/lib

Modified Files:
	librandom.tex 
Log Message:
Reworked random.py so that it no longer depends on, and offers all the
functionality of, whrandom.py.  Also closes all the "XXX" todos in
random.py.  New frequently-requested functions/methods getstate() and
setstate().  All exported functions are now bound methods of a hidden
instance.  Killed all unintended exports.  Updated the docs.
FRED:  The more I fiddle the docs, the less I understand the exact
intended use of the \var, \code, \method tags.  Please review critically.
GUIDO:  See email.  I updated NEWS as if whrandom were deprecated; I
think it should be.


Index: librandom.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/librandom.tex,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -r1.18 -r1.19
*** librandom.tex	2001/01/25 00:39:16	1.18
--- librandom.tex	2001/01/25 03:36:25	1.19
***************
*** 33,37 ****
--- 33,49 ----
  from different threads may see the same return values.
  
+ The functions supplied by this module are actually bound methods of a
+ hidden instance of the \var{random.Random} class.  You can instantiate
+ your own instances of \var{Random} to get generators that don't share state.
+ This may be especially useful for multi-threaded programs, although there's
+ no simple way to seed the distinct generators to ensure that the generated
+ sequences won't overlap.  Class \var{Random} can also be subclassed if you
+ want to use a different basic generator of your own devising:  in that
+ case, override the \method{random()}, \method{seed()}, \method{getstate()}
+ and \method{setstate()} methods.
  
+ 
+ Bookkeeping functions:
+ 
  \begin{funcdesc}{seed}{\optional{x}}
    Initialize the basic random number generator.
***************
*** 46,58 ****
  \end{funcdesc}
  
! \begin{funcdesc}{choice}{seq}
!   Return a random element from the non-empty sequence \var{seq}.
! \end{funcdesc}
  
! \begin{funcdesc}{randint}{a, b}
!   \deprecated{2.0}{Use \function{randrange()} instead.}
!   Return a random integer \var{N} such that
!   \code{\var{a} <= \var{N} <= \var{b}}.
! \end{funcdesc}
  
  \begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
--- 58,74 ----
  \end{funcdesc}
  
! \begin{funcdesc}{getstate}{}
!   Return an object capturing the current internal state of the generator.
!   This object can be passed to \code{setstate()} to restore the state.
!  \end{funcdesc}
! 
! \begin{funcdesc}{setstate}{state}
!   \var{state} should have been obtained from a previous call to
!   \code{getstate()}, and \code{setstate()} restores the internal state
!   of the generate to what it was at the time \code{setstate()} was called.
!  \end{funcdesc}
  
! 
! Functions for integers:
  
  \begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
***************
*** 64,67 ****
--- 80,114 ----
  \end{funcdesc}
  
+ \begin{funcdesc}{randint}{a, b}
+   \deprecated{2.0}{Use \function{randrange()} instead.}
+   Return a random integer \var{N} such that
+   \code{\var{a} <= \var{N} <= \var{b}}.
+ \end{funcdesc}
+ 
+ 
+ Functions for sequences:
+ 
+ \begin{funcdesc}{choice}{seq}
+   Return a random element from the non-empty sequence \var{seq}.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{shuffle}{x\optional{, random}}
+   Shuffle the sequence \var{x} in place.
+   The optional argument \var{random} is a 0-argument function
+   returning a random float in [0.0, 1.0); by default, this is the
+   function \function{random()}.
+ 
+   Note that for even rather small \code{len(\var{x})}, the total
+   number of permutations of \var{x} is larger than the period of most
+   random number generators; this implies that most permutations of a
+   long sequence can never be generated.
+ \end{funcdesc}
+ 
+ 
+ The following functions generate specific real-valued distributions.
+ Function parameters are named after the corresponding variables in the
+ distribution's equation, as used in common mathematical practice; most of
+ these equations can be found in any statistics text.
+ 
  \begin{funcdesc}{random}{}
    Return the next random floating point number in the range [0.0, 1.0).
***************
*** 73,84 ****
  \end{funcdesc}
  
- 
- The following functions are defined to support specific distributions,
- and all return real values.  Function parameters are named after the
- corresponding variables in the distribution's equation, as used in
- common mathematical practice; most of these equations can be found in
- any statistics text.
- 
- 
  \begin{funcdesc}{betavariate}{alpha, beta}
    Beta distribution.  Conditions on the parameters are
--- 120,123 ----
***************
*** 143,161 ****
  \end{funcdesc}
  
- 
- This function does not represent a specific distribution, but
- implements a standard useful algorithm:
- 
- \begin{funcdesc}{shuffle}{x\optional{, random}}
-   Shuffle the sequence \var{x} in place.
-   The optional argument \var{random} is a 0-argument function
-   returning a random float in [0.0, 1.0); by default, this is the
-   function \function{random()}.
- 
-   Note that for even rather small \code{len(\var{x})}, the total
-   number of permutations of \var{x} is larger than the period of most
-   random number generators; this implies that most permutations of a
-   long sequence can never be generated.
- \end{funcdesc}
  
  \begin{seealso}
--- 182,185 ----