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 * http://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.lang;
18
19 import org.apache.commons.lang.math.NumberUtils;
20
21 /**
22 * <p>Operations on boolean primitives and Boolean objects.</p>
23 *
24 * <p>This class tries to handle <code>null</code> input gracefully.
25 * An exception will not be thrown for a <code>null</code> input.
26 * Each method documents its behaviour in more detail.</p>
27 *
28 * @author Stephen Colebourne
29 * @author Matthew Hawthorne
30 * @author Gary Gregory
31 * @since 2.0
32 * @version $Id: BooleanUtils.java 589050 2007-10-27 05:07:45Z bayard $
33 */
34 public class BooleanUtils {
35
36 /**
37 * <p><code>BooleanUtils</code> instances should NOT be constructed in standard programming.
38 * Instead, the class should be used as <code>BooleanUtils.toBooleanObject(true);</code>.</p>
39 *
40 * <p>This constructor is public to permit tools that require a JavaBean instance
41 * to operate.</p>
42 */
43 public BooleanUtils() {
44 super();
45 }
46
47 // Boolean utilities
48 //--------------------------------------------------------------------------
49 /**
50 * <p>Negates the specified boolean.</p>
51 *
52 * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
53 *
54 * <pre>
55 * BooleanUtils.negate(Boolean.TRUE) = Boolean.FALSE;
56 * BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
57 * BooleanUtils.negate(null) = null;
58 * </pre>
59 *
60 * @param bool the Boolean to negate, may be null
61 * @return the negated Boolean, or <code>null</code> if <code>null</code> input
62 */
63 public static Boolean negate(Boolean bool) {
64 if (bool == null) {
65 return null;
66 }
67 return (bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE);
68 }
69
70 // boolean Boolean methods
71 //-----------------------------------------------------------------------
72 /**
73 * <p>Checks if a <code>Boolean</code> value is <code>true</code>,
74 * handling <code>null</code> by returning <code>false</code>.</p>
75 *
76 * <pre>
77 * BooleanUtils.isTrue(Boolean.TRUE) = true
78 * BooleanUtils.isTrue(Boolean.FALSE) = false
79 * BooleanUtils.isTrue(null) = false
80 * </pre>
81 *
82 * @param bool the boolean to check, null returns <code>false</code>
83 * @return <code>true</code> only if the input is non-null and true
84 * @since 2.1
85 */
86 public static boolean isTrue(Boolean bool) {
87 if (bool == null) {
88 return false;
89 }
90 return bool.booleanValue() ? true : false;
91 }
92
93 /**
94 * <p>Checks if a <code>Boolean</code> value is <i>not</i> <code>true</code>,
95 * handling <code>null</code> by returning <code>true</code>.</p>
96 *
97 * <pre>
98 * BooleanUtils.isNotTrue(Boolean.TRUE) = false
99 * 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 // public static void main(String[] args) {
704 // long start = System.currentTimeMillis();
705 // boolean flag = true;
706 // int count = 0;
707 // for (int i = 0; i < 100000000; i++) {
708 // flag = toBoolean("YES");
709 // }
710 // long end = System.currentTimeMillis();
711 // System.out.println((end - start) + " " + flag + " " + count);
712 // }
713
714 /**
715 * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
716 *
717 * <p>null is returned if there is no match.</p>
718 *
719 * <pre>
720 * BooleanUtils.toBoolean("true", "true", "false") = true
721 * BooleanUtils.toBoolean("false", "true", "false") = false
722 * </pre>
723 *
724 * @param str the String to check
725 * @param trueString the String to match for <code>true</code>
726 * (case sensitive), may be <code>null</code>
727 * @param falseString the String to match for <code>false</code>
728 * (case sensitive), may be <code>null</code>
729 * @return the boolean value of the string
730 * @throws IllegalArgumentException if the String doesn't match
731 */
732 public static boolean toBoolean(String str, String trueString, String falseString) {
733 if (str == null) {
734 if (trueString == null) {
735 return true;
736 } else if (falseString == null) {
737 return false;
738 }
739 } else if (str.equals(trueString)) {
740 return true;
741 } else if (str.equals(falseString)) {
742 return false;
743 }
744 // no match
745 throw new IllegalArgumentException("The String did not match either specified value");
746 }
747
748 // Boolean to String methods
749 //-----------------------------------------------------------------------
750 /**
751 * <p>Converts a Boolean to a String returning <code>'true'</code>,
752 * <code>'false'</code>, or <code>null</code>.</p>
753 *
754 * <pre>
755 * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
756 * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
757 * BooleanUtils.toStringTrueFalse(null) = null;
758 * </pre>
759 *
760 * @param bool the Boolean to check
761 * @return <code>'true'</code>, <code>'false'</code>,
762 * or <code>null</code>
763 */
764 public static String toStringTrueFalse(Boolean bool) {
765 return toString(bool, "true", "false", null);
766 }
767
768 /**
769 * <p>Converts a Boolean to a String returning <code>'on'</code>,
770 * <code>'off'</code>, or <code>null</code>.</p>
771 *
772 * <pre>
773 * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
774 * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
775 * BooleanUtils.toStringOnOff(null) = null;
776 * </pre>
777 *
778 * @param bool the Boolean to check
779 * @return <code>'on'</code>, <code>'off'</code>,
780 * or <code>null</code>
781 */
782 public static String toStringOnOff(Boolean bool) {
783 return toString(bool, "on", "off", null);
784 }
785
786 /**
787 * <p>Converts a Boolean to a String returning <code>'yes'</code>,
788 * <code>'no'</code>, or <code>null</code>.</p>
789 *
790 * <pre>
791 * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
792 * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
793 * BooleanUtils.toStringYesNo(null) = null;
794 * </pre>
795 *
796 * @param bool the Boolean to check
797 * @return <code>'yes'</code>, <code>'no'</code>,
798 * or <code>null</code>
799 */
800 public static String toStringYesNo(Boolean bool) {
801 return toString(bool, "yes", "no", null);
802 }
803
804 /**
805 * <p>Converts a Boolean to a String returning one of the input Strings.</p>
806 *
807 * <pre>
808 * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
809 * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
810 * BooleanUtils.toString(null, "true", "false", null) = null;
811 * </pre>
812 *
813 * @param bool the Boolean to check
814 * @param trueString the String to return if <code>true</code>,
815 * may be <code>null</code>
816 * @param falseString the String to return if <code>false</code>,
817 * may be <code>null</code>
818 * @param nullString the String to return if <code>null</code>,
819 * may be <code>null</code>
820 * @return one of the three input Strings
821 */
822 public static String toString(Boolean bool, String trueString, String falseString, String nullString) {
823 if (bool == null) {
824 return nullString;
825 }
826 return bool.booleanValue() ? trueString : falseString;
827 }
828
829 // boolean to String methods
830 //-----------------------------------------------------------------------
831 /**
832 * <p>Converts a boolean to a String returning <code>'true'</code>
833 * or <code>'false'</code>.</p>
834 *
835 * <pre>
836 * BooleanUtils.toStringTrueFalse(true) = "true"
837 * BooleanUtils.toStringTrueFalse(false) = "false"
838 * </pre>
839 *
840 * @param bool the Boolean to check
841 * @return <code>'true'</code>, <code>'false'</code>,
842 * or <code>null</code>
843 */
844 public static String toStringTrueFalse(boolean bool) {
845 return toString(bool, "true", "false");
846 }
847
848 /**
849 * <p>Converts a boolean to a String returning <code>'on'</code>
850 * or <code>'off'</code>.</p>
851 *
852 * <pre>
853 * BooleanUtils.toStringOnOff(true) = "on"
854 * BooleanUtils.toStringOnOff(false) = "off"
855 * </pre>
856 *
857 * @param bool the Boolean to check
858 * @return <code>'on'</code>, <code>'off'</code>,
859 * or <code>null</code>
860 */
861 public static String toStringOnOff(boolean bool) {
862 return toString(bool, "on", "off");
863 }
864
865 /**
866 * <p>Converts a boolean to a String returning <code>'yes'</code>
867 * or <code>'no'</code>.</p>
868 *
869 * <pre>
870 * BooleanUtils.toStringYesNo(true) = "yes"
871 * BooleanUtils.toStringYesNo(false) = "no"
872 * </pre>
873 *
874 * @param bool the Boolean to check
875 * @return <code>'yes'</code>, <code>'no'</code>,
876 * or <code>null</code>
877 */
878 public static String toStringYesNo(boolean bool) {
879 return toString(bool, "yes", "no");
880 }
881
882 /**
883 * <p>Converts a boolean to a String returning one of the input Strings.</p>
884 *
885 * <pre>
886 * BooleanUtils.toString(true, "true", "false") = "true"
887 * BooleanUtils.toString(false, "true", "false") = "false"
888 * </pre>
889 *
890 * @param bool the Boolean to check
891 * @param trueString the String to return if <code>true</code>,
892 * may be <code>null</code>
893 * @param falseString the String to return if <code>false</code>,
894 * may be <code>null</code>
895 * @return one of the two input Strings
896 */
897 public static String toString(boolean bool, String trueString, String falseString) {
898 return bool ? trueString : falseString;
899 }
900
901 // xor methods
902 // ----------------------------------------------------------------------
903 /**
904 * <p>Performs an xor on a set of booleans.</p>
905 *
906 * <pre>
907 * BooleanUtils.xor(new boolean[] { true, true }) = false
908 * BooleanUtils.xor(new boolean[] { false, false }) = false
909 * BooleanUtils.xor(new boolean[] { true, false }) = true
910 * </pre>
911 *
912 * @param array an array of <code>boolean<code>s
913 * @return <code>true</code> if the xor is successful.
914 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
915 * @throws IllegalArgumentException if <code>array</code> is empty.
916 */
917 public static boolean xor(boolean[] array) {
918 // Validates input
919 if (array == null) {
920 throw new IllegalArgumentException("The Array must not be null");
921 } else if (array.length == 0) {
922 throw new IllegalArgumentException("Array is empty");
923 }
924
925 // Loops through array, comparing each item
926 int trueCount = 0;
927 for (int i = 0; i < array.length; i++) {
928 // If item is true, and trueCount is < 1, increments count
929 // Else, xor fails
930 if (array[i]) {
931 if (trueCount < 1) {
932 trueCount++;
933 } else {
934 return false;
935 }
936 }
937 }
938
939 // Returns true if there was exactly 1 true item
940 return trueCount == 1;
941 }
942
943 /**
944 * <p>Performs an xor on an array of Booleans.</p>
945 *
946 * <pre>
947 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
948 * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
949 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
950 * </pre>
951 *
952 * @param array an array of <code>Boolean<code>s
953 * @return <code>true</code> if the xor is successful.
954 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
955 * @throws IllegalArgumentException if <code>array</code> is empty.
956 * @throws IllegalArgumentException if <code>array</code> contains a <code>null</code>
957 */
958 public static Boolean xor(Boolean[] array) {
959 if (array == null) {
960 throw new IllegalArgumentException("The Array must not be null");
961 } else if (array.length == 0) {
962 throw new IllegalArgumentException("Array is empty");
963 }
964 boolean[] primitive = null;
965 try {
966 primitive = ArrayUtils.toPrimitive(array);
967 } catch (NullPointerException ex) {
968 throw new IllegalArgumentException("The array must not contain any null elements");
969 }
970 return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
971 }
972
973 }