View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.rng;
18  
19  /**
20   * Applies to generators of random number sequences that follow a uniform
21   * distribution.
22   *
23   * @since 1.0
24   */
25  public interface UniformRandomProvider {
26      /**
27       * Generates {@code byte} values and places them into a user-supplied array.
28       * <p>
29       * The number of random bytes produced is equal to the length of the
30       * the byte array.
31       * </p>
32       *
33       * @param bytes Byte array in which to put the random bytes.
34       * Cannot be {@code null}.
35       */
36      void nextBytes(byte[] bytes);
37  
38      /**
39       * Generates {@code byte} values and places them into a user-supplied array.
40       *
41       * <p>
42       * The array is filled with bytes extracted from random integers.
43       * This implies that the number of random bytes generated may be larger than
44       * the length of the byte array.
45       * </p>
46       *
47       * @param bytes Array in which to put the generated bytes.
48       * Cannot be {@code null}.
49       * @param start Index at which to start inserting the generated bytes.
50       * @param len Number of bytes to insert.
51       * @throws IndexOutOfBoundsException if {@code start < 0} or
52       * {@code start >= bytes.length}.
53       * @throws IndexOutOfBoundsException if {@code len < 0} or
54       * {@code len > bytes.length - start}.
55       */
56      void nextBytes(byte[] bytes,
57                     int start,
58                     int len);
59  
60      /**
61       * Generates an {@code int} value.
62       *
63       * @return the next random value.
64       */
65      int nextInt();
66  
67      /**
68       * Generates an {@code int} value between 0 (inclusive) and the
69       * specified value (exclusive).
70       *
71       * @param n Bound on the random number to be returned.  Must be positive.
72       * @return a random {@code int} value between 0 (inclusive) and {@code n}
73       * (exclusive).
74       * @throws IllegalArgumentException if {@code n} is negative.
75       */
76      int nextInt(int n);
77  
78      /**
79       * Generates a {@code long} value.
80       *
81       * @return the next random value.
82       */
83      long nextLong();
84  
85      /**
86       * Generates a {@code long} value between 0 (inclusive) and the specified
87       * value (exclusive).
88       *
89       * @param n Bound on the random number to be returned.  Must be positive.
90       * @return a random {@code long} value between 0 (inclusive) and {@code n}
91       * (exclusive).
92       * @throws IllegalArgumentException if {@code n} is negative.
93       */
94      long nextLong(long n);
95  
96      /**
97       * Generates a {@code boolean} value.
98       *
99       * @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 }