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 *      https://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.text;
018
019import java.util.function.IntUnaryOperator;
020
021/**
022 * TextRandomProvider implementations are used by {@link RandomStringGenerator}
023 * as a source of randomness.  It is highly recommended that the
024 * <a href="https://commons.apache.org/proper/commons-rng/">Apache Commons RNG</a>
025 * library be used to provide the random number generation.
026 *
027 * <p>
028 * {@code TextRandomProvider} is a functional interface and need not be explicitly implemented.
029 * </p>
030 * <p>
031 * For example:
032 * </p>
033 * <pre>
034 * {@code
035 * UniformRandomProvider rng = RandomSource.create(...);
036 * RandomStringGenerator gen = RandomStringGenerator.builder()
037 *     .usingRandom(rng::nextInt)
038 *     // additional builder calls as needed
039 *     .build();
040 * }
041 * </pre>
042 *
043 * @since 1.1
044 */
045public interface TextRandomProvider extends IntUnaryOperator {
046
047    /**
048     * Generates an int value between 0 (inclusive) and the specified value (exclusive).
049     *
050     * @param max Bound on the random number to be returned. Must be positive.
051     * @return a random int value between 0 (inclusive) and max (exclusive).
052     * @since 1.14.0
053     */
054    @Override
055    default int applyAsInt(final int max) {
056        return nextInt(max);
057    }
058
059    /**
060     * Generates an int value between 0 (inclusive) and the specified value (exclusive).
061     *
062     * @param max Bound on the random number to be returned. Must be positive.
063     * @return a random int value between 0 (inclusive) and max (exclusive).
064     * @deprecated Use {@link #applyAsInt(int)}.
065     */
066    @Deprecated
067    int nextInt(int max);
068}