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 * https://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
18 package org.apache.commons.lang3;
19
20 import java.util.Arrays;
21 import java.util.function.IntFunction;
22
23 import org.apache.commons.lang3.function.FailableIntFunction;
24
25 /**
26 * Fills and returns arrays in the fluent style.
27 *
28 * @since 3.14.0
29 */
30 public final class ArrayFill {
31
32 /**
33 * Fills and returns the given array, assigning {@code 0} to each element of the array.
34 * <pre>
35 * ArrayFill.fill(a, (byte) 0);
36 * </pre>
37 *
38 * @param a The array to fill (may be null).
39 * @return The given array.
40 * @see Arrays#fill(byte[],byte)
41 * @see ArrayFill#fill(byte[],byte)
42 * @since 3.21.0
43 */
44 public static byte[] clear(final byte[] a) {
45 return fill(a, (byte) 0);
46 }
47
48 /**
49 * Fills and returns the given array, assigning {@code '\0'} to each element of the array.
50 * <p>
51 * Equivalent to:
52 * </p>
53 * <pre>
54 * ArrayFill.fill(a, '\0'); // and not '0'!
55 * </pre>
56 *
57 * @param a The array to fill (may be null).
58 * @return The given array.
59 * @see Arrays#fill(char[],char)
60 * @see ArrayFill#fill(char[],char)
61 * @see CharUtils#NUL
62 * @since 3.21.0
63 */
64 public static char[] clear(final char[] a) {
65 return fill(a, CharUtils.NUL); // and not '0'!
66 }
67
68 /**
69 * Fills and returns the given array, assigning {@code '\0'} to each element of the array.
70 * <p>
71 * Equivalent to:
72 * </p>
73 * <pre>
74 * ArrayFill.fill(a, fromIndex, toIndex, '\0'); // and not '0'!
75 * </pre>
76 *
77 * @param a The array to fill (may be null).
78 * @param fromIndex The index of the first element (inclusive) to be filled with {@code '\0'}.
79 * @param toIndex The index of the last element (exclusive) to be filled with {@code '\0'}.
80 * @return The given array.
81 * @see Arrays#fill(char[], int, int, char)
82 * @since 3.21.0
83 */
84 public static char[] clear(final char[] a, final int fromIndex, final int toIndex) {
85 return fill(a, fromIndex, toIndex, CharUtils.NUL);
86 }
87
88 /**
89 * Fills and returns the given array, assigning the given {@code boolean} value to each element of the array.
90 *
91 * @param a The array to fill (may be null).
92 * @param val The value to store in all elements of the array.
93 * @return The given array.
94 * @see Arrays#fill(boolean[],boolean)
95 * @since 3.18.0
96 */
97 public static boolean[] fill(final boolean[] a, final boolean val) {
98 if (a != null) {
99 Arrays.fill(a, val);
100 }
101 return a;
102 }
103
104 /**
105 * Fills and returns the given array, assigning the given {@code byte} value to each element of the array.
106 *
107 * @param a The array to fill (may be null).
108 * @param val The value to store in all elements of the array.
109 * @return The given array.
110 * @see Arrays#fill(byte[],byte)
111 */
112 public static byte[] fill(final byte[] a, final byte val) {
113 if (a != null) {
114 Arrays.fill(a, val);
115 }
116 return a;
117 }
118
119 /**
120 * Fills and returns the given array, assigning the given {@code char} value to each element of the array.
121 *
122 * @param a The array to fill (may be null).
123 * @param val The value to store in all elements of the array.
124 * @return The given array.
125 * @see Arrays#fill(char[],char)
126 */
127 public static char[] fill(final char[] a, final char val) {
128 if (a != null) {
129 Arrays.fill(a, val);
130 }
131 return a;
132 }
133
134 /**
135 * Fills and returns the given array, assigning the given {@code char} value to each element of the array.
136 *
137 * @param a The array to fill (may be null).
138 * @param val The value to store in all elements of the array.
139 * @param fromIndex The index of the first element (inclusive) to be filled with the specified value.
140 * @param toIndex The index of the last element (exclusive) to be filled with the specified value.
141 * @return The given array.
142 * @see Arrays#fill(char[], int, int, char)
143 * @since 3.21.0
144 */
145 public static char[] fill(final char[] a, final int fromIndex, final int toIndex, final char val) {
146 if (a != null) {
147 Arrays.fill(a, fromIndex, toIndex, val);
148 }
149 return a;
150 }
151
152 /**
153 * Fills and returns the given array, assigning the given {@code double} value to each element of the array.
154 *
155 * @param a The array to fill (may be null).
156 * @param val The value to store in all elements of the array.
157 * @return The given array.
158 * @see Arrays#fill(double[],double)
159 */
160 public static double[] fill(final double[] a, final double val) {
161 if (a != null) {
162 Arrays.fill(a, val);
163 }
164 return a;
165 }
166
167 /**
168 * Fills and returns the given array, assigning the given {@code float} value to each element of the array.
169 *
170 * @param a The array to fill (may be null).
171 * @param val The value to store in all elements of the array.
172 * @return The given array.
173 * @see Arrays#fill(float[],float)
174 */
175 public static float[] fill(final float[] a, final float val) {
176 if (a != null) {
177 Arrays.fill(a, val);
178 }
179 return a;
180 }
181
182 /**
183 * Fills and returns the given array, assigning the given {@code int} value to each element of the array.
184 *
185 * @param a The array to fill (may be null).
186 * @param val The value to store in all elements of the array.
187 * @return The given array.
188 * @see Arrays#fill(int[],int)
189 */
190 public static int[] fill(final int[] a, final int val) {
191 if (a != null) {
192 Arrays.fill(a, val);
193 }
194 return a;
195 }
196
197 /**
198 * Fills and returns the given array, assigning the given {@code long} value to each element of the array.
199 *
200 * @param a The array to fill (may be null).
201 * @param val The value to store in all elements of the array.
202 * @return The given array.
203 * @see Arrays#fill(long[],long)
204 */
205 public static long[] fill(final long[] a, final long val) {
206 if (a != null) {
207 Arrays.fill(a, val);
208 }
209 return a;
210 }
211
212 /**
213 * Fills and returns the given array, assigning the given {@code short} value to each element of the array.
214 *
215 * @param a The array to fill (may be null).
216 * @param val The value to store in all elements of the array.
217 * @return The given array.
218 * @see Arrays#fill(short[],short)
219 */
220 public static short[] fill(final short[] a, final short val) {
221 if (a != null) {
222 Arrays.fill(a, val);
223 }
224 return a;
225 }
226
227 /**
228 * Fills and returns the given array, using the provided generator function to compute each element. Like {@link Arrays#setAll(Object[], IntFunction)} with
229 * exception support.
230 * <p>
231 * If the generator function throws an exception, it is relayed to the caller and the array is left in an indeterminate state.
232 * </p>
233 * <p>
234 * If the input array or generator function is null, nothing happens.
235 * </p>
236 *
237 * @param <T> type of elements of the array.
238 * @param array array to fill (may be null).
239 * @param generator A function accepting an index and producing the desired value for that position.
240 * @return The input array.
241 * @param <E> The kind of thrown exception or error.
242 * @throws E Thrown by the given {@code generator}.
243 * @see Arrays#setAll(Object[], IntFunction)
244 * @since 3.18.0
245 */
246 public static <T, E extends Throwable> T[] fill(final T[] array, final FailableIntFunction<? extends T, E> generator) throws E {
247 if (array != null && generator != null) {
248 for (int i = 0; i < array.length; i++) {
249 array[i] = generator.apply(i);
250 }
251 }
252 return array;
253 }
254
255 /**
256 * Fills and returns the given array, assigning the given {@code T} value to each element of the array.
257 *
258 * @param <T> The array type.
259 * @param a The array to fill (may be null).
260 * @param val The value to store in all elements of the array.
261 * @return The given array.
262 * @see Arrays#fill(Object[],Object)
263 */
264 public static <T> T[] fill(final T[] a, final T val) {
265 if (a != null) {
266 Arrays.fill(a, val);
267 }
268 return a;
269 }
270
271 private ArrayFill() {
272 // no instances
273 }
274
275 }