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