Project

General

Profile

Download (10.5 KB)

Bug #5410 ยป 0001-Documentation-rewrite-for-Random.patch

gjp (Gregory Parkhurst), 10/06/2011 01:47 AM

View differences:

random.c
}
/*
* call-seq: Random.new([seed]) -> prng
* Document-class: Random
*
* Random provides an interface to Ruby's pseudorandom number generator, or PRNG.
* The PRNG produces a deterministic sequence of bits which approximate true
* randomness. The sequence may be represented by integers, floats, or binary
* strings.
*
* The generator may be initialized with either a system-generated or user-supplied
* seed value by using Random.srand.
*
* The class method Random.rand provides the base functionality of Kernel.rand
* along with better handling of floating point values. These are both interfaces to
* Random::DEFAULT, the Ruby system PRNG.
*
* Creates new Mersenne Twister based pseudorandom number generator with
* seed. When the argument seed is omitted, the generator is initialized
* with Random.new_seed.
* Random.new will create a new PRNG with a state independent of Random::DEFAULT,
* allowing multiple generators with different seed values or sequence positions to
* exist simultaneously. Random objects can be marshalled, allowing sequences to be
* saved and resumed.
*
* The argument seed is used to ensure repeatable sequences of random numbers
* between different runs of the program.
* PRNGs are currently implemented as a modified Mersenne Twister with a period
* of 2**19937-1.
*/
/*
* call-seq: Random.new([seed]) -> prng
*
* prng = Random.new(1234)
* [ prng.rand, prng.rand ] #=> [0.191519450378892, 0.622108771039832]
* [ prng.integer(10), prng.integer(1000) ] #=> [4, 664]
* prng = Random.new(1234)
* [ prng.rand, prng.rand ] #=> [0.191519450378892, 0.622108771039832]
* Creates a new PRNG using _seed_ to set the initial state. If _seed_ is omitted,
* the generator is initialized with Random.new_seed.
* See Random.srand for more information on the use of seed values.
*/
static VALUE
random_init(int argc, VALUE *argv, VALUE obj)
......
/*
* call-seq: Random.new_seed -> integer
*
* Returns arbitrary value for seed.
* Returns an arbitrary seed value. This is used by Random.new
* when no seed value is specified as an argument.
*
* Random.new_seed #=> 115032730400174366788466674494640623225
*/
static VALUE
random_seed(void)
......
/*
* call-seq: prng.seed -> integer
*
* Returns the seed of the generator.
* Returns the seed value used to initialize the generator. This may be used to
* initialize another generator with the same state at a later time, causing it
* to produce the same sequence of numbers.
*
* prng1 = Random.new(1234)
* prng1.seed #=> 1234
* prng1.rand(100) #=> 47
*
* prng2 = Random.new(prng1.seed)
* prng2.rand(100) #=> 47
*/
static VALUE
random_get_seed(VALUE obj)
......
}
/*
* call-seq:
* srand(number=0) -> old_seed
* call-seq:
* srand(number=0) -> old_seed
*
* Seeds the system pseudorandom number generator, Random::DEFAULT, with
* _number_. The previous seed value is returned.
*
* Seeds the pseudorandom number generator to the value of
* <i>number</i>. If <i>number</i> is omitted,
* seeds the generator using a combination of the time, the
* process id, and a sequence number. (This is also the behavior if
* <code>Kernel::rand</code> is called without previously calling
* <code>srand</code>, but without the sequence.) By setting the seed
* to a known value, scripts can be made deterministic during testing.
* The previous seed value is returned. Also see <code>Kernel::rand</code>.
* If _number_ is omitted, seeds the generator using a source of entropy
* provided by the operating system, if available (/dev/urandom on Unix systems
* or the RSA cryptographic provider on Windows), which is then combined with
* the time, the process id, and a sequence number.
*
* srand may be used to ensure repeatable sequences of pseudorandom numbers
* between different runs of the program. By setting the seed to a known value,
* programs can be made deterministic during testing.
*
* srand 1234 #=> 268519324636777531569100071560086917274
* [ rand, rand ] #=> [0.1915194503788923, 0.6221087710398319]
* [ rand(10), rand(1000) ] #=> [4, 664]
* srand 1234 #=> 1234
* [ rand, rand ] #=> [0.1915194503788923, 0.6221087710398319]
*/
static VALUE
......
/*
* call-seq: prng.bytes(size) -> a_string
*
* Returns a random binary string. The argument size specified the length of
* the result string.
* Returns a random binary string containing _size_ bytes.
*
* random_string = Random.new.bytes(10) #=> "\xD7:R\xAB?\x83\xCE\xFAkO"
* random_string.size #=> 10
*/
static VALUE
random_bytes(VALUE obj, VALUE len)
......
/*
* call-seq:
* prng.rand -> float
* prng.rand(limit) -> number
* prng.rand -> float
* prng.rand(max) -> number
*
* When _max_ is an +Integer+, +rand+ returns a random integer greater than
* or equal to zero and less than _max_. Unlike Kernel.rand, when _max_
* is a negative integer or zero, +rand+ raises an ArgumentError.
*
* When the argument is an +Integer+ or a +Bignum+, it returns a
* random integer greater than or equal to zero and less than the
* argument. Unlike Random.rand, when the argument is a negative
* integer or zero, it raises an ArgumentError.
* prng = Random.new
* prng.rand(100) #=> 42
*
* When the argument is a +Float+, it returns a random floating point
* number between 0.0 and _max_, including 0.0 and excluding _max_.
* When _max_ is a +Float+, +rand+ returns a random floating point number
* between 0.0 and _max_, including 0.0 and excluding _max_.
*
* When the argument _limit_ is a +Range+, it returns a random
* number where range.member?(number) == true.
* prng.rand(5..9) #=> one of [5, 6, 7, 8, 9]
* prng.rand(5...9) #=> one of [5, 6, 7, 8]
* prng.rand(5.0..9.0) #=> between 5.0 and 9.0, including 9.0
* prng.rand(5.0...9.0) #=> between 5.0 and 9.0, excluding 9.0
* prng.rand(1.5) #=> 1.4600282860034115
*
* +begin+/+end+ of the range have to have subtract and add methods.
* When _max_ is a +Range+, +rand+ returns a random number where
* range.member?(number) == true.
*
* Otherwise, it raises an ArgumentError.
* prng.rand(5..9) #=> one of [5, 6, 7, 8, 9]
* prng.rand(5...9) #=> one of [5, 6, 7, 8]
* prng.rand(5.0..9.0) #=> between 5.0 and 9.0, including 9.0
* prng.rand(5.0...9.0) #=> between 5.0 and 9.0, excluding 9.0
*
* Both the +begin+ and +end+ of the range must have +subtract+ and +add+ methods,
* or rand will raise an ArgumentError.
*/
static VALUE
random_rand(int argc, VALUE *argv, VALUE obj)
......
* call-seq:
* prng1 == prng2 -> true or false
*
* Returns true if the generators' states equal.
* Returns true if the two generators have the same internal state, otherwise
* false. Equivalent generators will return the same sequence of pseudorandom
* numbers. Two generators will generally have the same state only if they were
* initialized with the same seed
*
* Random.new == Random.new #=> false
* Random.new(1234) == Random.new(1234) #=> true
*
* and have the same invocation history.
*
* prng1 = Random.new(1234)
* prng2 = Random.new(1234)
* prng1 == prng2 #=> true
*
* prng1.rand #=> 0.1915194503788923
* prng1 == prng2 #=> false
*
* prng2.rand #=> 0.1915194503788923
* prng1 == prng2 #=> true
*/
static VALUE
random_equal(VALUE self, VALUE other)
......
* call-seq:
* rand(max=0) -> number
*
* If called without an argument, or if _max_.to_i.abs == 0, +rand+ returns
* a pseudorandom floating point number between 0.0 and 1.0, including 0.0 and
* excluding 1.0.
*
* rand #=> 0.2725926052826416
*
* If <i>max</i> is +Range+, returns a pseudorandom number where
* range.member(number) == true.
* When _max_.abs is greater than or equal to 1, +rand+ returns a pseudorandom
* integer greater than or equal to 0 and less than _max_.to_i.abs.
*
* Or else converts _max_ to an integer using max1 =
* max<code>.to_i.abs</code>.
* rand(100) #=> 12
*
* Then if _max_ is +nil+ the result is zero, returns a pseudorandom floating
* point number greater than or equal to 0.0 and less than 1.0.
* Negative or floating point values for _max_ are allowed, but may give
* surprising results.
*
* Otherwise, returns a pseudorandom integer greater than or equal to zero and
* less than max1.
* rand(-100) #=> 87
* rand(-0.5) #=> 0.8130921818028143
* rand(1.9) # equivalent to rand(1), which is always 0
*
* <code>Kernel::srand</code> may be used to ensure repeatable sequences of
* random numbers between different runs of the program. Ruby currently uses
* a modified Mersenne Twister with a period of 2**19937-1.
* Kernel.srand may be used to ensure that sequences of random numbers are
* reproducable between different runs of a program.
*
* srand 1234 #=> 0
* [ rand, rand ] #=> [0.191519450163469, 0.49766366626136]
* [ rand(10), rand(1000) ] #=> [6, 817]
* srand 1234 #=> 1234
* [ rand, rand ] #=> [0.191519450163469, 0.49766366626136]
* See also Random.rand.
*/
static VALUE
......
}
/*
* call-seq:
* Random.rand -> float
* Random.rand(limit) -> number
*
* Alias of _Random::DEFAULT.rand_.
* call-seq:
* Random.rand -> float
* Random.rand(max) -> number
*
* Alias of Random::DEFAULT.rand.
*/
static VALUE
    (1-1/1)