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}