001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3; 018 019import java.util.Arrays; 020import java.util.Collections; 021import java.util.List; 022import java.util.function.Consumer; 023 024import org.apache.commons.lang3.math.NumberUtils; 025 026/** 027 * Operations on boolean primitives and Boolean objects. 028 * 029 * <p>This class tries to handle {@code null} input gracefully. 030 * An exception will not be thrown for a {@code null} input. 031 * Each method documents its behavior in more detail.</p> 032 * 033 * <p>#ThreadSafe#</p> 034 * @since 2.0 035 */ 036public class BooleanUtils { 037 038 private static final List<Boolean> BOOLEAN_LIST = Collections.unmodifiableList(Arrays.asList(Boolean.FALSE, Boolean.TRUE)); 039 040 /** 041 * The false String {@code "false"}. 042 * 043 * @since 3.12.0 044 */ 045 public static final String FALSE = "false"; 046 047 /** 048 * The no String {@code "no"}. 049 * 050 * @since 3.12.0 051 */ 052 public static final String NO = "no"; 053 054 /** 055 * The off String {@code "off"}. 056 * 057 * @since 3.12.0 058 */ 059 public static final String OFF = "off"; 060 061 /** 062 * The on String {@code "on"}. 063 * 064 * @since 3.12.0 065 */ 066 public static final String ON = "on"; 067 068 /** 069 * The true String {@code "true"}. 070 * 071 * @since 3.12.0 072 */ 073 public static final String TRUE = "true"; 074 075 /** 076 * The yes String {@code "yes"}. 077 * 078 * @since 3.12.0 079 */ 080 public static final String YES = "yes"; 081 082 /** 083 * Performs an 'and' operation on a set of booleans. 084 * 085 * <pre> 086 * BooleanUtils.and(true, true) = true 087 * BooleanUtils.and(false, false) = false 088 * BooleanUtils.and(true, false) = false 089 * BooleanUtils.and(true, true, false) = false 090 * BooleanUtils.and(true, true, true) = true 091 * </pre> 092 * 093 * @param array an array of {@code boolean}s 094 * @return the result of the logical 'and' operation. That is {@code false} 095 * if any of the parameters is {@code false} and {@code true} otherwise. 096 * @throws NullPointerException if {@code array} is {@code null} 097 * @throws IllegalArgumentException if {@code array} is empty. 098 * @since 3.0.1 099 */ 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 * // N.B. 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 // Optimisation 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}