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 package org.apache.commons.lang3;
18
19 import java.util.Arrays;
20 import java.util.Collections;
21 import java.util.List;
22 import java.util.function.Consumer;
23
24 import org.apache.commons.lang3.math.NumberUtils;
25
26 /**
27 * Operations on boolean primitives and Boolean objects.
28 *
29 * <p>This class tries to handle {@code null} input gracefully.
30 * An exception will not be thrown for a {@code null} input.
31 * Each method documents its behavior in more detail.</p>
32 *
33 * <p>#ThreadSafe#</p>
34 * @since 2.0
35 */
36 public class BooleanUtils {
37
38 private static final List<Boolean> BOOLEAN_LIST = Collections.unmodifiableList(Arrays.asList(Boolean.FALSE, Boolean.TRUE));
39
40 /**
41 * The false String {@code "false"}.
42 *
43 * @since 3.12.0
44 */
45 public static final String FALSE = "false";
46
47 /**
48 * The no String {@code "no"}.
49 *
50 * @since 3.12.0
51 */
52 public static final String NO = "no";
53
54 /**
55 * The off String {@code "off"}.
56 *
57 * @since 3.12.0
58 */
59 public static final String OFF = "off";
60
61 /**
62 * The on String {@code "on"}.
63 *
64 * @since 3.12.0
65 */
66 public static final String ON = "on";
67
68 /**
69 * The true String {@code "true"}.
70 *
71 * @since 3.12.0
72 */
73 public static final String TRUE = "true";
74
75 /**
76 * The yes String {@code "yes"}.
77 *
78 * @since 3.12.0
79 */
80 public static final String YES = "yes";
81
82 /**
83 * Performs an 'and' operation on a set of booleans.
84 *
85 * <pre>
86 * BooleanUtils.and(true, true) = true
87 * BooleanUtils.and(false, false) = false
88 * BooleanUtils.and(true, false) = false
89 * BooleanUtils.and(true, true, false) = false
90 * BooleanUtils.and(true, true, true) = true
91 * </pre>
92 *
93 * @param array an array of {@code boolean}s
94 * @return the result of the logical 'and' operation. That is {@code false}
95 * if any of the parameters is {@code false} and {@code true} otherwise.
96 * @throws NullPointerException if {@code array} is {@code null}
97 * @throws IllegalArgumentException if {@code array} is empty.
98 * @since 3.0.1
99 */
100 public static boolean and(final boolean... array) {
101 ObjectUtils.requireNonEmpty(array, "array");
102 for (final boolean element : array) {
103 if (!element) {
104 return false;
105 }
106 }
107 return true;
108 }
109
110 /**
111 * Performs an 'and' operation on an array of Booleans.
112 * <pre>
113 * BooleanUtils.and(Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
114 * BooleanUtils.and(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
115 * BooleanUtils.and(Boolean.TRUE, Boolean.FALSE) = Boolean.FALSE
116 * BooleanUtils.and(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
117 * BooleanUtils.and(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
118 * BooleanUtils.and(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE) = Boolean.FALSE
119 * BooleanUtils.and(null, null) = Boolean.FALSE
120 * </pre>
121 * <p>
122 * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
123 * </p>
124 *
125 * @param array an array of {@link Boolean}s
126 * @return the result of the logical 'and' operation. That is {@code false}
127 * if any of the parameters is {@code false} and {@code true} otherwise.
128 * @throws NullPointerException if {@code array} is {@code null}
129 * @throws IllegalArgumentException if {@code array} is empty.
130 * @since 3.0.1
131 */
132 public static Boolean and(final Boolean... array) {
133 ObjectUtils.requireNonEmpty(array, "array");
134 return and(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
135 }
136
137 /**
138 * Returns a new array of possible values (like an enum would).
139 *
140 * @return a new array of possible values (like an enum would).
141 * @since 3.12.0
142 */
143 public static Boolean[] booleanValues() {
144 return new Boolean[] {Boolean.FALSE, Boolean.TRUE};
145 }
146
147 /**
148 * Compares two {@code boolean} values. This is the same functionality as provided in Java 7.
149 *
150 * @param x the first {@code boolean} to compare
151 * @param y the second {@code boolean} to compare
152 * @return the value {@code 0} if {@code x == y};
153 * a value less than {@code 0} if {@code !x && y}; and
154 * a value greater than {@code 0} if {@code x && !y}
155 * @since 3.4
156 */
157 public static int compare(final boolean x, final boolean y) {
158 if (x == y) {
159 return 0;
160 }
161 return x ? 1 : -1;
162 }
163
164 /**
165 * Performs the given action for each Boolean {@link BooleanUtils#values()}.
166 *
167 * @param action The action to be performed for each element
168 * @since 3.13.0
169 */
170 public static void forEach(final Consumer<Boolean> action) {
171 values().forEach(action);
172 }
173
174 /**
175 * Checks if a {@link Boolean} value is {@code false},
176 * handling {@code null} by returning {@code false}.
177 *
178 * <pre>
179 * BooleanUtils.isFalse(Boolean.TRUE) = false
180 * BooleanUtils.isFalse(Boolean.FALSE) = true
181 * BooleanUtils.isFalse(null) = false
182 * </pre>
183 *
184 * @param bool the boolean to check, null returns {@code false}
185 * @return {@code true} only if the input is non-{@code null} and {@code false}
186 * @since 2.1
187 */
188 public static boolean isFalse(final Boolean bool) {
189 return Boolean.FALSE.equals(bool);
190 }
191
192 /**
193 * Checks if a {@link Boolean} value is <em>not</em> {@code false},
194 * handling {@code null} by returning {@code true}.
195 *
196 * <pre>
197 * BooleanUtils.isNotFalse(Boolean.TRUE) = true
198 * BooleanUtils.isNotFalse(Boolean.FALSE) = false
199 * BooleanUtils.isNotFalse(null) = true
200 * </pre>
201 *
202 * @param bool the boolean to check, null returns {@code true}
203 * @return {@code true} if the input is {@code null} or {@code true}
204 * @since 2.3
205 */
206 public static boolean isNotFalse(final Boolean bool) {
207 return !isFalse(bool);
208 }
209
210 /**
211 * Checks if a {@link Boolean} value is <em>not</em> {@code true},
212 * handling {@code null} by returning {@code true}.
213 *
214 * <pre>
215 * BooleanUtils.isNotTrue(Boolean.TRUE) = false
216 * BooleanUtils.isNotTrue(Boolean.FALSE) = true
217 * BooleanUtils.isNotTrue(null) = true
218 * </pre>
219 *
220 * @param bool the boolean to check, null returns {@code true}
221 * @return {@code true} if the input is null or false
222 * @since 2.3
223 */
224 public static boolean isNotTrue(final Boolean bool) {
225 return !isTrue(bool);
226 }
227
228 /**
229 * Checks if a {@link Boolean} value is {@code true},
230 * handling {@code null} by returning {@code false}.
231 *
232 * <pre>
233 * BooleanUtils.isTrue(Boolean.TRUE) = true
234 * BooleanUtils.isTrue(Boolean.FALSE) = false
235 * BooleanUtils.isTrue(null) = false
236 * </pre>
237 *
238 * @param bool the boolean to check, {@code null} returns {@code false}
239 * @return {@code true} only if the input is non-null and true
240 * @since 2.1
241 */
242 public static boolean isTrue(final Boolean bool) {
243 return Boolean.TRUE.equals(bool);
244 }
245 /**
246 * Negates the specified boolean.
247 *
248 * <p>If {@code null} is passed in, {@code null} will be returned.</p>
249 *
250 * <p>NOTE: This returns {@code null} and will throw a {@link NullPointerException}
251 * if unboxed to a boolean.</p>
252 *
253 * <pre>
254 * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
255 * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
256 * BooleanUtils.negate(null) = null;
257 * </pre>
258 *
259 * @param bool the Boolean to negate, may be null
260 * @return the negated Boolean, or {@code null} if {@code null} input
261 */
262 public static Boolean negate(final Boolean bool) {
263 if (bool == null) {
264 return null;
265 }
266 return bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE;
267 }
268
269 /**
270 * Performs a one-hot on an array of booleans.
271 * <p>
272 * This implementation returns true if one, and only one, of the supplied values is true.
273 * </p>
274 * <p>
275 * See also <a href="https://en.wikipedia.org/wiki/One-hot">One-hot</a>.
276 * </p>
277 * @param array an array of {@code boolean}s
278 * @return the result of the one-hot operations
279 * @throws NullPointerException if {@code array} is {@code null}
280 * @throws IllegalArgumentException if {@code array} is empty.
281 */
282 public static boolean oneHot(final boolean... array) {
283 ObjectUtils.requireNonEmpty(array, "array");
284 boolean result = false;
285 for (final boolean element: array) {
286 if (element) {
287 if (result) {
288 return false;
289 }
290 result = true;
291 }
292 }
293 return result;
294 }
295
296 /**
297 * Performs a one-hot on an array of booleans.
298 * <p>
299 * This implementation returns true if one, and only one, of the supplied values is true.
300 * </p>
301 * <p>
302 * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
303 * </p>
304 * <p>
305 * See also <a href="https://en.wikipedia.org/wiki/One-hot">One-hot</a>.
306 * </p>
307 *
308 * @param array an array of {@code boolean}s
309 * @return the result of the one-hot operations
310 * @throws NullPointerException if {@code array} is {@code null}
311 * @throws IllegalArgumentException if {@code array} is empty.
312 */
313 public static Boolean oneHot(final Boolean... array) {
314 return Boolean.valueOf(oneHot(ArrayUtils.toPrimitive(array)));
315 }
316
317 /**
318 * Performs an 'or' operation on a set of booleans.
319 *
320 * <pre>
321 * BooleanUtils.or(true, true) = true
322 * BooleanUtils.or(false, false) = false
323 * BooleanUtils.or(true, false) = true
324 * BooleanUtils.or(true, true, false) = true
325 * BooleanUtils.or(true, true, true) = true
326 * BooleanUtils.or(false, false, false) = false
327 * </pre>
328 *
329 * @param array an array of {@code boolean}s
330 * @return {@code true} if any of the arguments is {@code true}, and it returns {@code false} otherwise.
331 * @throws NullPointerException if {@code array} is {@code null}
332 * @throws IllegalArgumentException if {@code array} is empty.
333 * @since 3.0.1
334 */
335 public static boolean or(final boolean... array) {
336 ObjectUtils.requireNonEmpty(array, "array");
337 for (final boolean element : array) {
338 if (element) {
339 return true;
340 }
341 }
342 return false;
343 }
344
345 /**
346 * Performs an 'or' operation on an array of Booleans.
347 * <pre>
348 * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
349 * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
350 * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE) = Boolean.TRUE
351 * BooleanUtils.or(Boolean.TRUE, Boolean.TRUE, Boolean.TRUE) = Boolean.TRUE
352 * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
353 * BooleanUtils.or(Boolean.TRUE, Boolean.FALSE, Boolean.TRUE) = Boolean.TRUE
354 * BooleanUtils.or(Boolean.FALSE, Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
355 * BooleanUtils.or(Boolean.TRUE, null) = Boolean.TRUE
356 * BooleanUtils.or(Boolean.FALSE, null) = Boolean.FALSE
357 * </pre>
358 * <p>
359 * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
360 * </p>
361 *
362 * @param array an array of {@link Boolean}s
363 * @return {@code true} if any of the arguments is {@code true}, and it returns {@code false} otherwise.
364 * @throws NullPointerException if {@code array} is {@code null}
365 * @throws IllegalArgumentException if {@code array} is empty.
366 * @since 3.0.1
367 */
368 public static Boolean or(final Boolean... array) {
369 ObjectUtils.requireNonEmpty(array, "array");
370 return or(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
371 }
372
373 /**
374 * Returns a new array of possible values (like an enum would).
375 * @return a new array of possible values (like an enum would).
376 * @since 3.12.0
377 */
378 public static boolean[] primitiveValues() {
379 return new boolean[] {false, true};
380 }
381
382 /**
383 * Converts a Boolean to a boolean handling {@code null}
384 * by returning {@code false}.
385 *
386 * <pre>
387 * BooleanUtils.toBoolean(Boolean.TRUE) = true
388 * BooleanUtils.toBoolean(Boolean.FALSE) = false
389 * BooleanUtils.toBoolean(null) = false
390 * </pre>
391 *
392 * @param bool the boolean to convert
393 * @return {@code true} or {@code false}, {@code null} returns {@code false}
394 */
395 public static boolean toBoolean(final Boolean bool) {
396 return bool != null && bool.booleanValue();
397 }
398
399 /**
400 * Converts an int to a boolean using the convention that {@code zero}
401 * is {@code false}, everything else is {@code true}.
402 *
403 * <pre>
404 * BooleanUtils.toBoolean(0) = false
405 * BooleanUtils.toBoolean(1) = true
406 * BooleanUtils.toBoolean(2) = true
407 * </pre>
408 *
409 * @param value the int to convert
410 * @return {@code true} if non-zero, {@code false}
411 * if zero
412 */
413 public static boolean toBoolean(final int value) {
414 return value != 0;
415 }
416
417 /**
418 * Converts an int to a boolean specifying the conversion values.
419 *
420 * <p>If the {@code trueValue} and {@code falseValue} are the same number then
421 * the return value will be {@code true} in case {@code value} matches it.</p>
422 *
423 * <pre>
424 * BooleanUtils.toBoolean(0, 1, 0) = false
425 * BooleanUtils.toBoolean(1, 1, 0) = true
426 * BooleanUtils.toBoolean(1, 1, 1) = true
427 * BooleanUtils.toBoolean(2, 1, 2) = false
428 * BooleanUtils.toBoolean(2, 2, 0) = true
429 * </pre>
430 *
431 * @param value the {@link Integer} to convert
432 * @param trueValue the value to match for {@code true}
433 * @param falseValue the value to match for {@code false}
434 * @return {@code true} or {@code false}
435 * @throws IllegalArgumentException if {@code value} does not match neither
436 * {@code trueValue} no {@code falseValue}
437 */
438 public static boolean toBoolean(final int value, final int trueValue, final int falseValue) {
439 if (value == trueValue) {
440 return true;
441 }
442 if (value == falseValue) {
443 return false;
444 }
445 throw new IllegalArgumentException("The Integer did not match either specified value");
446 }
447
448 /**
449 * Converts an Integer to a boolean specifying the conversion values.
450 *
451 * <pre>
452 * BooleanUtils.toBoolean(Integer.valueOf(0), Integer.valueOf(1), Integer.valueOf(0)) = false
453 * BooleanUtils.toBoolean(Integer.valueOf(1), Integer.valueOf(1), Integer.valueOf(0)) = true
454 * BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2)) = false
455 * BooleanUtils.toBoolean(Integer.valueOf(2), Integer.valueOf(2), Integer.valueOf(0)) = true
456 * BooleanUtils.toBoolean(null, null, Integer.valueOf(0)) = true
457 * </pre>
458 *
459 * @param value the Integer to convert
460 * @param trueValue the value to match for {@code true}, may be {@code null}
461 * @param falseValue the value to match for {@code false}, may be {@code null}
462 * @return {@code true} or {@code false}
463 * @throws IllegalArgumentException if no match
464 */
465 public static boolean toBoolean(final Integer value, final Integer trueValue, final Integer falseValue) {
466 if (value == null) {
467 if (trueValue == null) {
468 return true;
469 }
470 if (falseValue == null) {
471 return false;
472 }
473 } else if (value.equals(trueValue)) {
474 return true;
475 } else if (value.equals(falseValue)) {
476 return false;
477 }
478 throw new IllegalArgumentException("The Integer did not match either specified value");
479 }
480
481 /**
482 * Converts a String to a boolean (optimized for performance).
483 *
484 * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'} or {@code 'yes'}
485 * (case insensitive) will return {@code true}. Otherwise,
486 * {@code false} is returned.</p>
487 *
488 * <p>This method performs 4 times faster (JDK1.4) than
489 * {@code Boolean.valueOf(String)}. However, this method accepts
490 * 'on' and 'yes', 't', 'y' as true values.
491 *
492 * <pre>
493 * BooleanUtils.toBoolean(null) = false
494 * BooleanUtils.toBoolean("true") = true
495 * BooleanUtils.toBoolean("TRUE") = true
496 * BooleanUtils.toBoolean("tRUe") = true
497 * BooleanUtils.toBoolean("on") = true
498 * BooleanUtils.toBoolean("yes") = true
499 * BooleanUtils.toBoolean("false") = false
500 * BooleanUtils.toBoolean("x gti") = false
501 * BooleanUtils.toBoolean("y") = true
502 * BooleanUtils.toBoolean("n") = false
503 * BooleanUtils.toBoolean("t") = true
504 * BooleanUtils.toBoolean("f") = false
505 * </pre>
506 *
507 * @param str the String to check
508 * @return the boolean value of the string, {@code false} if no match or the String is null
509 */
510 public static boolean toBoolean(final String str) {
511 return toBooleanObject(str) == Boolean.TRUE;
512 }
513
514 /**
515 * Converts a String to a Boolean throwing an exception if no match found.
516 *
517 * <pre>
518 * BooleanUtils.toBoolean("true", "true", "false") = true
519 * BooleanUtils.toBoolean("false", "true", "false") = false
520 * </pre>
521 *
522 * @param str the String to check
523 * @param trueString the String to match for {@code true} (case-sensitive), may be {@code null}
524 * @param falseString the String to match for {@code false} (case-sensitive), may be {@code null}
525 * @return the boolean value of the string
526 * @throws IllegalArgumentException if the String doesn't match
527 */
528 public static boolean toBoolean(final String str, final String trueString, final String falseString) {
529 if (str == trueString) {
530 return true;
531 }
532 if (str == falseString) {
533 return false;
534 }
535 if (str != null) {
536 if (str.equals(trueString)) {
537 return true;
538 }
539 if (str.equals(falseString)) {
540 return false;
541 }
542 }
543 throw new IllegalArgumentException("The String did not match either specified value");
544 }
545
546 /**
547 * Converts a Boolean to a boolean handling {@code null}.
548 *
549 * <pre>
550 * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
551 * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, true) = true
552 * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
553 * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, false) = false
554 * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
555 * BooleanUtils.toBooleanDefaultIfNull(null, false) = false
556 * </pre>
557 *
558 * @param bool the boolean object to convert to primitive
559 * @param valueIfNull the boolean value to return if the parameter {@code bool} is {@code null}
560 * @return {@code true} or {@code false}
561 */
562 public static boolean toBooleanDefaultIfNull(final Boolean bool, final boolean valueIfNull) {
563 if (bool == null) {
564 return valueIfNull;
565 }
566 return bool.booleanValue();
567 }
568
569 /**
570 * Converts an int to a Boolean using the convention that {@code zero}
571 * is {@code false}, everything else is {@code true}.
572 *
573 * <pre>
574 * BooleanUtils.toBoolean(0) = Boolean.FALSE
575 * BooleanUtils.toBoolean(1) = Boolean.TRUE
576 * BooleanUtils.toBoolean(2) = Boolean.TRUE
577 * </pre>
578 *
579 * @param value the int to convert
580 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
581 * {@code null} if {@code null}
582 */
583 public static Boolean toBooleanObject(final int value) {
584 return value == 0 ? Boolean.FALSE : Boolean.TRUE;
585 }
586
587 /**
588 * Converts an int to a Boolean specifying the conversion values.
589 *
590 * <p>NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
591 * if unboxed to a {@code boolean}.</p>
592 *
593 * <p>The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
594 * finally for the {@code nullValue}.</p>
595 *
596 * <pre>
597 * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
598 * BooleanUtils.toBooleanObject(0, 0, 0, 3) = Boolean.TRUE
599 * BooleanUtils.toBooleanObject(0, 0, 0, 0) = Boolean.TRUE
600 * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
601 * BooleanUtils.toBooleanObject(2, 1, 2, 2) = Boolean.FALSE
602 * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
603 * </pre>
604 *
605 * @param value the Integer to convert
606 * @param trueValue the value to match for {@code true}
607 * @param falseValue the value to match for {@code false}
608 * @param nullValue the value to match for {@code null}
609 * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
610 * @throws IllegalArgumentException if no match
611 */
612 public static Boolean toBooleanObject(final int value, final int trueValue, final int falseValue, final int nullValue) {
613 if (value == trueValue) {
614 return Boolean.TRUE;
615 }
616 if (value == falseValue) {
617 return Boolean.FALSE;
618 }
619 if (value == nullValue) {
620 return null;
621 }
622 throw new IllegalArgumentException("The Integer did not match any specified value");
623 }
624
625 /**
626 * Converts an Integer to a Boolean using the convention that {@code zero}
627 * is {@code false}, every other numeric value is {@code true}.
628 *
629 * <p>{@code null} will be converted to {@code null}.</p>
630 *
631 * <p>NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
632 * if unboxed to a {@code boolean}.</p>
633 *
634 * <pre>
635 * BooleanUtils.toBooleanObject(Integer.valueOf(0)) = Boolean.FALSE
636 * BooleanUtils.toBooleanObject(Integer.valueOf(1)) = Boolean.TRUE
637 * BooleanUtils.toBooleanObject(Integer.valueOf(null)) = null
638 * </pre>
639 *
640 * @param value the Integer to convert
641 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
642 * {@code null} if {@code null} input
643 */
644 public static Boolean toBooleanObject(final Integer value) {
645 if (value == null) {
646 return null;
647 }
648 return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
649 }
650
651 /**
652 * Converts an Integer to a Boolean specifying the conversion values.
653 *
654 * <p>NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
655 * if unboxed to a {@code boolean}.</p>
656 *
657 * <p>The checks are done first for the {@code trueValue}, then for the {@code falseValue} and
658 * finally for the {@code nullValue}.</p>
659 **
660 * <pre>
661 * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.TRUE
662 * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(3)) = Boolean.TRUE
663 * BooleanUtils.toBooleanObject(Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0), Integer.valueOf(0)) = Boolean.TRUE
664 * BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = Boolean.FALSE
665 * BooleanUtils.toBooleanObject(Integer.valueOf(2), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(2)) = Boolean.FALSE
666 * BooleanUtils.toBooleanObject(Integer.valueOf(3), Integer.valueOf(1), Integer.valueOf(2), Integer.valueOf(3)) = null
667 * </pre>
668 *
669 * @param value the Integer to convert
670 * @param trueValue the value to match for {@code true}, may be {@code null}
671 * @param falseValue the value to match for {@code false}, may be {@code null}
672 * @param nullValue the value to match for {@code null}, may be {@code null}
673 * @return Boolean.TRUE, Boolean.FALSE, or {@code null}
674 * @throws IllegalArgumentException if no match
675 */
676 public static Boolean toBooleanObject(final Integer value, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
677 if (value == null) {
678 if (trueValue == null) {
679 return Boolean.TRUE;
680 }
681 if (falseValue == null) {
682 return Boolean.FALSE;
683 }
684 if (nullValue == null) {
685 return null;
686 }
687 } else if (value.equals(trueValue)) {
688 return Boolean.TRUE;
689 } else if (value.equals(falseValue)) {
690 return Boolean.FALSE;
691 } else if (value.equals(nullValue)) {
692 return null;
693 }
694 throw new IllegalArgumentException("The Integer did not match any specified value");
695 }
696
697 /**
698 * Converts a String to a Boolean.
699 *
700 * <p>{@code 'true'}, {@code 'on'}, {@code 'y'}, {@code 't'}, {@code 'yes'}
701 * or {@code '1'} (case insensitive) will return {@code true}.
702 * {@code 'false'}, {@code 'off'}, {@code 'n'}, {@code 'f'}, {@code 'no'}
703 * or {@code '0'} (case insensitive) will return {@code false}.
704 * Otherwise, {@code null} is returned.</p>
705 *
706 * <p>NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
707 * if unboxed to a {@code boolean}.</p>
708 *
709 * <pre>
710 * // Case is not significant
711 * BooleanUtils.toBooleanObject(null) = null
712 * BooleanUtils.toBooleanObject("true") = Boolean.TRUE
713 * BooleanUtils.toBooleanObject("T") = Boolean.TRUE // i.e. T[RUE]
714 * BooleanUtils.toBooleanObject("false") = Boolean.FALSE
715 * BooleanUtils.toBooleanObject("f") = Boolean.FALSE // i.e. f[alse]
716 * BooleanUtils.toBooleanObject("No") = Boolean.FALSE
717 * BooleanUtils.toBooleanObject("n") = Boolean.FALSE // i.e. n[o]
718 * BooleanUtils.toBooleanObject("on") = Boolean.TRUE
719 * BooleanUtils.toBooleanObject("ON") = Boolean.TRUE
720 * BooleanUtils.toBooleanObject("off") = Boolean.FALSE
721 * BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
722 * BooleanUtils.toBooleanObject("yes") = Boolean.TRUE
723 * BooleanUtils.toBooleanObject("Y") = Boolean.TRUE // i.e. Y[ES]
724 * BooleanUtils.toBooleanObject("1") = Boolean.TRUE
725 * BooleanUtils.toBooleanObject("0") = Boolean.FALSE
726 * BooleanUtils.toBooleanObject("blue") = null
727 * BooleanUtils.toBooleanObject("true ") = null // trailing space (too long)
728 * BooleanUtils.toBooleanObject("ono") = null // does not match on or no
729 * </pre>
730 *
731 * @param str the String to check; upper and lower case are treated as the same
732 * @return the Boolean value of the string, {@code null} if no match or {@code null} input
733 */
734 public static Boolean toBooleanObject(final String str) {
735 // Previously used equalsIgnoreCase, which was fast for interned 'true'.
736 // Non interned 'true' matched 15 times slower.
737 //
738 // Optimization provides same performance as before for interned 'true'.
739 // Similar performance for null, 'false', and other strings not length 2/3/4.
740 // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
741 if (str == TRUE) {
742 return Boolean.TRUE;
743 }
744 if (str == null) {
745 return null;
746 }
747 switch (str.length()) {
748 case 1: {
749 final char ch0 = str.charAt(0);
750 if (ch0 == 'y' || ch0 == 'Y' ||
751 ch0 == 't' || ch0 == 'T' ||
752 ch0 == '1') {
753 return Boolean.TRUE;
754 }
755 if (ch0 == 'n' || ch0 == 'N' ||
756 ch0 == 'f' || ch0 == 'F' ||
757 ch0 == '0') {
758 return Boolean.FALSE;
759 }
760 break;
761 }
762 case 2: {
763 final char ch0 = str.charAt(0);
764 final char ch1 = str.charAt(1);
765 if ((ch0 == 'o' || ch0 == 'O') &&
766 (ch1 == 'n' || ch1 == 'N')) {
767 return Boolean.TRUE;
768 }
769 if ((ch0 == 'n' || ch0 == 'N') &&
770 (ch1 == 'o' || ch1 == 'O')) {
771 return Boolean.FALSE;
772 }
773 break;
774 }
775 case 3: {
776 final char ch0 = str.charAt(0);
777 final char ch1 = str.charAt(1);
778 final char ch2 = str.charAt(2);
779 if ((ch0 == 'y' || ch0 == 'Y') &&
780 (ch1 == 'e' || ch1 == 'E') &&
781 (ch2 == 's' || ch2 == 'S')) {
782 return Boolean.TRUE;
783 }
784 if ((ch0 == 'o' || ch0 == 'O') &&
785 (ch1 == 'f' || ch1 == 'F') &&
786 (ch2 == 'f' || ch2 == 'F')) {
787 return Boolean.FALSE;
788 }
789 break;
790 }
791 case 4: {
792 final char ch0 = str.charAt(0);
793 final char ch1 = str.charAt(1);
794 final char ch2 = str.charAt(2);
795 final char ch3 = str.charAt(3);
796 if ((ch0 == 't' || ch0 == 'T') &&
797 (ch1 == 'r' || ch1 == 'R') &&
798 (ch2 == 'u' || ch2 == 'U') &&
799 (ch3 == 'e' || ch3 == 'E')) {
800 return Boolean.TRUE;
801 }
802 break;
803 }
804 case 5: {
805 final char ch0 = str.charAt(0);
806 final char ch1 = str.charAt(1);
807 final char ch2 = str.charAt(2);
808 final char ch3 = str.charAt(3);
809 final char ch4 = str.charAt(4);
810 if ((ch0 == 'f' || ch0 == 'F') &&
811 (ch1 == 'a' || ch1 == 'A') &&
812 (ch2 == 'l' || ch2 == 'L') &&
813 (ch3 == 's' || ch3 == 'S') &&
814 (ch4 == 'e' || ch4 == 'E')) {
815 return Boolean.FALSE;
816 }
817 break;
818 }
819 default:
820 break;
821 }
822
823 return null;
824 }
825
826 /**
827 * Converts a String to a Boolean throwing an exception if no match.
828 *
829 * <p>NOTE: This method may return {@code null} and may throw a {@link NullPointerException}
830 * if unboxed to a {@code boolean}.</p>
831 *
832 * <pre>
833 * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
834 * BooleanUtils.toBooleanObject(null, null, "false", "null") = Boolean.TRUE
835 * BooleanUtils.toBooleanObject(null, null, null, "null") = Boolean.TRUE
836 * BooleanUtils.toBooleanObject(null, null, null, null) = Boolean.TRUE
837 * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
838 * BooleanUtils.toBooleanObject("false", "true", "false", "false") = Boolean.FALSE
839 * BooleanUtils.toBooleanObject(null, "true", null, "false") = Boolean.FALSE
840 * BooleanUtils.toBooleanObject(null, "true", null, null) = Boolean.FALSE
841 * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
842 * </pre>
843 *
844 * @param str the String to check
845 * @param trueString the String to match for {@code true} (case-sensitive), may be {@code null}
846 * @param falseString the String to match for {@code false} (case-sensitive), may be {@code null}
847 * @param nullString the String to match for {@code null} (case-sensitive), may be {@code null}
848 * @return the Boolean value of the string, {@code null} if either the String matches {@code nullString}
849 * or if {@code null} input and {@code nullString} is {@code null}
850 * @throws IllegalArgumentException if the String doesn't match
851 */
852 public static Boolean toBooleanObject(final String str, final String trueString, final String falseString, final String nullString) {
853 if (str == null) {
854 if (trueString == null) {
855 return Boolean.TRUE;
856 }
857 if (falseString == null) {
858 return Boolean.FALSE;
859 }
860 if (nullString == null) {
861 return null;
862 }
863 } else if (str.equals(trueString)) {
864 return Boolean.TRUE;
865 } else if (str.equals(falseString)) {
866 return Boolean.FALSE;
867 } else if (str.equals(nullString)) {
868 return null;
869 }
870 // no match
871 throw new IllegalArgumentException("The String did not match any specified value");
872 }
873
874 /**
875 * Converts a boolean to an int using the convention that
876 * {@code true} is {@code 1} and {@code false} is {@code 0}.
877 *
878 * <pre>
879 * BooleanUtils.toInteger(true) = 1
880 * BooleanUtils.toInteger(false) = 0
881 * </pre>
882 *
883 * @param bool the boolean to convert
884 * @return one if {@code true}, zero if {@code false}
885 */
886 public static int toInteger(final boolean bool) {
887 return bool ? 1 : 0;
888 }
889
890 /**
891 * Converts a boolean to an int specifying the conversion values.
892 *
893 * <pre>
894 * BooleanUtils.toInteger(true, 1, 0) = 1
895 * BooleanUtils.toInteger(false, 1, 0) = 0
896 * </pre>
897 *
898 * @param bool the to convert
899 * @param trueValue the value to return if {@code true}
900 * @param falseValue the value to return if {@code false}
901 * @return the appropriate value
902 */
903 public static int toInteger(final boolean bool, final int trueValue, final int falseValue) {
904 return bool ? trueValue : falseValue;
905 }
906
907 /**
908 * Converts a Boolean to an int specifying the conversion values.
909 *
910 * <pre>
911 * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
912 * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
913 * BooleanUtils.toInteger(null, 1, 0, 2) = 2
914 * </pre>
915 *
916 * @param bool the Boolean to convert
917 * @param trueValue the value to return if {@code true}
918 * @param falseValue the value to return if {@code false}
919 * @param nullValue the value to return if {@code null}
920 * @return the appropriate value
921 */
922 public static int toInteger(final Boolean bool, final int trueValue, final int falseValue, final int nullValue) {
923 if (bool == null) {
924 return nullValue;
925 }
926 return bool.booleanValue() ? trueValue : falseValue;
927 }
928
929 /**
930 * Converts a boolean to an Integer using the convention that
931 * {@code true} is {@code 1} and {@code false} is {@code 0}.
932 *
933 * <pre>
934 * BooleanUtils.toIntegerObject(true) = Integer.valueOf(1)
935 * BooleanUtils.toIntegerObject(false) = Integer.valueOf(0)
936 * </pre>
937 *
938 * @param bool the boolean to convert
939 * @return one if {@code true}, zero if {@code false}
940 */
941 public static Integer toIntegerObject(final boolean bool) {
942 return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
943 }
944
945 /**
946 * Converts a boolean to an Integer specifying the conversion values.
947 *
948 * <pre>
949 * BooleanUtils.toIntegerObject(true, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(1)
950 * BooleanUtils.toIntegerObject(false, Integer.valueOf(1), Integer.valueOf(0)) = Integer.valueOf(0)
951 * </pre>
952 *
953 * @param bool the to convert
954 * @param trueValue the value to return if {@code true}, may be {@code null}
955 * @param falseValue the value to return if {@code false}, may be {@code null}
956 * @return the appropriate value
957 */
958 public static Integer toIntegerObject(final boolean bool, final Integer trueValue, final Integer falseValue) {
959 return bool ? trueValue : falseValue;
960 }
961
962 /**
963 * Converts a Boolean to an Integer using the convention that
964 * {@code zero} is {@code false}.
965 *
966 * <p>{@code null} will be converted to {@code null}.</p>
967 *
968 * <pre>
969 * BooleanUtils.toIntegerObject(Boolean.TRUE) = Integer.valueOf(1)
970 * BooleanUtils.toIntegerObject(Boolean.FALSE) = Integer.valueOf(0)
971 * </pre>
972 *
973 * @param bool the Boolean to convert
974 * @return one if Boolean.TRUE, zero if Boolean.FALSE, {@code null} if {@code null}
975 */
976 public static Integer toIntegerObject(final Boolean bool) {
977 if (bool == null) {
978 return null;
979 }
980 return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
981 }
982
983 /**
984 * Converts a Boolean to an Integer specifying the conversion values.
985 *
986 * <pre>
987 * BooleanUtils.toIntegerObject(Boolean.TRUE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(1)
988 * BooleanUtils.toIntegerObject(Boolean.FALSE, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(0)
989 * BooleanUtils.toIntegerObject(null, Integer.valueOf(1), Integer.valueOf(0), Integer.valueOf(2)) = Integer.valueOf(2)
990 * </pre>
991 *
992 * @param bool the Boolean to convert
993 * @param trueValue the value to return if {@code true}, may be {@code null}
994 * @param falseValue the value to return if {@code false}, may be {@code null}
995 * @param nullValue the value to return if {@code null}, may be {@code null}
996 * @return the appropriate value
997 */
998 public static Integer toIntegerObject(final Boolean bool, final Integer trueValue, final Integer falseValue, final Integer nullValue) {
999 if (bool == null) {
1000 return nullValue;
1001 }
1002 return bool.booleanValue() ? trueValue : falseValue;
1003 }
1004
1005 /**
1006 * Converts a boolean to a String returning one of the input Strings.
1007 *
1008 * <pre>
1009 * BooleanUtils.toString(true, "true", "false") = "true"
1010 * BooleanUtils.toString(false, "true", "false") = "false"
1011 * </pre>
1012 *
1013 * @param bool the Boolean to check
1014 * @param trueString the String to return if {@code true}, may be {@code null}
1015 * @param falseString the String to return if {@code false}, may be {@code null}
1016 * @return one of the two input Strings
1017 */
1018 public static String toString(final boolean bool, final String trueString, final String falseString) {
1019 return bool ? trueString : falseString;
1020 }
1021
1022 /**
1023 * Converts a Boolean to a String returning one of the input Strings.
1024 *
1025 * <pre>
1026 * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
1027 * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
1028 * BooleanUtils.toString(null, "true", "false", null) = null;
1029 * </pre>
1030 *
1031 * @param bool the Boolean to check
1032 * @param trueString the String to return if {@code true}, may be {@code null}
1033 * @param falseString the String to return if {@code false}, may be {@code null}
1034 * @param nullString the String to return if {@code null}, may be {@code null}
1035 * @return one of the three input Strings
1036 */
1037 public static String toString(final Boolean bool, final String trueString, final String falseString, final String nullString) {
1038 if (bool == null) {
1039 return nullString;
1040 }
1041 return bool.booleanValue() ? trueString : falseString;
1042 }
1043
1044 /**
1045 * Converts a boolean to a String returning {@code 'on'}
1046 * or {@code 'off'}.
1047 *
1048 * <pre>
1049 * BooleanUtils.toStringOnOff(true) = "on"
1050 * BooleanUtils.toStringOnOff(false) = "off"
1051 * </pre>
1052 *
1053 * @param bool the Boolean to check
1054 * @return {@code 'on'}, {@code 'off'}, or {@code null}
1055 */
1056 public static String toStringOnOff(final boolean bool) {
1057 return toString(bool, ON, OFF);
1058 }
1059
1060 /**
1061 * Converts a Boolean to a String returning {@code 'on'},
1062 * {@code 'off'}, or {@code null}.
1063 *
1064 * <pre>
1065 * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
1066 * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
1067 * BooleanUtils.toStringOnOff(null) = null;
1068 * </pre>
1069 *
1070 * @param bool the Boolean to check
1071 * @return {@code 'on'}, {@code 'off'}, or {@code null}
1072 */
1073 public static String toStringOnOff(final Boolean bool) {
1074 return toString(bool, ON, OFF, null);
1075 }
1076
1077 /**
1078 * Converts a boolean to a String returning {@code 'true'}
1079 * or {@code 'false'}.
1080 *
1081 * <pre>
1082 * BooleanUtils.toStringTrueFalse(true) = "true"
1083 * BooleanUtils.toStringTrueFalse(false) = "false"
1084 * </pre>
1085 *
1086 * @param bool the Boolean to check
1087 * @return {@code 'true'}, {@code 'false'}, or {@code null}
1088 */
1089 public static String toStringTrueFalse(final boolean bool) {
1090 return toString(bool, TRUE, FALSE);
1091 }
1092
1093 /**
1094 * Converts a Boolean to a String returning {@code 'true'},
1095 * {@code 'false'}, or {@code null}.
1096 *
1097 * <pre>
1098 * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
1099 * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
1100 * BooleanUtils.toStringTrueFalse(null) = null;
1101 * </pre>
1102 *
1103 * @param bool the Boolean to check
1104 * @return {@code 'true'}, {@code 'false'}, or {@code null}
1105 */
1106 public static String toStringTrueFalse(final Boolean bool) {
1107 return toString(bool, TRUE, FALSE, null);
1108 }
1109
1110 /**
1111 * Converts a boolean to a String returning {@code 'yes'}
1112 * or {@code 'no'}.
1113 *
1114 * <pre>
1115 * BooleanUtils.toStringYesNo(true) = "yes"
1116 * BooleanUtils.toStringYesNo(false) = "no"
1117 * </pre>
1118 *
1119 * @param bool the Boolean to check
1120 * @return {@code 'yes'}, {@code 'no'}, or {@code null}
1121 */
1122 public static String toStringYesNo(final boolean bool) {
1123 return toString(bool, YES, NO);
1124 }
1125
1126 /**
1127 * Converts a Boolean to a String returning {@code 'yes'},
1128 * {@code 'no'}, or {@code null}.
1129 *
1130 * <pre>
1131 * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
1132 * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
1133 * BooleanUtils.toStringYesNo(null) = null;
1134 * </pre>
1135 *
1136 * @param bool the Boolean to check
1137 * @return {@code 'yes'}, {@code 'no'}, or {@code null}
1138 */
1139 public static String toStringYesNo(final Boolean bool) {
1140 return toString(bool, YES, NO, null);
1141 }
1142
1143 /**
1144 * Returns an unmodifiable list of Booleans {@code [false, true]}.
1145 *
1146 * @return an unmodifiable list of Booleans {@code [false, true]}.
1147 * @since 3.13.0
1148 */
1149 public static List<Boolean> values() {
1150 return BOOLEAN_LIST;
1151 }
1152
1153 /**
1154 * Performs an xor on a set of booleans.
1155 * <p>
1156 * This behaves like an XOR gate;
1157 * it returns true if the number of true values is odd,
1158 * and false if the number of true values is zero or even.
1159 * </p>
1160 *
1161 * <pre>
1162 * BooleanUtils.xor(true, true) = false
1163 * BooleanUtils.xor(false, false) = false
1164 * BooleanUtils.xor(true, false) = true
1165 * BooleanUtils.xor(true, false, false) = true
1166 * BooleanUtils.xor(true, true, true) = true
1167 * BooleanUtils.xor(true, true, true, true) = false
1168 * </pre>
1169 *
1170 * @param array an array of {@code boolean}s
1171 * @return true if the number of true values in the array is odd; otherwise returns false.
1172 * @throws NullPointerException if {@code array} is {@code null}
1173 * @throws IllegalArgumentException if {@code array} is empty.
1174 */
1175 public static boolean xor(final boolean... array) {
1176 ObjectUtils.requireNonEmpty(array, "array");
1177 // false if the neutral element of the xor operator
1178 boolean result = false;
1179 for (final boolean element : array) {
1180 result ^= element;
1181 }
1182
1183 return result;
1184 }
1185
1186 /**
1187 * Performs an xor on an array of Booleans.
1188 * <pre>
1189 * BooleanUtils.xor(Boolean.TRUE, Boolean.TRUE) = Boolean.FALSE
1190 * BooleanUtils.xor(Boolean.FALSE, Boolean.FALSE) = Boolean.FALSE
1191 * BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE) = Boolean.TRUE
1192 * BooleanUtils.xor(Boolean.TRUE, Boolean.FALSE, Boolean.FALSE) = Boolean.TRUE
1193 * BooleanUtils.xor(Boolean.FALSE, null) = Boolean.FALSE
1194 * BooleanUtils.xor(Boolean.TRUE, null) = Boolean.TRUE
1195 * </pre>
1196 * <p>
1197 * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
1198 * </p>
1199 *
1200 * @param array an array of {@link Boolean}s
1201 * @return the result of the xor operations
1202 * @throws NullPointerException if {@code array} is {@code null}
1203 * @throws IllegalArgumentException if {@code array} is empty.
1204 */
1205 public static Boolean xor(final Boolean... array) {
1206 ObjectUtils.requireNonEmpty(array, "array");
1207 return xor(ArrayUtils.toPrimitive(array)) ? Boolean.TRUE : Boolean.FALSE;
1208 }
1209
1210 /**
1211 * {@link BooleanUtils} instances should NOT be constructed in standard programming.
1212 * Instead, the class should be used as {@code BooleanUtils.negate(true);}.
1213 *
1214 * <p>This constructor is public to permit tools that require a JavaBean instance
1215 * to operate.</p>
1216 *
1217 * @deprecated TODO Make private in 4.0.
1218 */
1219 @Deprecated
1220 public BooleanUtils() {
1221 // empty
1222 }
1223
1224 }