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

[Tim Peters]

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

Modified Files:
	librandom.tex 
Log Message:
Change random.seed() so that it can get at the full range of possible
internal states.  Put the old .seed() (which could only get at about
the square root of the # of possibilities) under the new name .whseed(),
for bit-level compatibility with older versions.  This occurred to me
while reviewing effbot's book (he found himself stumbling over .seed()
more than once there ...).


Index: librandom.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/librandom.tex,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -r1.21 -r1.22
*** librandom.tex	2001/01/26 10:00:39	1.21
--- librandom.tex	2001/02/01 04:59:17	1.22
***************
*** 26,30 ****
  function supplied by most C libraries, the theoretical properties
  are much the same as for a single linear congruential generator of
! large modulus.
  
  The functions in this module are not threadsafe:  if you want to call these
--- 26,31 ----
  function supplied by most C libraries, the theoretical properties
  are much the same as for a single linear congruential generator of
! large modulus.  It is not suitable for all purposes, and is completely
! unsuitable for cryptographic purposes.
  
  The functions in this module are not threadsafe:  if you want to call these
***************
*** 73,77 ****
  threads.  The generators don't share state so can be called safely in
  parallel.  So long as no thread calls its \code{g.random()} more than a
! million times (the second argument to \function{create_generators}), the
  sequences seen by each thread will not overlap.  The period of the
  underlying Wichmann-Hill generator limits how far this technique can be
--- 74,78 ----
  threads.  The generators don't share state so can be called safely in
  parallel.  So long as no thread calls its \code{g.random()} more than a
! million times (the second argument to \function{create_generators), the
  sequences seen by each thread will not overlap.  The period of the
  underlying Wichmann-Hill generator limits how far this technique can be
***************
*** 84,91 ****
  >>> g = Random(42)  # arbitrary
  >>> g.random()
! 0.24855401895528142
  >>> g.jumpahead(6953607871644L - 1) # move *back* one
  >>> g.random()
! 0.24855401895528142
  \end{verbatim}
  
--- 85,92 ----
  >>> g = Random(42)  # arbitrary
  >>> g.random()
! 0.25420336316883324
  >>> g.jumpahead(6953607871644L - 1) # move *back* one
  >>> g.random()
! 0.25420336316883324
  \end{verbatim}
  
***************
*** 95,117 ****
  \begin{funcdesc}{seed}{\optional{x}}
    Initialize the basic random number generator.
!   Optional argument \var{x} can be any hashable object,
!   and the generator is seeded from its hash code.
!   It is not guaranteed that distinct hash codes will produce distinct
!   seeds.
!   If \var{x} is omitted or \code{None},
!   the seed is derived from the current system time.
!   The seed is also set from the current system time when
!   the module is first imported.
  \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}
  
--- 96,131 ----
  \begin{funcdesc}{seed}{\optional{x}}
    Initialize the basic random number generator.
!   Optional argument \var{x} can be any hashable object.
!   If \var(x) is omitted or \code{None}, current system time is used;
!   current system time is also used to initialize the generator when the
!   module is first imported.
!   If \var(x) is not \code{None} or an int or long,
!   \code{hash(\var{x})) is used instead.
!   If \var{x} is an int or long, \var{x} is used directly.
!   Distinct values between 0 and 27814431486575L inclusive are guaranteed
!   to yield distinct internal states (this guarantee is specific to the
!   default Wichmann-Hill generator, and may not apply to subclasses
!   supplying their own basic generator).
  \end{funcdesc}
  
+ \begin{funcdesc}{whseed}{\optional{x}}
+   This is obsolete, supplied for bit-level compatibility with versions
+   of Python prior to 2.1.
+   See \function{seed} for details.  \function{whseed} does not guarantee
+   that distinct integer arguments yield distinct internal states, and can
+   yield no more than about 2**24 distinct internal states in all.
+ \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.
!   \versionadded{2.1}
! \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 generator to what it was at the time \code{setstate()} was called.
!   \versionadded{2.1}
   \end{funcdesc}
  
***************
*** 125,128 ****
--- 139,143 ----
    instances' states as far apart as you like (up to the period of the
    generator).
+   \versionadded{2.1}
   \end{funcdesc}