Merge pull request #19 from schmouk/augment-operator-call

#16-Augment operator '()'
This is part #2/2 of the delivery for Release 1.2.0.

Author: schmouk

PyRandLib/README.md

@@ -123,6 +123,44 @@ Note 3:  a Cython version of PyRandLib might be delivered in a next release.
 Up today, no date is planned for this.
 
 
+## New in release 1.2
+This is available starting at version 1.2 of PyRandLib.  The  call  operator
+(i.e., '()')  gets  a  new signature which is still backward compatible with
+previous versions of this library. Its new use is described here below.  The
+implementation  code  can  be  found  in  class `BaseRandom`,  in  module
+`baserandom.py`.
+
+    from fastrand63 import FastRand63
+    
+    rand = FastRand63()
+    
+    # prints a float random value ranging in [0.0, 1.0]
+    print( rand() )
+    
+    # prints an integer random value ranging in [0, 5]
+    print( rand(5) )
+    
+    # prints a float random value ranging in [0.0, 20.0]
+    print( rand(20.0) 
+    
+    # prints a list of 10 integer values each ranging in [0, 5]
+    print( rand(5, 10) )
+    
+    # prints a list of 10 float values each ranging in [0.0, 1.0]
+    print( rand(times=10) )
+    
+    # prints a list of 4 random values ranging respectively in
+    #    [0, 5], [0.0, 50.0], [0.0, 500.0] and [0, 5000]
+    print( rand(5, 50.0, 500.0, 5000) )
+    						
+    # a more complex call which prints something like:
+    #   [ [3, 11.64307079016269, 127.65395855782158, 4206, [2, 0, 1, 4, 4, 1, 2, 0]],
+    #     [2, 34.22526698212995, 242.54183578253426, 2204, [5, 3, 5, 4, 2, 0, 1, 3]], 
+    #     [0, 17.77303802057933, 417.70662295909983,  559, [4, 1, 5, 0, 5, 3, 0, 5]] ] 
+    print( rand( (5, 50.0, 500.0, 5000, [5]*8), times=3 ) )
+		   
+
+    
 ## Architecture overview
 Each of the implemented PRG is described in an independent module. The  name
 of the module is directly related to the name of the related class.
@@ -136,7 +174,7 @@ aims at providing simple common behavior for all PRG classes of the library,
 the  most  noticeable  one  being the 'callable' nature of every implemented 
 PRGs. For instance:
 
-    rand = UBaseRandom()
+    rand = BaseRandom()
     print( rand() )    # prints a uniform pseudo-random value within [0.0, 1.0)
     print( rand(a) )   # prints a uniform pseudo-random value within [0.0, a)
     print( rand(a,b) ) # prints a uniform pseudo-random value within [a, b)

PyRandLib/baserandom.py

@@ -24,9 +24,9 @@
 
 #=============================================================================
 from random import Random
-from typing import Any
+from typing import Any, List, Tuple, Union
 
-from .types import Numeric, SeedStateType
+from .types import Numerical, SeedStateType, StateType
 
 
 #=============================================================================
@@ -243,12 +243,39 @@ def seed(self, _seed: SeedStateType = None) -> None:
 
 
     #------------------------------------------------------------------------=
-    def __call__(self, _max: Numeric = 1.0) -> float:
+    def __call__(self, _max : Union[Numerical,
+                                    Tuple[Numerical],
+                                    List[Numerical]] = 1.0,
+                       times: int                    = 1   ) -> Numerical:
         """This class's instances are callable.
         
-        The returned value is uniformly contained 
-        within the interval [0.0 : _max].
+        The returned value is uniformly contained within the 
+        interval [0.0 : _max].  When times is set, a list of
+        iterated pseudo-random values is  returned.  'times'
+        must  be an integer.  If less than 1 it is forced to
+        be 1.
+        '_max' may be a list or a tuple of values,  in which
+        case  a  list  of  related  pseudo-random  values is
+        returned with entries of the same type than the same 
+        indexed entry in '_max'.
         """
-        return self.uniform( 0.0, _max )
+        assert isinstance( times, int )
+        if times < 1:
+            times =  1
+         
+        if isinstance( _max, int ):
+            ret = [ self.randint(0, _max) for _ in range(times) ]
+        elif isinstance( _max, float ):
+            ret = [ self.uniform( 0.0, _max ) for _ in range(times) ]
+        else:
+            try:
+                if times == 1:
+                    ret = [ self(m,1) for m in _max] 
+                else:
+                    ret = [ [self(m,1) for m in _max] for _ in range(times) ]
+            except:
+                ret = [ self.__call__(times=1) ]
+        
+        return ret[0] if len(ret) == 1 else ret
 
 #=====   end of module   baserandom.py   =====================================

PyRandLib/fastrand32.py

@@ -26,7 +26,7 @@
 import time
 
 from .baselcg import BaseLCG
-from .types   import Numeric
+from .types   import Numerical
 
 
 #=============================================================================
@@ -93,10 +93,10 @@ class FastRand32( BaseLCG ):
     """
 
     #------------------------------------------------------------------------=
-    def __init__(self, _seed: Numeric = None) -> None:
+    def __init__(self, _seed: Numerical = None) -> None:
         """Constructor.
         
-        Should _seed be None or not a numeric then the local 
+        Should _seed be None or not a numerical then the local 
         time is used (with its shuffled value) as a seed.
         """
         super().__init__( _seed ) # this call creates attribute self._value and sets it
@@ -113,7 +113,7 @@ def random(self) -> float:
 
 
     #------------------------------------------------------------------------=
-    def setstate(self, _state: Numeric) -> None:
+    def setstate(self, _state: Numerical) -> None:
         """Restores the internal state of the generator.
         
         _state should have been obtained from a previous call 

PyRandLib/fastrand63.py

@@ -26,7 +26,7 @@
 import time
 
 from .baselcg import BaseLCG
-from .types   import Numeric
+from .types   import Numerical
 
 
 #=============================================================================
@@ -103,7 +103,7 @@ def random(self) -> float:
 
 
     #------------------------------------------------------------------------=
-    def setstate(self, _state: Numeric) -> None:
+    def setstate(self, _state: Numerical) -> None:
         """Restores the internal state of the generator.
         
         _state should have been obtained from a previous call 

PyRandLib/types.py

@@ -25,9 +25,9 @@
 #=============================================================================
 from typing import List, Tuple, Union
 
-Numeric       = Union[ int, float ]
-StateType     = Union[ Tuple[Numeric], List[Numeric], Tuple[List[Numeric], int] ]
-SeedStateType = Union[ Numeric, StateType ]
+Numerical     = Union[ int, float ]
+StateType     = Union[ Tuple[Numerical], List[Numerical], Tuple[List[Numerical], int] ]
+SeedStateType = Union[ Numerical, StateType ]
 
 
 #=====   end of   PyRandLib.types   =====#