1 /* 2 * Copyright 2023 Code Intelligence GmbH 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.code_intelligence.jazzer.mutation.api; 18 19 import com.google.errorprone.annotations.DoNotMock; 20 import java.util.List; 21 import java.util.function.Supplier; 22 23 @DoNotMock("Use TestSupport#mockPseudoRandom instead") 24 public interface PseudoRandom { 25 /** 26 * @return a uniformly random {@code boolean} 27 */ choice()28 boolean choice(); 29 30 /** 31 * @return a {@code boolean} that is {@code true} with probability {@code 1/inverseFrequencyTrue} 32 */ trueInOneOutOf(int inverseFrequencyTrue)33 boolean trueInOneOutOf(int inverseFrequencyTrue); 34 35 /** 36 * @throws IllegalArgumentException if {@code array.length == 0} 37 * @return an element from the given array at uniformly random index 38 */ pickIn(T[] array)39 <T> T pickIn(T[] array); 40 41 /** 42 * @throws IllegalArgumentException if {@code array.length == 0} 43 * @return an element from the given List at uniformly random index 44 */ pickIn(List<T> array)45 <T> T pickIn(List<T> array); 46 47 /** 48 * @throws IllegalArgumentException if {@code array.length == 0} 49 * @return a uniformly random index valid for the given array 50 */ indexIn(T[] array)51 <T> int indexIn(T[] array); 52 53 /** 54 * @throws IllegalArgumentException if {@code list.size() == 0} 55 * @return a uniformly random index valid for the given list 56 */ indexIn(List<T> list)57 <T> int indexIn(List<T> list); 58 59 /** 60 * Prefer {@link #indexIn(Object[])} and {@link #indexIn(List)}. 61 * 62 * @throws IllegalArgumentException if {@code range < 1} 63 * @return a uniformly random index in the range {@code [0, range-1]} 64 */ indexIn(int range)65 int indexIn(int range); 66 67 /** 68 * @throws IllegalArgumentException if {@code array.length < 2} 69 * @return a uniformly random index valid for the given array and different from 70 * {@code currentIndex} 71 */ otherIndexIn(T[] array, int currentIndex)72 <T> int otherIndexIn(T[] array, int currentIndex); 73 74 /** 75 * @throws IllegalArgumentException if {@code length < 2} 76 * @return a uniformly random {@code int} in the closed range {@code [0, length)} that is 77 * different from {@code currentIndex} 78 */ otherIndexIn(int range, int currentIndex)79 int otherIndexIn(int range, int currentIndex); 80 81 /** 82 * @return a uniformly random {@code int} in the closed range 83 * {@code [lowerInclusive, upperInclusive]}. 84 */ closedRange(int lowerInclusive, int upperInclusive)85 int closedRange(int lowerInclusive, int upperInclusive); 86 87 /** 88 * @return a uniformly random {@code long} in the closed range 89 * {@code [lowerInclusive, upperInclusive]}. 90 */ closedRange(long lowerInclusive, long upperInclusive)91 long closedRange(long lowerInclusive, long upperInclusive); 92 93 /** 94 * @return a uniformly random {@code float} in the closed range 95 * {@code [lowerInclusive, upperInclusive]}. 96 */ closedRange(float lowerInclusive, float upperInclusive)97 float closedRange(float lowerInclusive, float upperInclusive); 98 99 /** 100 * @return a uniformly random {@code double} in the closed range 101 * {@code [lowerInclusive, upperInclusive]}. 102 */ closedRange(double lowerInclusive, double upperInclusive)103 double closedRange(double lowerInclusive, double upperInclusive); 104 105 /** 106 * @return a random value in the closed range [0, upperInclusive] that is heavily biased towards 107 * being small 108 */ closedRangeBiasedTowardsSmall(int upperInclusive)109 int closedRangeBiasedTowardsSmall(int upperInclusive); 110 111 /** 112 * @return a random value in the closed range [lowerInclusive, upperInclusive] that is heavily 113 * biased towards being small 114 */ closedRangeBiasedTowardsSmall(int lowerInclusive, int upperInclusive)115 int closedRangeBiasedTowardsSmall(int lowerInclusive, int upperInclusive); 116 117 /** 118 * Fills the given array with random bytes. 119 */ bytes(byte[] bytes)120 void bytes(byte[] bytes); 121 122 /** 123 * Use the given supplier to produce a value with probability {@code 1/inverseSupplierFrequency}, 124 * otherwise randomly return one of the given values. 125 * 126 * @return value produced by the supplier or one of the given values 127 */ pickValue(T value, T otherValue, Supplier<T> supplier, int inverseSupplierFrequency)128 <T> T pickValue(T value, T otherValue, Supplier<T> supplier, int inverseSupplierFrequency); 129 130 /** 131 * Returns a pseudorandom {@code long} value. 132 * 133 * @return a pseudorandom {@code long} value 134 */ nextLong()135 long nextLong(); 136 } 137