001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.shared.ldap.util;
021
022
023 /**
024 * <p>
025 * Operations on boolean primitives and Boolean objects.
026 * </p>
027 * <p>
028 * This class tries to handle <code>null</code> input gracefully. An exception
029 * will not be thrown for a <code>null</code> input. Each method documents its
030 * behaviour in more detail.
031 * </p>
032 *
033 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
034 * @since 2.0
035 * @version $Id: BooleanUtils.java 491689 2007-01-01 23:18:58Z elecharny $
036 */
037 public class BooleanUtils
038 {
039 private static final Integer INTEGER_ZERO = Integer.valueOf( 0 );
040
041 private static final Integer INTEGER_ONE = Integer.valueOf( 1 );
042
043
044 /**
045 * <p>
046 * <code>BooleanUtils</code> instances should NOT be constructed in
047 * standard programming. Instead, the class should be used as
048 * <code>BooleanUtils.toBooleanObject(true);</code>.
049 * </p>
050 * <p>
051 * This constructor is public to permit tools that require a JavaBean
052 * instance to operate.
053 * </p>
054 */
055 public BooleanUtils()
056 {
057 }
058
059
060 // Boolean utilities
061 // --------------------------------------------------------------------------
062 /**
063 * <p>
064 * Negates the specified boolean.
065 * </p>
066 * <p>
067 * If <code>null</code> is passed in, <code>null</code> will be
068 * returned.
069 * </p>
070 *
071 * <pre>
072 * BooleanUtils.negate( Boolean.TRUE ) = Boolean.FALSE;
073 * BooleanUtils.negate( Boolean.FALSE ) = Boolean.TRUE;
074 * BooleanUtils.negate( null ) = null;
075 * </pre>
076 *
077 * @param bool
078 * the Boolean to negate, may be null
079 * @return the negated Boolean, or <code>null</code> if <code>null</code>
080 * input
081 */
082 public static Boolean negate( Boolean bool )
083 {
084 if ( bool == null )
085 {
086 return null;
087 }
088 return ( bool.booleanValue() ? Boolean.FALSE : Boolean.TRUE );
089 }
090
091
092 // boolean Boolean methods
093 // -----------------------------------------------------------------------
094 /**
095 * <p>
096 * Boolean factory that avoids creating new Boolean objecs all the time.
097 * </p>
098 * <p>
099 * This method was added to JDK1.4 but is available here for earlier JDKs.
100 * </p>
101 *
102 * <pre>
103 * BooleanUtils.toBooleanObject(false) = Boolean.FALSE
104 * BooleanUtils.toBooleanObject(true) = Boolean.TRUE
105 * </pre>
106 *
107 * @param bool
108 * the boolean to convert
109 * @return Boolean.TRUE or Boolean.FALSE as appropriate
110 */
111 public static Boolean toBooleanObject( boolean bool )
112 {
113 return ( bool ? Boolean.TRUE : Boolean.FALSE );
114 }
115
116
117 /**
118 * <p>
119 * Converts a Boolean to a boolean handling <code>null</code> by returning
120 * <code>false</code>.
121 * </p>
122 *
123 * <pre>
124 * BooleanUtils.toBoolean(Boolean.TRUE) = true
125 * BooleanUtils.toBoolean(Boolean.FALSE) = false
126 * BooleanUtils.toBoolean(null) = false
127 * </pre>
128 *
129 * @param bool
130 * the boolean to convert
131 * @return <code>true</code> or <code>false</code>, <code>null</code>
132 * returns <code>false</code>
133 */
134 public static boolean toBoolean( Boolean bool )
135 {
136 if ( bool == null )
137 {
138 return false;
139 }
140 return ( bool.booleanValue() ? true : false );
141 }
142
143
144 /**
145 * <p>
146 * Converts a Boolean to a boolean handling <code>null</code>.
147 * </p>
148 *
149 * <pre>
150 * BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
151 * BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
152 * BooleanUtils.toBooleanDefaultIfNull(null, true) = true
153 * </pre>
154 *
155 * @param bool
156 * the boolean to convert
157 * @param valueIfNull
158 * the boolean value to return if <code>null</code>
159 * @return <code>true</code> or <code>false</code>
160 */
161 public static boolean toBooleanDefaultIfNull( Boolean bool, boolean valueIfNull )
162 {
163 if ( bool == null )
164 {
165 return valueIfNull;
166 }
167 return ( bool.booleanValue() ? true : false );
168 }
169
170
171 // Integer to Boolean methods
172 // -----------------------------------------------------------------------
173 /**
174 * <p>
175 * Converts an int to a boolean using the convention that <code>zero</code>
176 * is <code>false</code>.
177 * </p>
178 *
179 * <pre>
180 * BooleanUtils.toBoolean(0) = false
181 * BooleanUtils.toBoolean(1) = true
182 * BooleanUtils.toBoolean(2) = true
183 * </pre>
184 *
185 * @param value
186 * the int to convert
187 * @return <code>true</code> if non-zero, <code>false</code> if zero
188 */
189 public static boolean toBoolean( int value )
190 {
191 return ( value == 0 ? false : true );
192 }
193
194
195 /**
196 * <p>
197 * Converts an int to a Boolean using the convention that <code>zero</code>
198 * is <code>false</code>.
199 * </p>
200 *
201 * <pre>
202 * BooleanUtils.toBoolean(0) = Boolean.FALSE
203 * BooleanUtils.toBoolean(1) = Boolean.TRUE
204 * BooleanUtils.toBoolean(2) = Boolean.TRUE
205 * </pre>
206 *
207 * @param value
208 * the int to convert
209 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
210 * <code>null</code> if <code>null</code>
211 */
212 public static Boolean toBooleanObject( int value )
213 {
214 return ( value == 0 ? Boolean.FALSE : Boolean.TRUE );
215 }
216
217
218 /**
219 * <p>
220 * Converts an Integer to a Boolean using the convention that
221 * <code>zero</code> is <code>false</code>.
222 * </p>
223 * <p>
224 * <code>null</code> will be converted to <code>null</code>.
225 * </p>
226 *
227 * <pre>
228 * BooleanUtils.toBoolean(new Integer(0)) = Boolean.FALSE
229 * BooleanUtils.toBoolean(new Integer(1)) = Boolean.TRUE
230 * BooleanUtils.toBoolean(new Integer(null)) = null
231 * </pre>
232 *
233 * @param value
234 * the Integer to convert
235 * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
236 * <code>null</code> if <code>null</code> input
237 */
238 public static Boolean toBooleanObject( Integer value )
239 {
240 if ( value == null )
241 {
242 return null;
243 }
244 return ( value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE );
245 }
246
247
248 /**
249 * <p>
250 * Converts an int to a boolean specifying the conversion values.
251 * </p>
252 *
253 * <pre>
254 * BooleanUtils.toBoolean(0, 1, 0) = false
255 * BooleanUtils.toBoolean(1, 1, 0) = true
256 * BooleanUtils.toBoolean(2, 1, 2) = false
257 * BooleanUtils.toBoolean(2, 2, 0) = true
258 * </pre>
259 *
260 * @param value
261 * the Integer to convert
262 * @param trueValue
263 * the value to match for <code>true</code>
264 * @param falseValue
265 * the value to match for <code>false</code>
266 * @return <code>true</code> or <code>false</code>
267 * @throws IllegalArgumentException
268 * if no match
269 */
270 public static boolean toBoolean( int value, int trueValue, int falseValue )
271 {
272 if ( value == trueValue )
273 {
274 return true;
275 }
276 else if ( value == falseValue )
277 {
278 return false;
279 }
280 // no match
281 throw new IllegalArgumentException( "The Integer did not match either specified value" );
282 }
283
284
285 /**
286 * <p>
287 * Converts an Integer to a boolean specifying the conversion values.
288 * </p>
289 *
290 * <pre>
291 * BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
292 * BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
293 * BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
294 * BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
295 * BooleanUtils.toBoolean(null, null, new Integer(0)) = true
296 * </pre>
297 *
298 * @param value
299 * the Integer to convert
300 * @param trueValue
301 * the value to match for <code>true</code>, may be
302 * <code>null</code>
303 * @param falseValue
304 * the value to match for <code>false</code>, may be
305 * <code>null</code>
306 * @return <code>true</code> or <code>false</code>
307 * @throws IllegalArgumentException
308 * if no match
309 */
310 public static boolean toBoolean( Integer value, Integer trueValue, Integer falseValue )
311 {
312 if ( value == null )
313 {
314 if ( trueValue == null )
315 {
316 return true;
317 }
318 else if ( falseValue == null )
319 {
320 return false;
321 }
322 }
323 else if ( value.equals( trueValue ) )
324 {
325 return true;
326 }
327 else if ( value.equals( falseValue ) )
328 {
329 return false;
330 }
331 // no match
332 throw new IllegalArgumentException( "The Integer did not match either specified value" );
333 }
334
335
336 /**
337 * <p>
338 * Converts an int to a Boolean specifying the conversion values.
339 * </p>
340 *
341 * <pre>
342 * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
343 * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
344 * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
345 * </pre>
346 *
347 * @param value
348 * the Integer to convert
349 * @param trueValue
350 * the value to match for <code>true</code>
351 * @param falseValue
352 * the value to match for <code>false</code>
353 * @param nullValue
354 * the value to to match for <code>null</code>
355 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
356 * @throws IllegalArgumentException
357 * if no match
358 */
359 public static Boolean toBooleanObject( int value, int trueValue, int falseValue, int nullValue )
360 {
361 if ( value == trueValue )
362 {
363 return Boolean.TRUE;
364 }
365 else if ( value == falseValue )
366 {
367 return Boolean.FALSE;
368 }
369 else if ( value == nullValue )
370 {
371 return null;
372 }
373 // no match
374 throw new IllegalArgumentException( "The Integer did not match any specified value" );
375 }
376
377
378 /**
379 * <p>
380 * Converts an Integer to a Boolean specifying the conversion values.
381 * </p>
382 *
383 * <pre>
384 * BooleanUtils.toBooleanObject(new Integer(0), new Integer(0), new Integer(2), new Integer(3)) = Boolean.TRUE
385 * BooleanUtils.toBooleanObject(new Integer(2), new Integer(1), new Integer(2), new Integer(3)) = Boolean.FALSE
386 * BooleanUtils.toBooleanObject(new Integer(3), new Integer(1), new Integer(2), new Integer(3)) = null
387 * </pre>
388 *
389 * @param value
390 * the Integer to convert
391 * @param trueValue
392 * the value to match for <code>true</code>, may be
393 * <code>null</code>
394 * @param falseValue
395 * the value to match for <code>false</code>, may be
396 * <code>null</code>
397 * @param nullValue
398 * the value to to match for <code>null</code>, may be
399 * <code>null</code>
400 * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
401 * @throws IllegalArgumentException
402 * if no match
403 */
404 public static Boolean toBooleanObject( Integer value, Integer trueValue, Integer falseValue, Integer nullValue )
405 {
406 if ( value == null )
407 {
408 if ( trueValue == null )
409 {
410 return Boolean.TRUE;
411 }
412 else if ( falseValue == null )
413 {
414 return Boolean.FALSE;
415 }
416 else if ( nullValue == null )
417 {
418 return null;
419 }
420 }
421 else if ( value.equals( trueValue ) )
422 {
423 return Boolean.TRUE;
424 }
425 else if ( value.equals( falseValue ) )
426 {
427 return Boolean.FALSE;
428 }
429 else if ( value.equals( nullValue ) )
430 {
431 return null;
432 }
433 // no match
434 throw new IllegalArgumentException( "The Integer did not match any specified value" );
435 }
436
437
438 // Boolean to Integer methods
439 // -----------------------------------------------------------------------
440 /**
441 * <p>
442 * Converts a boolean to an int using the convention that <code>zero</code>
443 * is <code>false</code>.
444 * </p>
445 *
446 * <pre>
447 * BooleanUtils.toInteger(true) = 1
448 * BooleanUtils.toInteger(false) = 0
449 * </pre>
450 *
451 * @param bool
452 * the boolean to convert
453 * @return one if <code>true</code>, zero if <code>false</code>
454 */
455 public static int toInteger( boolean bool )
456 {
457 return ( bool ? 1 : 0 );
458 }
459
460
461 /**
462 * <p>
463 * Converts a boolean to an Integer using the convention that
464 * <code>zero</code> is <code>false</code>.
465 * </p>
466 *
467 * <pre>
468 * BooleanUtils.toIntegerObject(true) = new Integer(1)
469 * BooleanUtils.toIntegerObject(false) = new Integer(0)
470 * </pre>
471 *
472 * @param bool
473 * the boolean to convert
474 * @return one if <code>true</code>, zero if <code>false</code>
475 */
476 public static Integer toIntegerObject( boolean bool )
477 {
478 return ( bool ? INTEGER_ONE : INTEGER_ZERO );
479 }
480
481
482 /**
483 * <p>
484 * Converts a Boolean to a Integer using the convention that
485 * <code>zero</code> is <code>false</code>.
486 * </p>
487 * <p>
488 * <code>null</code> will be converted to <code>null</code>.
489 * </p>
490 *
491 * <pre>
492 * BooleanUtils.toIntegerObject(Boolean.TRUE) = new Integer(1)
493 * BooleanUtils.toIntegerObject(Boolean.FALSE) = new Integer(0)
494 * </pre>
495 *
496 * @param bool
497 * the Boolean to convert
498 * @return one if Boolean.TRUE, zero if Boolean.FALSE, <code>null</code>
499 * if <code>null</code>
500 */
501 public static Integer toIntegerObject( Boolean bool )
502 {
503 if ( bool == null )
504 {
505 return null;
506 }
507 return ( bool.booleanValue() ? INTEGER_ONE : INTEGER_ZERO );
508 }
509
510
511 /**
512 * <p>
513 * Converts a boolean to an int specifying the conversion values.
514 * </p>
515 *
516 * <pre>
517 * BooleanUtils.toInteger(true, 1, 0) = 1
518 * BooleanUtils.toInteger(false, 1, 0) = 0
519 * </pre>
520 *
521 * @param bool
522 * the to convert
523 * @param trueValue
524 * the value to return if <code>true</code>
525 * @param falseValue
526 * the value to return if <code>false</code>
527 * @return the appropriate value
528 */
529 public static int toInteger( boolean bool, int trueValue, int falseValue )
530 {
531 return ( bool ? trueValue : falseValue );
532 }
533
534
535 /**
536 * <p>
537 * Converts a Boolean to an int specifying the conversion values.
538 * </p>
539 *
540 * <pre>
541 * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
542 * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
543 * BooleanUtils.toInteger(null, 1, 0, 2) = 2
544 * </pre>
545 *
546 * @param bool
547 * the Boolean to convert
548 * @param trueValue
549 * the value to return if <code>true</code>
550 * @param falseValue
551 * the value to return if <code>false</code>
552 * @param nullValue
553 * the value to return if <code>null</code>
554 * @return the appropriate value
555 */
556 public static int toInteger( Boolean bool, int trueValue, int falseValue, int nullValue )
557 {
558 if ( bool == null )
559 {
560 return nullValue;
561 }
562 return ( bool.booleanValue() ? trueValue : falseValue );
563 }
564
565
566 /**
567 * <p>
568 * Converts a boolean to an Integer specifying the conversion values.
569 * </p>
570 *
571 * <pre>
572 * BooleanUtils.toIntegerObject(true, new Integer(1), new Integer(0)) = new Integer(1)
573 * BooleanUtils.toIntegerObject(false, new Integer(1), new Integer(0)) = new Integer(0)
574 * </pre>
575 *
576 * @param bool
577 * the to convert
578 * @param trueValue
579 * the value to return if <code>true</code>, may be
580 * <code>null</code>
581 * @param falseValue
582 * the value to return if <code>false</code>, may be
583 * <code>null</code>
584 * @return the appropriate value
585 */
586 public static Integer toIntegerObject( boolean bool, Integer trueValue, Integer falseValue )
587 {
588 return ( bool ? trueValue : falseValue );
589 }
590
591
592 /**
593 * <p>
594 * Converts a Boolean to an Integer specifying the conversion values.
595 * </p>
596 *
597 * <pre>
598 * BooleanUtils.toIntegerObject(Boolean.TRUE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(1)
599 * BooleanUtils.toIntegerObject(Boolean.FALSE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(0)
600 * BooleanUtils.toIntegerObject(null, new Integer(1), new Integer(0), new Integer(2)) = new Integer(2)
601 * </pre>
602 *
603 * @param bool
604 * the Boolean to convert
605 * @param trueValue
606 * the value to return if <code>true</code>, may be
607 * <code>null</code>
608 * @param falseValue
609 * the value to return if <code>false</code>, may be
610 * <code>null</code>
611 * @param nullValue
612 * the value to return if <code>null</code>, may be
613 * <code>null</code>
614 * @return the appropriate value
615 */
616 public static Integer toIntegerObject( Boolean bool, Integer trueValue, Integer falseValue, Integer nullValue )
617 {
618 if ( bool == null )
619 {
620 return nullValue;
621 }
622 return ( bool.booleanValue() ? trueValue : falseValue );
623 }
624
625
626 // String to Boolean methods
627 // -----------------------------------------------------------------------
628 /**
629 * <p>
630 * Converts a String to a Boolean.
631 * </p>
632 * <p>
633 * <code>'true'</code>, <code>'on'</code> or <code>'yes'</code> (case
634 * insensitive) will return <code>true</code>. <code>'false'</code>,
635 * <code>'off'</code> or <code>'no'</code> (case insensitive) will
636 * return <code>false</code>. Otherwise, <code>null</code> is returned.
637 * </p>
638 *
639 * <pre>
640 * BooleanUtils.toBooleanObject(null) = null
641 * BooleanUtils.toBooleanObject("true") = Boolean.TRUE
642 * BooleanUtils.toBooleanObject("false") = Boolean.FALSE
643 * BooleanUtils.toBooleanObject("on") = Boolean.TRUE
644 * BooleanUtils.toBooleanObject("ON") = Boolean.TRUE
645 * BooleanUtils.toBooleanObject("off") = Boolean.FALSE
646 * BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
647 * BooleanUtils.toBooleanObject("blue") = null
648 * </pre>
649 *
650 * @param str
651 * the String to check
652 * @return the Boolean value of the string, <code>null</code> if no match
653 * or <code>null</code> input
654 */
655 public static Boolean toBooleanObject( String str )
656 {
657 if ( "true".equalsIgnoreCase( str ) )
658 {
659 return Boolean.TRUE;
660 }
661 else if ( "false".equalsIgnoreCase( str ) )
662 {
663 return Boolean.FALSE;
664 }
665 else if ( "on".equalsIgnoreCase( str ) )
666 {
667 return Boolean.TRUE;
668 }
669 else if ( "off".equalsIgnoreCase( str ) )
670 {
671 return Boolean.FALSE;
672 }
673 else if ( "yes".equalsIgnoreCase( str ) )
674 {
675 return Boolean.TRUE;
676 }
677 else if ( "no".equalsIgnoreCase( str ) )
678 {
679 return Boolean.FALSE;
680 }
681 // no match
682 return null;
683 }
684
685
686 /**
687 * <p>
688 * Converts a String to a Boolean throwing an exception if no match.
689 * </p>
690 *
691 * <pre>
692 * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
693 * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
694 * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
695 * </pre>
696 *
697 * @param str
698 * the String to check
699 * @param trueString
700 * the String to match for <code>true</code> (case sensitive),
701 * may be <code>null</code>
702 * @param falseString
703 * the String to match for <code>false</code> (case sensitive),
704 * may be <code>null</code>
705 * @param nullString
706 * the String to match for <code>null</code> (case sensitive),
707 * may be <code>null</code>
708 * @return the Boolean value of the string, <code>null</code> if no match
709 * or <code>null</code> input
710 */
711 public static Boolean toBooleanObject( String str, String trueString, String falseString, String nullString )
712 {
713 if ( str == null )
714 {
715 if ( trueString == null )
716 {
717 return Boolean.TRUE;
718 }
719 else if ( falseString == null )
720 {
721 return Boolean.FALSE;
722 }
723 else if ( nullString == null )
724 {
725 return null;
726 }
727 }
728 else if ( str.equals( trueString ) )
729 {
730 return Boolean.TRUE;
731 }
732 else if ( str.equals( falseString ) )
733 {
734 return Boolean.FALSE;
735 }
736 else if ( str.equals( nullString ) )
737 {
738 return null;
739 }
740 // no match
741 throw new IllegalArgumentException( "The String did not match any specified value" );
742 }
743
744
745 // String to boolean methods
746 // -----------------------------------------------------------------------
747 /**
748 * <p>
749 * Converts a String to a boolean (optimised for performance).
750 * </p>
751 * <p>
752 * <code>'true'</code>, <code>'on'</code> or <code>'yes'</code> (case
753 * insensitive) will return <code>true</code>. Otherwise,
754 * <code>false</code> is returned.
755 * </p>
756 * <p>
757 * This method performs 4 times faster (JDK1.4) than
758 * <code>Boolean.valueOf(String)</code>. However, this method accepts
759 * 'on' and 'yes' as true values.
760 *
761 * <pre>
762 * BooleanUtils.toBoolean(null) = false
763 * BooleanUtils.toBoolean("true") = true
764 * BooleanUtils.toBoolean("TRUE") = true
765 * BooleanUtils.toBoolean("tRUe") = true
766 * BooleanUtils.toBoolean("on") = true
767 * BooleanUtils.toBoolean("yes") = true
768 * BooleanUtils.toBoolean("false") = false
769 * BooleanUtils.toBoolean("x gti") = false
770 * </pre>
771 *
772 * @param str
773 * the String to check
774 * @return the boolean value of the string, <code>false</code> if no match
775 */
776 public static boolean toBoolean( String str )
777 {
778 // Previously used equalsIgnoreCase, which was fast for interned 'true'.
779 // Non interned 'true' matched 15 times slower.
780 //
781 // Optimisation provides same performance as before for interned 'true'.
782 // Similar performance for null, 'false', and other strings not length
783 // 2/3/4.
784 // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
785 if ( "true".equals( str ) )
786 {
787 return true;
788 }
789 if ( str == null )
790 {
791 return false;
792 }
793 switch ( str.length() )
794 {
795 case 2:
796 {
797 char ch0 = str.charAt( 0 );
798 char ch1 = str.charAt( 1 );
799 return ( ch0 == 'o' || ch0 == 'O' ) && ( ch1 == 'n' || ch1 == 'N' );
800 }
801 case 3:
802 {
803 char ch = str.charAt( 0 );
804 if ( ch == 'y' )
805 {
806 return ( str.charAt( 1 ) == 'e' || str.charAt( 1 ) == 'E' )
807 && ( str.charAt( 2 ) == 's' || str.charAt( 2 ) == 'S' );
808 }
809 if ( ch == 'Y' )
810 {
811 return ( str.charAt( 1 ) == 'E' || str.charAt( 1 ) == 'e' )
812 && ( str.charAt( 2 ) == 'S' || str.charAt( 2 ) == 's' );
813 }
814 }
815 case 4:
816 {
817 char ch = str.charAt( 0 );
818 if ( ch == 't' )
819 {
820 return ( str.charAt( 1 ) == 'r' || str.charAt( 1 ) == 'R' )
821 && ( str.charAt( 2 ) == 'u' || str.charAt( 2 ) == 'U' )
822 && ( str.charAt( 3 ) == 'e' || str.charAt( 3 ) == 'E' );
823 }
824 if ( ch == 'T' )
825 {
826 return ( str.charAt( 1 ) == 'R' || str.charAt( 1 ) == 'r' )
827 && ( str.charAt( 2 ) == 'U' || str.charAt( 2 ) == 'u' )
828 && ( str.charAt( 3 ) == 'E' || str.charAt( 3 ) == 'e' );
829 }
830 }
831 }
832 return false;
833 }
834
835
836 /**
837 * <p>
838 * Converts a String to a Boolean throwing an exception if no match found.
839 * </p>
840 * <p>
841 * null is returned if there is no match.
842 * </p>
843 *
844 * <pre>
845 * BooleanUtils.toBoolean("true", "true", "false") = true
846 * BooleanUtils.toBoolean("false", "true", "false") = false
847 * </pre>
848 *
849 * @param str
850 * the String to check
851 * @param trueString
852 * the String to match for <code>true</code> (case sensitive),
853 * may be <code>null</code>
854 * @param falseString
855 * the String to match for <code>false</code> (case sensitive),
856 * may be <code>null</code>
857 * @return the boolean value of the string
858 * @throws IllegalArgumentException
859 * if the String doesn't match
860 */
861 public static boolean toBoolean( String str, String trueString, String falseString )
862 {
863 if ( str == null )
864 {
865 if ( trueString == null )
866 {
867 return true;
868 }
869 else if ( falseString == null )
870 {
871 return false;
872 }
873 }
874 else if ( str.equals( trueString ) )
875 {
876 return true;
877 }
878 else if ( str.equals( falseString ) )
879 {
880 return false;
881 }
882 // no match
883 throw new IllegalArgumentException( "The String did not match either specified value" );
884 }
885
886
887 // Boolean to String methods
888 // -----------------------------------------------------------------------
889 /**
890 * <p>
891 * Converts a Boolean to a String returning <code>'true'</code>,
892 * <code>'false'</code>, or <code>null</code>.
893 * </p>
894 *
895 * <pre>
896 * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
897 * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
898 * BooleanUtils.toStringTrueFalse(null) = null;
899 * </pre>
900 *
901 * @param bool
902 * the Boolean to check
903 * @return <code>'true'</code>, <code>'false'</code>, or
904 * <code>null</code>
905 */
906 public static String toStringTrueFalse( Boolean bool )
907 {
908 return toString( bool, "true", "false", null );
909 }
910
911
912 /**
913 * <p>
914 * Converts a Boolean to a String returning <code>'on'</code>,
915 * <code>'off'</code>, or <code>null</code>.
916 * </p>
917 *
918 * <pre>
919 * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
920 * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
921 * BooleanUtils.toStringOnOff(null) = null;
922 * </pre>
923 *
924 * @param bool
925 * the Boolean to check
926 * @return <code>'on'</code>, <code>'off'</code>, or <code>null</code>
927 */
928 public static String toStringOnOff( Boolean bool )
929 {
930 return toString( bool, "on", "off", null );
931 }
932
933
934 /**
935 * <p>
936 * Converts a Boolean to a String returning <code>'yes'</code>,
937 * <code>'no'</code>, or <code>null</code>.
938 * </p>
939 *
940 * <pre>
941 * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
942 * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
943 * BooleanUtils.toStringYesNo(null) = null;
944 * </pre>
945 *
946 * @param bool
947 * the Boolean to check
948 * @return <code>'yes'</code>, <code>'no'</code>, or <code>null</code>
949 */
950 public static String toStringYesNo( Boolean bool )
951 {
952 return toString( bool, "yes", "no", null );
953 }
954
955
956 /**
957 * <p>
958 * Converts a Boolean to a String returning one of the input Strings.
959 * </p>
960 *
961 * <pre>
962 * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
963 * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
964 * BooleanUtils.toString(null, "true", "false", null) = null;
965 * </pre>
966 *
967 * @param bool
968 * the Boolean to check
969 * @param trueString
970 * the String to return if <code>true</code>, may be
971 * <code>null</code>
972 * @param falseString
973 * the String to return if <code>false</code>, may be
974 * <code>null</code>
975 * @param nullString
976 * the String to return if <code>null</code>, may be
977 * <code>null</code>
978 * @return one of the three input Strings
979 */
980 public static String toString( Boolean bool, String trueString, String falseString, String nullString )
981 {
982 if ( bool == null )
983 {
984 return nullString;
985 }
986 return ( bool.booleanValue() ? trueString : falseString );
987 }
988
989
990 // boolean to String methods
991 // -----------------------------------------------------------------------
992 /**
993 * <p>
994 * Converts a boolean to a String returning <code>'true'</code> or
995 * <code>'false'</code>.
996 * </p>
997 *
998 * <pre>
999 * BooleanUtils.toStringTrueFalse(true) = "true"
1000 * BooleanUtils.toStringTrueFalse(false) = "false"
1001 * </pre>
1002 *
1003 * @param bool
1004 * the Boolean to check
1005 * @return <code>'true'</code>, <code>'false'</code>, or
1006 * <code>null</code>
1007 */
1008 public static String toStringTrueFalse( boolean bool )
1009 {
1010 return toString( bool, "true", "false" );
1011 }
1012
1013
1014 /**
1015 * <p>
1016 * Converts a boolean to a String returning <code>'on'</code> or
1017 * <code>'off'</code>.
1018 * </p>
1019 *
1020 * <pre>
1021 * BooleanUtils.toStringOnOff(true) = "on"
1022 * BooleanUtils.toStringOnOff(false) = "off"
1023 * </pre>
1024 *
1025 * @param bool
1026 * the Boolean to check
1027 * @return <code>'on'</code>, <code>'off'</code>, or <code>null</code>
1028 */
1029 public static String toStringOnOff( boolean bool )
1030 {
1031 return toString( bool, "on", "off" );
1032 }
1033
1034
1035 /**
1036 * <p>
1037 * Converts a boolean to a String returning <code>'yes'</code> or
1038 * <code>'no'</code>.
1039 * </p>
1040 *
1041 * <pre>
1042 * BooleanUtils.toStringYesNo(true) = "yes"
1043 * BooleanUtils.toStringYesNo(false) = "no"
1044 * </pre>
1045 *
1046 * @param bool
1047 * the Boolean to check
1048 * @return <code>'yes'</code>, <code>'no'</code>, or <code>null</code>
1049 */
1050 public static String toStringYesNo( boolean bool )
1051 {
1052 return toString( bool, "yes", "no" );
1053 }
1054
1055
1056 /**
1057 * <p>
1058 * Converts a boolean to a String returning one of the input Strings.
1059 * </p>
1060 *
1061 * <pre>
1062 * BooleanUtils.toString(true, "true", "false") = "true"
1063 * BooleanUtils.toString(false, "true", "false") = "false"
1064 * </pre>
1065 *
1066 * @param bool
1067 * the Boolean to check
1068 * @param trueString
1069 * the String to return if <code>true</code>, may be
1070 * <code>null</code>
1071 * @param falseString
1072 * the String to return if <code>false</code>, may be
1073 * <code>null</code>
1074 * @return one of the two input Strings
1075 */
1076 public static String toString( boolean bool, String trueString, String falseString )
1077 {
1078 return ( bool ? trueString : falseString );
1079 }
1080
1081
1082 // xor methods
1083 // ----------------------------------------------------------------------
1084 /**
1085 * <p>
1086 * Performs an xor on a set of booleans.
1087 * </p>
1088 *
1089 * <pre>
1090 * BooleanUtils.xor(new boolean[] { true, true }) = false
1091 * BooleanUtils.xor(new boolean[] { false, false }) = false
1092 * BooleanUtils.xor(new boolean[] { true, false }) = true
1093 * </pre>
1094 *
1095 * @param array
1096 * an array of <code>boolean<code>s
1097 * @return <code>true</code> if the xor is successful.
1098 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
1099 * @throws IllegalArgumentException if <code>array</code> is empty.
1100 */
1101 public static boolean xor( boolean[] array )
1102 {
1103 // Validates input
1104 if ( array == null )
1105 {
1106 throw new IllegalArgumentException( "The Array must not be null" );
1107 }
1108 else if ( array.length == 0 )
1109 {
1110 throw new IllegalArgumentException( "Array is empty" );
1111 }
1112
1113 // Loops through array, comparing each item
1114 int trueCount = 0;
1115 for ( int i = 0; i < array.length; i++ )
1116 {
1117 // If item is true, and trueCount is < 1, increments count
1118 // Else, xor fails
1119 if ( array[i] )
1120 {
1121 if ( trueCount < 1 )
1122 {
1123 trueCount++;
1124 }
1125 else
1126 {
1127 return false;
1128 }
1129 }
1130 }
1131
1132 // Returns true if there was exactly 1 true item
1133 return trueCount == 1;
1134 }
1135
1136
1137 /**
1138 * <p>
1139 * Performs an xor on an array of Booleans.
1140 * </p>
1141 *
1142 * <pre>
1143 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
1144 * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
1145 * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
1146 * </pre>
1147 *
1148 * @param array
1149 * an array of <code>Boolean<code>s
1150 * @return <code>true</code> if the xor is successful.
1151 * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
1152 * @throws IllegalArgumentException if <code>array</code> is empty.
1153 * @throws IllegalArgumentException if <code>array</code> contains a <code>null</code>
1154 */
1155 public static Boolean xor( Boolean[] array )
1156 {
1157 if ( array == null )
1158 {
1159 throw new IllegalArgumentException( "The Array must not be null" );
1160 }
1161 else if ( array.length == 0 )
1162 {
1163 throw new IllegalArgumentException( "Array is empty" );
1164 }
1165 boolean[] primitive = null;
1166 try
1167 {
1168 primitive = ArrayUtils.toPrimitive( array );
1169 }
1170 catch ( NullPointerException ex )
1171 {
1172 throw new IllegalArgumentException( "The array must not contain any null elements" );
1173 }
1174 return ( xor( primitive ) ? Boolean.TRUE : Boolean.FALSE );
1175 }
1176
1177 }