    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 */
    017
    018package org.apache.commons.lang3;
    019
    020import java.util.Arrays;
    021import java.util.function.IntFunction;
    022
    023import org.apache.commons.lang3.function.FailableIntFunction;
    024
    025/**
    026 * Fills and returns arrays in the fluent style.
    027 *
    028 * @since 3.14.0
    029 */
    030public final class ArrayFill {
    031
    032    /**
    033     * Fills and returns the given array, assigning the given {@code boolean} value to each element of the array.
    034     *
    035     * @param a   the array to be filled (may be null).
    036     * @param val the value to be stored in all elements of the array.
    037     * @return the given array.
    038     * @see Arrays#fill(boolean[],boolean)
    039     * @since 3.18.0
    040     */
    041    public static boolean[] fill(final boolean[] a, final boolean val) {
    042        if (a != null) {
    043            Arrays.fill(a, val);
    044        }
    045        return a;
    046    }
    047
    048    /**
    049     * Fills and returns the given array, assigning the given {@code byte} value to each element of the array.
    050     *
    051     * @param a   the array to be filled (may be null).
    052     * @param val the value to be stored in all elements of the array.
    053     * @return the given array.
    054     * @see Arrays#fill(byte[],byte)
    055     */
    056    public static byte[] fill(final byte[] a, final byte val) {
    057        if (a != null) {
    058            Arrays.fill(a, val);
    059        }
    060        return a;
    061    }
    062
    063    /**
    064     * Fills and returns the given array, assigning the given {@code char} value to each element of the array.
    065     *
    066     * @param a   the array to be filled (may be null).
    067     * @param val the value to be stored in all elements of the array.
    068     * @return the given array.
    069     * @see Arrays#fill(char[],char)
    070     */
    071    public static char[] fill(final char[] a, final char val) {
    072        if (a != null) {
    073            Arrays.fill(a, val);
    074        }
    075        return a;
    076    }
    077
    078    /**
    079     * Fills and returns the given array, assigning the given {@code double} value to each element of the array.
    080     *
    081     * @param a   the array to be filled (may be null).
    082     * @param val the value to be stored in all elements of the array.
    083     * @return the given array.
    084     * @see Arrays#fill(double[],double)
    085     */
    086    public static double[] fill(final double[] a, final double val) {
    087        if (a != null) {
    088            Arrays.fill(a, val);
    089        }
    090        return a;
    091    }
    092
    093    /**
    094     * Fills and returns the given array, assigning the given {@code float} value to each element of the array.
    095     *
    096     * @param a   the array to be filled (may be null).
    097     * @param val the value to be stored in all elements of the array.
    098     * @return the given array.
    099     * @see Arrays#fill(float[],float)
    100     */
    101    public static float[] fill(final float[] a, final float val) {
    102        if (a != null) {
    103            Arrays.fill(a, val);
    104        }
    105        return a;
    106    }
    107
    108    /**
    109     * Fills and returns the given array, assigning the given {@code int} value to each element of the array.
    110     *
    111     * @param a   the array to be filled (may be null).
    112     * @param val the value to be stored in all elements of the array.
    113     * @return the given array.
    114     * @see Arrays#fill(int[],int)
    115     */
    116    public static int[] fill(final int[] a, final int val) {
    117        if (a != null) {
    118            Arrays.fill(a, val);
    119        }
    120        return a;
    121    }
    122
    123    /**
    124     * Fills and returns the given array, assigning the given {@code long} value to each element of the array.
    125     *
    126     * @param a   the array to be filled (may be null).
    127     * @param val the value to be stored in all elements of the array.
    128     * @return the given array.
    129     * @see Arrays#fill(long[],long)
    130     */
    131    public static long[] fill(final long[] a, final long val) {
    132        if (a != null) {
    133            Arrays.fill(a, val);
    134        }
    135        return a;
    136    }
    137
    138    /**
    139     * Fills and returns the given array, assigning the given {@code short} value to each element of the array.
    140     *
    141     * @param a   the array to be filled (may be null).
    142     * @param val the value to be stored in all elements of the array.
    143     * @return the given array.
    144     * @see Arrays#fill(short[],short)
    145     */
    146    public static short[] fill(final short[] a, final short val) {
    147        if (a != null) {
    148            Arrays.fill(a, val);
    149        }
    150        return a;
    151    }
    152
    153    /**
    154     * Fills and returns the given array, using the provided generator supplier to compute each element. Like
    155     * {@link Arrays#setAll(Object[], IntFunction)} with exception support.
    156     * <p>
    157     * If the generator supplier throws an exception, it is relayed to the caller and the array is left in an indeterminate
    158     * state.
    159     * </p>
    160     *
    161     * @param <T> type of elements of the array.
    162     * @param array array to be initialized.
    163     * @param generator a function accepting an index and producing the desired value for that position.
    164     * @return the input array
    165     * @param <E> The kind of thrown exception or error.
    166     * @throws E Thrown by the given {@code generator}.
    167     * @see Arrays#setAll(Object[], IntFunction)
    168     * @since 3.18.0
    169     */
    170    public static <T, E extends Throwable> T[] fill(final T[] array, final FailableIntFunction<? extends T, E> generator) throws E {
    171        if (array != null && generator != null) {
    172            for (int i = 0; i < array.length; i++) {
    173                array[i] = generator.apply(i);
    174            }
    175        }
    176        return array;
    177    }
    178
    179    /**
    180     * Fills and returns the given array, assigning the given {@code T} value to each element of the array.
    181     *
    182     * @param <T> the array type.
    183     * @param a   the array to be filled (may be null).
    184     * @param val the value to be stored in all elements of the array.
    185     * @return the given array.
    186     * @see Arrays#fill(Object[],Object)
    187     */
    188    public static <T> T[] fill(final T[] a, final T val) {
    189        if (a != null) {
    190            Arrays.fill(a, val);
    191        }
    192        return a;
    193    }
    194
    195    private ArrayFill() {
    196        // no instances
    197    }
    198
    199}