/*
 Copyright (C) 2007 Richard Gomes

 This file is part of JQuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://jquantlib.org/

 JQuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 . The license is also available online at
 .

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
 
 JQuantLib is based on QuantLib. http://quantlib.org/
 When applicable, the original copyright notice follows this notice.
 */

package org.jquantlib.math.randomnumbers;

import org.jquantlib.methods.montecarlo.Sample;

/**
 * @author Richard Gomes
 */
public interface RandomNumberGenerator {

    /**
     * @return another random number
     */
    public Sample next() /*@ReadOnly*/;


    /**
     * Once JVM does not support unsigned fixed arithmetic, we use 64bit variables as containers for 32bit values in order to reduce
     * the complexity and performance overhead of certain fixed arithmetic operations.
     * 

     * From the user's perspective, it's easier to understand that a certain long variable contains 
     * values from 0 to 2^32 than understand that a certain int variable contains negative values that should be 
     * converted to it's two's complement and extended to a long variable before use.
     * 
     * @see Bug 4504839
     * @see Java and Unsigned Types
     * @see Two's complement
     * 
     * @return an unsigned 32bit wide number encapsulated in a 64bit container
     */
    public /*@UnsignedInt*/ long nextInt32() /*@ReadOnly*/;

    // FIXME: code review:: public boolean allowErrorEstimate(); // FIXME: should declare this method???
}