001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.rng;
018
019/**
020 * Applies to generators of random number sequences that follow a uniform
021 * distribution.
022 *
023 * @since 1.0
024 */
025public interface UniformRandomProvider {
026    /**
027     * Generates {@code byte} values and places them into a user-supplied array.
028     * <p>
029     * The number of random bytes produced is equal to the length of the
030     * the byte array.
031     * </p>
032     *
033     * @param bytes Byte array in which to put the random bytes.
034     * Cannot be {@code null}.
035     */
036    void nextBytes(byte[] bytes);
037
038    /**
039     * Generates {@code byte} values and places them into a user-supplied array.
040     *
041     * <p>
042     * The array is filled with bytes extracted from random integers.
043     * This implies that the number of random bytes generated may be larger than
044     * the length of the byte array.
045     * </p>
046     *
047     * @param bytes Array in which to put the generated bytes.
048     * Cannot be {@code null}.
049     * @param start Index at which to start inserting the generated bytes.
050     * @param len Number of bytes to insert.
051     * @throws IndexOutOfBoundsException if {@code start < 0} or
052     * {@code start >= bytes.length}.
053     * @throws IndexOutOfBoundsException if {@code len < 0} or
054     * {@code len > bytes.length - start}.
055     */
056    void nextBytes(byte[] bytes,
057                   int start,
058                   int len);
059
060    /**
061     * Generates an {@code int} value.
062     *
063     * @return the next random value.
064     */
065    int nextInt();
066
067    /**
068     * Generates an {@code int} value between 0 (inclusive) and the
069     * specified value (exclusive).
070     *
071     * @param n Bound on the random number to be returned.  Must be positive.
072     * @return a random {@code int} value between 0 (inclusive) and {@code n}
073     * (exclusive).
074     * @throws IllegalArgumentException if {@code n} is negative.
075     */
076    int nextInt(int n);
077
078    /**
079     * Generates a {@code long} value.
080     *
081     * @return the next random value.
082     */
083    long nextLong();
084
085    /**
086     * Generates a {@code long} value between 0 (inclusive) and the specified
087     * value (exclusive).
088     *
089     * @param n Bound on the random number to be returned.  Must be positive.
090     * @return a random {@code long} value between 0 (inclusive) and {@code n}
091     * (exclusive).
092     * @throws IllegalArgumentException if {@code n} is negative.
093     */
094    long nextLong(long n);
095
096    /**
097     * Generates a {@code boolean} value.
098     *
099     * @return the next random value.
100     */
101    boolean nextBoolean();
102
103    /**
104     * Generates a {@code float} value between 0 and 1.
105     *
106     * @return the next random value between 0 and 1.
107     */
108    float nextFloat();
109
110    /**
111     * Generates a {@code double} value between 0 and 1.
112     *
113     * @return the next random value between 0 and 1.
114     */
115    double nextDouble();
116}