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 */
017 package org.apache.commons.lang;
018
019 import org.apache.commons.lang.math.NumberUtils;
020
021 /**
022 * <p>Operations on boolean primitives and Boolean objects.</p>
023 *
024 * <p>This class tries to handle <code>null</code> input gracefully.
025 * An exception will not be thrown for a <code>null</code> input.
026 * Each method documents its behaviour in more detail.</p>
027 *
028 * @author Apache Software Foundation
029 * @author Matthew Hawthorne
030 * @author Gary Gregory
031 * @since 2.0
032 * @version $Id: BooleanUtils.java 905636 2010-02-02 14:03:32Z niallp $
033 */
034 public class BooleanUtils {
035
036 /**
037 * <p><code>BooleanUtils</code> instances should NOT be constructed in standard programming.
038 * Instead, the class should be used as <code>BooleanUtils.toBooleanObject(true);</code>.</p>
039 *
040 * <p>This constructor is public to permit tools that require a JavaBean instance
041 * to operate.</p>
042 */
043 public BooleanUtils() {
044 super();
045 }
046
047 // Boolean utilities
048 //--------------------------------------------------------------------------
049 /**
050 * <p>Negates the specified boolean.</p>
051 *
052 * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
053 *
054 * <pre>
055 * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
056 * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
057 * BooleanUtils.negate(null) = null;
058 * </pre>
059 *
060 * @param bool the Boolean to negate, may be null
061 * @return the negated Boolean, or <code>null</code> if <code>null</code> input
062 */
063 public static Boolean negate(Boolean bool) {
064 if (bool == null) {
065 return null;
066 }
067 return (bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE);
068 }
069
070 // boolean Boolean methods
071 //-----------------------------------------------------------------------
072 /**
073 * <p>Checks if a <code>Boolean</code> value is <code>true</code>,
074 * handling <code>null</code> by returning <code>false</code>.</p>
075 *
076 * <pre>
077 * BooleanUtils.isTrue(Boolean.TRUE) = true
078 * BooleanUtils.isTrue(Boolean.FALSE) = false
079 * BooleanUtils.isTrue(null) = false
080 * </pre>
081 *
082 * @param bool the boolean to check, null returns <code>false</code>
083 * @return <code>true</code> only if the input is non-null and true
084 * @since 2.1
085 */
086 public static boolean isTrue(Boolean bool) {
087 if (bool == null) {
088 return false;
089 }
090 return bool.booleanValue() ? true : false;
091 }
092
093 /**
094 * <p>Checks if a <code>Boolean</code> value is <i>not</i> <code>true</code>,
095 * handling <code>null</code> by returning <code>true</code>.</p>
096 *
097 * <pre>
098 * BooleanUtils.isNotTrue(Boolean.TRUE) = false
099 * BooleanUtils.isNotTrue(Boolean.FALSE) = true
100 * BooleanUtils.isNotTrue(null) = true
101 * </pre>
102 *
103 * @param bool the boolean to check, null returns <code>true</code>
104 * @return <code>true</code> if the input is null or false
105 * @since 2.3
106 */
107 public static boolean isNotTrue(Boolean bool) {
108 return !isTrue(bool);
109 }
110
111 /**
112 * <p>Checks if a <code>Boolean</code> value is <code>false</code>,
113 * handling <code>null</code> by returning <code>false</code>.</p>
114 *
115 * <pre>
116 * BooleanUtils.isFalse(Boolean.TRUE) = false
117 * BooleanUtils.isFalse(Boolean.FALSE) = true
118 * BooleanUtils.isFalse(null) = false
119 * </pre>
120 *
121 * @param bool the boolean to check, null returns <code>false</code>
122 * @return <code>true</code> only if the input is non-null and false
123 * @since 2.1
124 */
125 public static boolean isFalse(Boolean bool) {
126 if (bool == null) {
127 return false;
128 }
129 return bool.booleanValue() ? false : true;
130 }
131
132 /**
133 * <p>Checks if a <code>Boolean</code> value is <i>not</i> <code>false</code>,
134 * handling <code>null</code> by returning <code>true</code>.</p>
135 *
136 * <pre>
137 * BooleanUtils.isNotFalse(Boolean.TRUE) = true
138 * BooleanUtils.isNotFalse(Boolean.FALSE) = false
139 * BooleanUtils.isNotFalse(null) = true
140 * </pre>
141 *
142 * @param bool the boolean to check, null returns <code>true</code>
143 * @return <code>true</code> if the input is null or true
144 * @since 2.3
145 */
146 public static boolean isNotFalse(Boolean bool) {
147 return !isFalse(bool);
148 }
149
150 //-----------------------------------------------------------------------
151 /**
152 * <p>Boolean factory that avoids creating new Boolean objecs all the time.</p>
153 *
154 * <p>This method was added to JDK1.4 but is available here for earlier JDKs.</p>
155 *
156 * <pre>
157 * BooleanUtils.toBooleanObject(false) = Boolean.FALSE
158 * BooleanUtils.toBooleanObject(true) = Boolean.TRUE
159 * </pre>
160 *
161 * @param bool the boolean to convert
162 * @return Boolean.TRUE or Boolean.FALSE as appropriate
163 */
164 public static Boolean toBooleanObject(boolean bool) {
165 return bool ? Boolean.TRUE : Boolean.FALSE;
166 }
167
168 /**
169 * <p>Converts a Boolean to a boolean handling <code>null</code>
170 * by returning <code>false</code>.</p>
171 *
172 * <pre>
173 * BooleanUtils.toBoolean(Boolean.TRUE) = true
174 * BooleanUtils.toBoolean(Boolean.FALSE) = false
175 * BooleanUtils.toBoolean(null) = false
176 * </pre>
177 *
178 * @param bool the boolean to convert
179 * @return <code>true</code> or <code>false</code>,
180 * <code>null</code> returns <code>false</code>
181 */
182 public static boolean toBoolean(Boolean bool) {
183 if (bool == null) {
184 return false;
185 }
186 return bool.booleanValue() ? true : false;
187 }
188
189 /**
190 * <p>Converts a Boolean to a boolean handling <code>null</code>.</p>
191 *
192 * <pre>
193 * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
194 * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
195 * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
196 * </pre>
197 *
198 * @param bool the boolean to convert
199 * @param valueIfNull the boolean value to return if <code>null</code>
200 * @return <code>true</code> or <code>false</code>
201 */
202 public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull) {
203 if (bool == null) {
204 return valueIfNull;
205 }
206 return bool.booleanValue() ? true : false;
207 }
208
209 // Integer to Boolean methods
210 //-----------------------------------------------------------------------
211 /**
212 * <p>Converts an int to a boolean using the convention that <code>zero</code>
213 * is <code>false</code>.</p>
214 *
215 * <pre>
216 * BooleanUtils.toBoolean(0) = false
217 * BooleanUtils.toBoolean(1) = true
218 * BooleanUtils.toBoolean(2) = true
219 * </pre>
220 *
221 * @param value the int to convert
222 * @return <code>true</code> if non-zero, <code>false</code>
223 * if zero
224 */
225 public static boolean toBoolean(int value) {
226 return value == 0 ? false : true;
227 }
228
229 /**
230 * <p>Converts an int to a Boolean using the convention that <code>zero</code>
231 * is <code>false</code>.</p>
232 *
233 * <pre>
234 * BooleanUtils.toBoolean(0) = Boolean.FALSE
235 * BooleanUtils.toBoolean(1) = Boolean.TRUE
236 * BooleanUtils.toBoolean(2) = Boolean.TRUE
237 * </pre>
238 *
239 * @param value the int to convert
240 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
241 * <code>null</code> if <code>null</code>
242 */
243 public static Boolean toBooleanObject(int value) {
244 return value == 0 ? Boolean.FALSE : Boolean.TRUE;
245 }
246
247 /**
248 * <p>Converts an Integer to a Boolean using the convention that <code>zero</code>
249 * is <code>false</code>.</p>
250 *
251 * <p><code>null</code> will be converted to <code>null</code>.</p>
252 *
253 * <pre>
254 * BooleanUtils.toBoolean(new Integer(0)) = Boolean.FALSE
255 * BooleanUtils.toBoolean(new Integer(1)) = Boolean.TRUE
256 * BooleanUtils.toBoolean(new Integer(null)) = null
257 * </pre>
258 *
259 * @param value the Integer to convert
260 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
261 * <code>null</code> if <code>null</code> input
262 */
263 public static Boolean toBooleanObject(Integer value) {
264 if (value == null) {
265 return null;
266 }
267 return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
268 }
269
270 /**
271 * <p>Converts an int to a boolean specifying the conversion values.</p>
272 *
273 * <pre>
274 * BooleanUtils.toBoolean(0, 1, 0) = false
275 * BooleanUtils.toBoolean(1, 1, 0) = true
276 * BooleanUtils.toBoolean(2, 1, 2) = false
277 * BooleanUtils.toBoolean(2, 2, 0) = true
278 * </pre>
279 *
280 * @param value the Integer to convert
281 * @param trueValue the value to match for <code>true</code>
282 * @param falseValue the value to match for <code>false</code>
283 * @return <code>true</code> or <code>false</code>
284 * @throws IllegalArgumentException if no match
285 */
286 public static boolean toBoolean(int value, int trueValue, int falseValue) {
287 if (value == trueValue) {
288 return true;
289 } else if (value == falseValue) {
290 return false;
291 }
292 // no match
293 throw new IllegalArgumentException("The Integer did not match either specified value");
294 }
295
296 /**
297 * <p>Converts an Integer to a boolean specifying the conversion values.</p>
298 *
299 * <pre>
300 * BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
301 * BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
302 * BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
303 * BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
304 * BooleanUtils.toBoolean(null, null, new Integer(0)) = true
305 * </pre>
306 *
307 * @param value the Integer to convert
308 * @param trueValue the value to match for <code>true</code>,
309 * may be <code>null</code>
310 * @param falseValue the value to match for <code>false</code>,
311 * may be <code>null</code>
312 * @return <code>true</code> or <code>false</code>
313 * @throws IllegalArgumentException if no match
314 */
315 public static boolean toBoolean(Integer value, Integer trueValue, Integer falseValue) {
316 if (value == null) {
317 if (trueValue == null) {
318 return true;
319 } else if (falseValue == null) {
320 return false;
321 }
322 } else if (value.equals(trueValue)) {
323 return true;
324 } else if (value.equals(falseValue)) {
325 return false;
326 }
327 // no match
328 throw new IllegalArgumentException("The Integer did not match either specified value");
329 }
330
331 /**
332 * <p>Converts an int to a Boolean specifying the conversion values.</p>
333 *
334 * <pre>
335 * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
336 * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
337 * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
338 * </pre>
339 *
340 * @param value the Integer to convert
341 * @param trueValue the value to match for <code>true</code>
342 * @param falseValue the value to match for <code>false</code>
343 * @param nullValue the value to to match for <code>null</code>
344 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
345 * @throws IllegalArgumentException if no match
346 */
347 public static Boolean toBooleanObject(int value, int trueValue, int falseValue, int nullValue) {
348 if (value == trueValue) {
349 return Boolean.TRUE;
350 } else if (value == falseValue) {
351 return Boolean.FALSE;
352 } else if (value == nullValue) {
353 return null;
354 }
355 // no match
356 throw new IllegalArgumentException("The Integer did not match any specified value");
357 }
358
359 /**
360 * <p>Converts an Integer to a Boolean specifying the conversion values.</p>
361 *
362 * <pre>
363 * BooleanUtils.toBooleanObject(new Integer(0), new Integer(0), new Integer(2), new Integer(3)) = Boolean.TRUE
364 * BooleanUtils.toBooleanObject(new Integer(2), new Integer(1), new Integer(2), new Integer(3)) = Boolean.FALSE
365 * BooleanUtils.toBooleanObject(new Integer(3), new Integer(1), new Integer(2), new Integer(3)) = null
366 * </pre>
367 *
368 * @param value the Integer to convert
369 * @param trueValue the value to match for <code>true</code>,
370 * may be <code>null</code>
371 * @param falseValue the value to match for <code>false</code>,
372 * may be <code>null</code>
373 * @param nullValue the value to to match for <code>null</code>,
374 * may be <code>null</code>
375 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
376 * @throws IllegalArgumentException if no match
377 */
378 public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer falseValue, Integer nullValue) {
379 if (value == null) {
380 if (trueValue == null) {
381 return Boolean.TRUE;
382 } else if (falseValue == null) {
383 return Boolean.FALSE;
384 } else if (nullValue == null) {
385 return null;
386 }
387 } else if (value.equals(trueValue)) {
388 return Boolean.TRUE;
389 } else if (value.equals(falseValue)) {
390 return Boolean.FALSE;
391 } else if (value.equals(nullValue)) {
392 return null;
393 }
394 // no match
395 throw new IllegalArgumentException("The Integer did not match any specified value");
396 }
397
398 // Boolean to Integer methods
399 //-----------------------------------------------------------------------
400 /**
401 * <p>Converts a boolean to an int using the convention that
402 * <code>zero</code> is <code>false</code>.</p>
403 *
404 * <pre>
405 * BooleanUtils.toInteger(true) = 1
406 * BooleanUtils.toInteger(false) = 0
407 * </pre>
408 *
409 * @param bool the boolean to convert
410 * @return one if <code>true</code>, zero if <code>false</code>
411 */
412 public static int toInteger(boolean bool) {
413 return bool ? 1 : 0;
414 }
415
416 /**
417 * <p>Converts a boolean to an Integer using the convention that
418 * <code>zero</code> is <code>false</code>.</p>
419 *
420 * <pre>
421 * BooleanUtils.toIntegerObject(true) = new Integer(1)
422 * BooleanUtils.toIntegerObject(false) = new Integer(0)
423 * </pre>
424 *
425 * @param bool the boolean to convert
426 * @return one if <code>true</code>, zero if <code>false</code>
427 */
428 public static Integer toIntegerObject(boolean bool) {
429 return bool ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
430 }
431
432 /**
433 * <p>Converts a Boolean to a Integer using the convention that
434 * <code>zero</code> is <code>false</code>.</p>
435 *
436 * <p><code>null</code> will be converted to <code>null</code>.</p>
437 *
438 * <pre>
439 * BooleanUtils.toIntegerObject(Boolean.TRUE) = new Integer(1)
440 * BooleanUtils.toIntegerObject(Boolean.FALSE) = new Integer(0)
441 * </pre>
442 *
443 * @param bool the Boolean to convert
444 * @return one if Boolean.TRUE, zero if Boolean.FALSE, <code>null</code> if <code>null</code>
445 */
446 public static Integer toIntegerObject(Boolean bool) {
447 if (bool == null) {
448 return null;
449 }
450 return bool.booleanValue() ? NumberUtils.INTEGER_ONE : NumberUtils.INTEGER_ZERO;
451 }
452
453 /**
454 * <p>Converts a boolean to an int specifying the conversion values.</p>
455 *
456 * <pre>
457 * BooleanUtils.toInteger(true, 1, 0) = 1
458 * BooleanUtils.toInteger(false, 1, 0) = 0
459 * </pre>
460 *
461 * @param bool the to convert
462 * @param trueValue the value to return if <code>true</code>
463 * @param falseValue the value to return if <code>false</code>
464 * @return the appropriate value
465 */
466 public static int toInteger(boolean bool, int trueValue, int falseValue) {
467 return bool ? trueValue : falseValue;
468 }
469
470 /**
471 * <p>Converts a Boolean to an int specifying the conversion values.</p>
472 *
473 * <pre>
474 * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
475 * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
476 * BooleanUtils.toInteger(null, 1, 0, 2) = 2
477 * </pre>
478 *
479 * @param bool the Boolean to convert
480 * @param trueValue the value to return if <code>true</code>
481 * @param falseValue the value to return if <code>false</code>
482 * @param nullValue the value to return if <code>null</code>
483 * @return the appropriate value
484 */
485 public static int toInteger(Boolean bool, int trueValue, int falseValue, int nullValue) {
486 if (bool == null) {
487 return nullValue;
488 }
489 return bool.booleanValue() ? trueValue : falseValue;
490 }
491
492 /**
493 * <p>Converts a boolean to an Integer specifying the conversion values.</p>
494 *
495 * <pre>
496 * BooleanUtils.toIntegerObject(true, new Integer(1), new Integer(0)) = new Integer(1)
497 * BooleanUtils.toIntegerObject(false, new Integer(1), new Integer(0)) = new Integer(0)
498 * </pre>
499 *
500 * @param bool the to convert
501 * @param trueValue the value to return if <code>true</code>,
502 * may be <code>null</code>
503 * @param falseValue the value to return if <code>false</code>,
504 * may be <code>null</code>
505 * @return the appropriate value
506 */
507 public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer falseValue) {
508 return bool ? trueValue : falseValue;
509 }
510
511 /**
512 * <p>Converts a Boolean to an Integer specifying the conversion values.</p>
513 *
514 * <pre>
515 * BooleanUtils.toIntegerObject(Boolean.TRUE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(1)
516 * BooleanUtils.toIntegerObject(Boolean.FALSE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(0)
517 * BooleanUtils.toIntegerObject(null, new Integer(1), new Integer(0), new Integer(2)) = new Integer(2)
518 * </pre>
519 *
520 * @param bool the Boolean to convert
521 * @param trueValue the value to return if <code>true</code>,
522 * may be <code>null</code>
523 * @param falseValue the value to return if <code>false</code>,
524 * may be <code>null</code>
525 * @param nullValue the value to return if <code>null</code>,
526 * may be <code>null</code>
527 * @return the appropriate value
528 */
529 public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue) {
530 if (bool == null) {
531 return nullValue;
532 }
533 return bool.booleanValue() ? trueValue : falseValue;
534 }
535
536 // String to Boolean methods
537 //-----------------------------------------------------------------------
538 /**
539 * <p>Converts a String to a Boolean.</p>
540 *
541 * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
542 * (case insensitive) will return <code>true</code>.
543 * <code>'false'</code>, <code>'off'</code> or <code>'no'</code>
544 * (case insensitive) will return <code>false</code>.
545 * Otherwise, <code>null</code> is returned.</p>
546 *
547 * <pre>
548 * BooleanUtils.toBooleanObject(null) = null
549 * BooleanUtils.toBooleanObject("true") = Boolean.TRUE
550 * BooleanUtils.toBooleanObject("false") = Boolean.FALSE
551 * BooleanUtils.toBooleanObject("on") = Boolean.TRUE
552 * BooleanUtils.toBooleanObject("ON") = Boolean.TRUE
553 * BooleanUtils.toBooleanObject("off") = Boolean.FALSE
554 * BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
555 * BooleanUtils.toBooleanObject("blue") = null
556 * </pre>
557 *
558 * @param str the String to check
559 * @return the Boolean value of the string,
560 * <code>null</code> if no match or <code>null</code> input
561 */
562 public static Boolean toBooleanObject(String str) {
563 if ("true".equalsIgnoreCase(str)) {
564 return Boolean.TRUE;
565 } else if ("false".equalsIgnoreCase(str)) {
566 return Boolean.FALSE;
567 } else if ("on".equalsIgnoreCase(str)) {
568 return Boolean.TRUE;
569 } else if ("off".equalsIgnoreCase(str)) {
570 return Boolean.FALSE;
571 } else if ("yes".equalsIgnoreCase(str)) {
572 return Boolean.TRUE;
573 } else if ("no".equalsIgnoreCase(str)) {
574 return Boolean.FALSE;
575 }
576 // no match
577 return null;
578 }
579
580 /**
581 * <p>Converts a String to a Boolean throwing an exception if no match.</p>
582 *
583 * <pre>
584 * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
585 * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
586 * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
587 * </pre>
588 *
589 * @param str the String to check
590 * @param trueString the String to match for <code>true</code>
591 * (case sensitive), may be <code>null</code>
592 * @param falseString the String to match for <code>false</code>
593 * (case sensitive), may be <code>null</code>
594 * @param nullString the String to match for <code>null</code>
595 * (case sensitive), may be <code>null</code>
596 * @return the Boolean value of the string,
597 * <code>null</code> if either the String matches <code>nullString</code>
598 * or if <code>null</code> input and <code>nullString</code> is
599 * <code>null</code>
600 * @throws IllegalArgumentException if the String doesn't match
601 */
602 public static Boolean toBooleanObject(String str, String trueString, String falseString, String nullString) {
603 if (str == null) {
604 if (trueString == null) {
605 return Boolean.TRUE;
606 } else if (falseString == null) {
607 return Boolean.FALSE;
608 } else if (nullString == null) {
609 return null;
610 }
611 } else if (str.equals(trueString)) {
612 return Boolean.TRUE;
613 } else if (str.equals(falseString)) {
614 return Boolean.FALSE;
615 } else if (str.equals(nullString)) {
616 return null;
617 }
618 // no match
619 throw new IllegalArgumentException("The String did not match any specified value");
620 }
621
622 // String to boolean methods
623 //-----------------------------------------------------------------------
624 /**
625 * <p>Converts a String to a boolean (optimised for performance).</p>
626 *
627 * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
628 * (case insensitive) will return <code>true</code>. Otherwise,
629 * <code>false</code> is returned.</p>
630 *
631 * <p>This method performs 4 times faster (JDK1.4) than
632 * <code>Boolean.valueOf(String)</code>. However, this method accepts
633 * 'on' and 'yes' as true values.
634 *
635 * <pre>
636 * BooleanUtils.toBoolean(null) = false
637 * BooleanUtils.toBoolean("true") = true
638 * BooleanUtils.toBoolean("TRUE") = true
639 * BooleanUtils.toBoolean("tRUe") = true
640 * BooleanUtils.toBoolean("on") = true
641 * BooleanUtils.toBoolean("yes") = true
642 * BooleanUtils.toBoolean("false") = false
643 * BooleanUtils.toBoolean("x gti") = false
644 * </pre>
645 *
646 * @param str the String to check
647 * @return the boolean value of the string, <code>false</code> if no match
648 */
649 public static boolean toBoolean(String str) {
650 // Previously used equalsIgnoreCase, which was fast for interned 'true'.
651 // Non interned 'true' matched 15 times slower.
652 //
653 // Optimisation provides same performance as before for interned 'true'.
654 // Similar performance for null, 'false', and other strings not length 2/3/4.
655 // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
656 if (str == "true") {
657 return true;
658 }
659 if (str == null) {
660 return false;
661 }
662 switch (str.length()) {
663 case 2: {
664 char ch0 = str.charAt(0);
665 char ch1 = str.charAt(1);
666 return
667 (ch0 == 'o' || ch0 == 'O') &&
668 (ch1 == 'n' || ch1 == 'N');
669 }
670 case 3: {
671 char ch = str.charAt(0);
672 if (ch == 'y') {
673 return
674 (str.charAt(1) == 'e' || str.charAt(1) == 'E') &&
675 (str.charAt(2) == 's' || str.charAt(2) == 'S');
676 }
677 if (ch == 'Y') {
678 return
679 (str.charAt(1) == 'E' || str.charAt(1) == 'e') &&
680 (str.charAt(2) == 'S' || str.charAt(2) == 's');
681 }
682 return false;
683 }
684 case 4: {
685 char ch = str.charAt(0);
686 if (ch == 't') {
687 return
688 (str.charAt(1) == 'r' || str.charAt(1) == 'R') &&
689 (str.charAt(2) == 'u' || str.charAt(2) == 'U') &&
690 (str.charAt(3) == 'e' || str.charAt(3) == 'E');
691 }
692 if (ch == 'T') {
693 return
694 (str.charAt(1) == 'R' || str.charAt(1) == 'r') &&
695 (str.charAt(2) == 'U' || str.charAt(2) == 'u') &&
696 (str.charAt(3) == 'E' || str.charAt(3) == 'e');
697 }
698 }
699 }
700 return false;
701 }
702
703 /**
704 * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
705 *
706 * <p>null is returned if there is no match.</p>
707 *
708 * <pre>
709 * BooleanUtils.toBoolean("true", "true", "false") = true
710 * BooleanUtils.toBoolean("false", "true", "false") = false
711 * </pre>
712 *
713 * @param str the String to check
714 * @param trueString the String to match for <code>true</code>
715 * (case sensitive), may be <code>null</code>
716 * @param falseString the String to match for <code>false</code>
717 * (case sensitive), may be <code>null</code>
718 * @return the boolean value of the string
719 * @throws IllegalArgumentException if the String doesn't match
720 */
721 public static boolean toBoolean(String str, String trueString, String falseString) {
722 if (str == null) {
723 if (trueString == null) {
724 return true;
725 } else if (falseString == null) {
726 return false;
727 }
728 } else if (str.equals(trueString)) {
729 return true;
730 } else if (str.equals(falseString)) {
731 return false;
732 }
733 // no match
734 throw new IllegalArgumentException("The String did not match either specified value");
735 }
736
737 // Boolean to String methods
738 //-----------------------------------------------------------------------
739 /**
740 * <p>Converts a Boolean to a String returning <code>'true'</code>,
741 * <code>'false'</code>, or <code>null</code>.</p>
742 *
743 * <pre>
744 * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
745 * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
746 * BooleanUtils.toStringTrueFalse(null) = null;
747 * </pre>
748 *
749 * @param bool the Boolean to check
750 * @return <code>'true'</code>, <code>'false'</code>,
751 * or <code>null</code>
752 */
753 public static String toStringTrueFalse(Boolean bool) {
754 return toString(bool, "true", "false", null);
755 }
756
757 /**
758 * <p>Converts a Boolean to a String returning <code>'on'</code>,
759 * <code>'off'</code>, or <code>null</code>.</p>
760 *
761 * <pre>
762 * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
763 * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
764 * BooleanUtils.toStringOnOff(null) = null;
765 * </pre>
766 *
767 * @param bool the Boolean to check
768 * @return <code>'on'</code>, <code>'off'</code>,
769 * or <code>null</code>
770 */
771 public static String toStringOnOff(Boolean bool) {
772 return toString(bool, "on", "off", null);
773 }
774
775 /**
776 * <p>Converts a Boolean to a String returning <code>'yes'</code>,
777 * <code>'no'</code>, or <code>null</code>.</p>
778 *
779 * <pre>
780 * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
781 * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
782 * BooleanUtils.toStringYesNo(null) = null;
783 * </pre>
784 *
785 * @param bool the Boolean to check
786 * @return <code>'yes'</code>, <code>'no'</code>,
787 * or <code>null</code>
788 */
789 public static String toStringYesNo(Boolean bool) {
790 return toString(bool, "yes", "no", null);
791 }
792
793 /**
794 * <p>Converts a Boolean to a String returning one of the input Strings.</p>
795 *
796 * <pre>
797 * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
798 * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
799 * BooleanUtils.toString(null, "true", "false", null) = null;
800 * </pre>
801 *
802 * @param bool the Boolean to check
803 * @param trueString the String to return if <code>true</code>,
804 * may be <code>null</code>
805 * @param falseString the String to return if <code>false</code>,
806 * may be <code>null</code>
807 * @param nullString the String to return if <code>null</code>,
808 * may be <code>null</code>
809 * @return one of the three input Strings
810 */
811 public static String toString(Boolean bool, String trueString, String falseString, String nullString) {
812 if (bool == null) {
813 return nullString;
814 }
815 return bool.booleanValue() ? trueString : falseString;
816 }
817
818 // boolean to String methods
819 //-----------------------------------------------------------------------
820 /**
821 * <p>Converts a boolean to a String returning <code>'true'</code>
822 * or <code>'false'</code>.</p>
823 *
824 * <pre>
825 * BooleanUtils.toStringTrueFalse(true) = "true"
826 * BooleanUtils.toStringTrueFalse(false) = "false"
827 * </pre>
828 *
829 * @param bool the Boolean to check
830 * @return <code>'true'</code>, <code>'false'</code>,
831 * or <code>null</code>
832 */
833 public static String toStringTrueFalse(boolean bool) {
834 return toString(bool, "true", "false");
835 }
836
837 /**
838 * <p>Converts a boolean to a String returning <code>'on'</code>
839 * or <code>'off'</code>.</p>
840 *
841 * <pre>
842 * BooleanUtils.toStringOnOff(true) = "on"
843 * BooleanUtils.toStringOnOff(false) = "off"
844 * </pre>
845 *
846 * @param bool the Boolean to check
847 * @return <code>'on'</code>, <code>'off'</code>,
848 * or <code>null</code>
849 */
850 public static String toStringOnOff(boolean bool) {
851 return toString(bool, "on", "off");
852 }
853
854 /**
855 * <p>Converts a boolean to a String returning <code>'yes'</code>
856 * or <code>'no'</code>.</p>
857 *
858 * <pre>
859 * BooleanUtils.toStringYesNo(true) = "yes"
860 * BooleanUtils.toStringYesNo(false) = "no"
861 * </pre>
862 *
863 * @param bool the Boolean to check
864 * @return <code>'yes'</code>, <code>'no'</code>,
865 * or <code>null</code>
866 */
867 public static String toStringYesNo(boolean bool) {
868 return toString(bool, "yes", "no");
869 }
870
871 /**
872 * <p>Converts a boolean to a String returning one of the input Strings.</p>
873 *
874 * <pre>
875 * BooleanUtils.toString(true, "true", "false") = "true"
876 * BooleanUtils.toString(false, "true", "false") = "false"
877 * </pre>
878 *
879 * @param bool the Boolean to check
880 * @param trueString the String to return if <code>true</code>,
881 * may be <code>null</code>
882 * @param falseString the String to return if <code>false</code>,
883 * may be <code>null</code>
884 * @return one of the two input Strings
885 */
886 public static String toString(boolean bool, String trueString, String falseString) {
887 return bool ? trueString : falseString;
888 }
889
890 // xor methods
891 // ----------------------------------------------------------------------
892 /**
893 * <p>Performs an xor on a set of booleans.</p>
894 *
895 * <pre>
896 * BooleanUtils.xor(new boolean[] { true, true }) = false
897 * BooleanUtils.xor(new boolean[] { false, false }) = false
898 * BooleanUtils.xor(new boolean[] { true, false }) = true
899 * </pre>
900 *
901 * @param array an array of <code>boolean<code>s
902 * @return <code>true</code> if the xor is successful.
903 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
904 * @throws IllegalArgumentException if <code>array</code> is empty.
905 */
906 public static boolean xor(boolean[] array) {
907 // Validates input
908 if (array == null) {
909 throw new IllegalArgumentException("The Array must not be null");
910 } else if (array.length == 0) {
911 throw new IllegalArgumentException("Array is empty");
912 }
913
914 // Loops through array, comparing each item
915 int trueCount = 0;
916 for (int i = 0; i < array.length; i++) {
917 // If item is true, and trueCount is < 1, increments count
918 // Else, xor fails
919 if (array[i]) {
920 if (trueCount < 1) {
921 trueCount++;
922 } else {
923 return false;
924 }
925 }
926 }
927
928 // Returns true if there was exactly 1 true item
929 return trueCount == 1;
930 }
931
932 /**
933 * <p>Performs an xor on an array of Booleans.</p>
934 *
935 * <pre>
936 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
937 * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
938 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
939 * </pre>
940 *
941 * @param array an array of <code>Boolean<code>s
942 * @return <code>true</code> if the xor is successful.
943 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
944 * @throws IllegalArgumentException if <code>array</code> is empty.
945 * @throws IllegalArgumentException if <code>array</code> contains a <code>null</code>
946 */
947 public static Boolean xor(Boolean[] array) {
948 if (array == null) {
949 throw new IllegalArgumentException("The Array must not be null");
950 } else if (array.length == 0) {
951 throw new IllegalArgumentException("Array is empty");
952 }
953 boolean[] primitive = null;
954 try {
955 primitive = ArrayUtils.toPrimitive(array);
956 } catch (NullPointerException ex) {
957 throw new IllegalArgumentException("The array must not contain any null elements");
958 }
959 return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
960 }
961
962 }