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 Stephen Colebourne
029: * @author Matthew Hawthorne
030: * @author Gary Gregory
031: * @since 2.0
032: * @version $Id: BooleanUtils.java 492378 2007-01-04 01:31:24Z scolebourne $
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,
203: boolean valueIfNull) {
204: if (bool == null) {
205: return valueIfNull;
206: }
207: return bool.booleanValue() ? true : false;
208: }
209:
210: // Integer to Boolean methods
211: //-----------------------------------------------------------------------
212: /**
213: * <p>Converts an int to a boolean using the convention that <code>zero</code>
214: * is <code>false</code>.</p>
215: *
216: * <pre>
217: * BooleanUtils.toBoolean(0) = false
218: * BooleanUtils.toBoolean(1) = true
219: * BooleanUtils.toBoolean(2) = true
220: * </pre>
221: *
222: * @param value the int to convert
223: * @return <code>true</code> if non-zero, <code>false</code>
224: * if zero
225: */
226: public static boolean toBoolean(int value) {
227: return value == 0 ? false : true;
228: }
229:
230: /**
231: * <p>Converts an int to a Boolean using the convention that <code>zero</code>
232: * is <code>false</code>.</p>
233: *
234: * <pre>
235: * BooleanUtils.toBoolean(0) = Boolean.FALSE
236: * BooleanUtils.toBoolean(1) = Boolean.TRUE
237: * BooleanUtils.toBoolean(2) = Boolean.TRUE
238: * </pre>
239: *
240: * @param value the int to convert
241: * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
242: * <code>null</code> if <code>null</code>
243: */
244: public static Boolean toBooleanObject(int value) {
245: return value == 0 ? Boolean.FALSE : Boolean.TRUE;
246: }
247:
248: /**
249: * <p>Converts an Integer to a Boolean using the convention that <code>zero</code>
250: * is <code>false</code>.</p>
251: *
252: * <p><code>null</code> will be converted to <code>null</code>.</p>
253: *
254: * <pre>
255: * BooleanUtils.toBoolean(new Integer(0)) = Boolean.FALSE
256: * BooleanUtils.toBoolean(new Integer(1)) = Boolean.TRUE
257: * BooleanUtils.toBoolean(new Integer(null)) = null
258: * </pre>
259: *
260: * @param value the Integer to convert
261: * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero,
262: * <code>null</code> if <code>null</code> input
263: */
264: public static Boolean toBooleanObject(Integer value) {
265: if (value == null) {
266: return null;
267: }
268: return value.intValue() == 0 ? Boolean.FALSE : Boolean.TRUE;
269: }
270:
271: /**
272: * <p>Converts an int to a boolean specifying the conversion values.</p>
273: *
274: * <pre>
275: * BooleanUtils.toBoolean(0, 1, 0) = false
276: * BooleanUtils.toBoolean(1, 1, 0) = true
277: * BooleanUtils.toBoolean(2, 1, 2) = false
278: * BooleanUtils.toBoolean(2, 2, 0) = true
279: * </pre>
280: *
281: * @param value the Integer to convert
282: * @param trueValue the value to match for <code>true</code>
283: * @param falseValue the value to match for <code>false</code>
284: * @return <code>true</code> or <code>false</code>
285: * @throws IllegalArgumentException if no match
286: */
287: public static boolean toBoolean(int value, int trueValue,
288: int falseValue) {
289: if (value == trueValue) {
290: return true;
291: } else if (value == falseValue) {
292: return false;
293: }
294: // no match
295: throw new IllegalArgumentException(
296: "The Integer did not match either specified value");
297: }
298:
299: /**
300: * <p>Converts an Integer to a boolean specifying the conversion values.</p>
301: *
302: * <pre>
303: * BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
304: * BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
305: * BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
306: * BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
307: * BooleanUtils.toBoolean(null, null, new Integer(0)) = true
308: * </pre>
309: *
310: * @param value the Integer to convert
311: * @param trueValue the value to match for <code>true</code>,
312: * may be <code>null</code>
313: * @param falseValue the value to match for <code>false</code>,
314: * may be <code>null</code>
315: * @return <code>true</code> or <code>false</code>
316: * @throws IllegalArgumentException if no match
317: */
318: public static boolean toBoolean(Integer value, Integer trueValue,
319: Integer falseValue) {
320: if (value == null) {
321: if (trueValue == null) {
322: return true;
323: } else if (falseValue == null) {
324: return false;
325: }
326: } else if (value.equals(trueValue)) {
327: return true;
328: } else if (value.equals(falseValue)) {
329: return false;
330: }
331: // no match
332: throw new IllegalArgumentException(
333: "The Integer did not match either specified value");
334: }
335:
336: /**
337: * <p>Converts an int to a Boolean specifying the conversion values.</p>
338: *
339: * <pre>
340: * BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
341: * BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
342: * BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
343: * </pre>
344: *
345: * @param value the Integer to convert
346: * @param trueValue the value to match for <code>true</code>
347: * @param falseValue the value to match for <code>false</code>
348: * @param nullValue the value to to match for <code>null</code>
349: * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
350: * @throws IllegalArgumentException if no match
351: */
352: public static Boolean toBooleanObject(int value, int trueValue,
353: int falseValue, int nullValue) {
354: if (value == trueValue) {
355: return Boolean.TRUE;
356: } else if (value == falseValue) {
357: return Boolean.FALSE;
358: } else if (value == nullValue) {
359: return null;
360: }
361: // no match
362: throw new IllegalArgumentException(
363: "The Integer did not match any specified value");
364: }
365:
366: /**
367: * <p>Converts an Integer to a Boolean specifying the conversion values.</p>
368: *
369: * <pre>
370: * BooleanUtils.toBooleanObject(new Integer(0), new Integer(0), new Integer(2), new Integer(3)) = Boolean.TRUE
371: * BooleanUtils.toBooleanObject(new Integer(2), new Integer(1), new Integer(2), new Integer(3)) = Boolean.FALSE
372: * BooleanUtils.toBooleanObject(new Integer(3), new Integer(1), new Integer(2), new Integer(3)) = null
373: * </pre>
374: *
375: * @param value the Integer to convert
376: * @param trueValue the value to match for <code>true</code>,
377: * may be <code>null</code>
378: * @param falseValue the value to match for <code>false</code>,
379: * may be <code>null</code>
380: * @param nullValue the value to to match for <code>null</code>,
381: * may be <code>null</code>
382: * @return Boolean.TRUE, Boolean.FALSE, or <code>null</code>
383: * @throws IllegalArgumentException if no match
384: */
385: public static Boolean toBooleanObject(Integer value,
386: Integer trueValue, Integer falseValue, Integer nullValue) {
387: if (value == null) {
388: if (trueValue == null) {
389: return Boolean.TRUE;
390: } else if (falseValue == null) {
391: return Boolean.FALSE;
392: } else if (nullValue == null) {
393: return null;
394: }
395: } else if (value.equals(trueValue)) {
396: return Boolean.TRUE;
397: } else if (value.equals(falseValue)) {
398: return Boolean.FALSE;
399: } else if (value.equals(nullValue)) {
400: return null;
401: }
402: // no match
403: throw new IllegalArgumentException(
404: "The Integer did not match any specified value");
405: }
406:
407: // Boolean to Integer methods
408: //-----------------------------------------------------------------------
409: /**
410: * <p>Converts a boolean to an int using the convention that
411: * <code>zero</code> is <code>false</code>.</p>
412: *
413: * <pre>
414: * BooleanUtils.toInteger(true) = 1
415: * BooleanUtils.toInteger(false) = 0
416: * </pre>
417: *
418: * @param bool the boolean to convert
419: * @return one if <code>true</code>, zero if <code>false</code>
420: */
421: public static int toInteger(boolean bool) {
422: return bool ? 1 : 0;
423: }
424:
425: /**
426: * <p>Converts a boolean to an Integer using the convention that
427: * <code>zero</code> is <code>false</code>.</p>
428: *
429: * <pre>
430: * BooleanUtils.toIntegerObject(true) = new Integer(1)
431: * BooleanUtils.toIntegerObject(false) = new Integer(0)
432: * </pre>
433: *
434: * @param bool the boolean to convert
435: * @return one if <code>true</code>, zero if <code>false</code>
436: */
437: public static Integer toIntegerObject(boolean bool) {
438: return bool ? NumberUtils.INTEGER_ONE
439: : NumberUtils.INTEGER_ZERO;
440: }
441:
442: /**
443: * <p>Converts a Boolean to a Integer using the convention that
444: * <code>zero</code> is <code>false</code>.</p>
445: *
446: * <p><code>null</code> will be converted to <code>null</code>.</p>
447: *
448: * <pre>
449: * BooleanUtils.toIntegerObject(Boolean.TRUE) = new Integer(1)
450: * BooleanUtils.toIntegerObject(Boolean.FALSE) = new Integer(0)
451: * </pre>
452: *
453: * @param bool the Boolean to convert
454: * @return one if Boolean.TRUE, zero if Boolean.FALSE, <code>null</code> if <code>null</code>
455: */
456: public static Integer toIntegerObject(Boolean bool) {
457: if (bool == null) {
458: return null;
459: }
460: return bool.booleanValue() ? NumberUtils.INTEGER_ONE
461: : NumberUtils.INTEGER_ZERO;
462: }
463:
464: /**
465: * <p>Converts a boolean to an int specifying the conversion values.</p>
466: *
467: * <pre>
468: * BooleanUtils.toInteger(true, 1, 0) = 1
469: * BooleanUtils.toInteger(false, 1, 0) = 0
470: * </pre>
471: *
472: * @param bool the to convert
473: * @param trueValue the value to return if <code>true</code>
474: * @param falseValue the value to return if <code>false</code>
475: * @return the appropriate value
476: */
477: public static int toInteger(boolean bool, int trueValue,
478: int falseValue) {
479: return bool ? trueValue : falseValue;
480: }
481:
482: /**
483: * <p>Converts a Boolean to an int specifying the conversion values.</p>
484: *
485: * <pre>
486: * BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2) = 1
487: * BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
488: * BooleanUtils.toInteger(null, 1, 0, 2) = 2
489: * </pre>
490: *
491: * @param bool the Boolean to convert
492: * @param trueValue the value to return if <code>true</code>
493: * @param falseValue the value to return if <code>false</code>
494: * @param nullValue the value to return if <code>null</code>
495: * @return the appropriate value
496: */
497: public static int toInteger(Boolean bool, int trueValue,
498: int falseValue, int nullValue) {
499: if (bool == null) {
500: return nullValue;
501: }
502: return bool.booleanValue() ? trueValue : falseValue;
503: }
504:
505: /**
506: * <p>Converts a boolean to an Integer specifying the conversion values.</p>
507: *
508: * <pre>
509: * BooleanUtils.toIntegerObject(true, new Integer(1), new Integer(0)) = new Integer(1)
510: * BooleanUtils.toIntegerObject(false, new Integer(1), new Integer(0)) = new Integer(0)
511: * </pre>
512: *
513: * @param bool the to convert
514: * @param trueValue the value to return if <code>true</code>,
515: * may be <code>null</code>
516: * @param falseValue the value to return if <code>false</code>,
517: * may be <code>null</code>
518: * @return the appropriate value
519: */
520: public static Integer toIntegerObject(boolean bool,
521: Integer trueValue, Integer falseValue) {
522: return bool ? trueValue : falseValue;
523: }
524:
525: /**
526: * <p>Converts a Boolean to an Integer specifying the conversion values.</p>
527: *
528: * <pre>
529: * BooleanUtils.toIntegerObject(Boolean.TRUE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(1)
530: * BooleanUtils.toIntegerObject(Boolean.FALSE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(0)
531: * BooleanUtils.toIntegerObject(null, new Integer(1), new Integer(0), new Integer(2)) = new Integer(2)
532: * </pre>
533: *
534: * @param bool the Boolean to convert
535: * @param trueValue the value to return if <code>true</code>,
536: * may be <code>null</code>
537: * @param falseValue the value to return if <code>false</code>,
538: * may be <code>null</code>
539: * @param nullValue the value to return if <code>null</code>,
540: * may be <code>null</code>
541: * @return the appropriate value
542: */
543: public static Integer toIntegerObject(Boolean bool,
544: Integer trueValue, Integer falseValue, Integer nullValue) {
545: if (bool == null) {
546: return nullValue;
547: }
548: return bool.booleanValue() ? trueValue : falseValue;
549: }
550:
551: // String to Boolean methods
552: //-----------------------------------------------------------------------
553: /**
554: * <p>Converts a String to a Boolean.</p>
555: *
556: * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
557: * (case insensitive) will return <code>true</code>.
558: * <code>'false'</code>, <code>'off'</code> or <code>'no'</code>
559: * (case insensitive) will return <code>false</code>.
560: * Otherwise, <code>null</code> is returned.</p>
561: *
562: * <pre>
563: * BooleanUtils.toBooleanObject(null) = null
564: * BooleanUtils.toBooleanObject("true") = Boolean.TRUE
565: * BooleanUtils.toBooleanObject("false") = Boolean.FALSE
566: * BooleanUtils.toBooleanObject("on") = Boolean.TRUE
567: * BooleanUtils.toBooleanObject("ON") = Boolean.TRUE
568: * BooleanUtils.toBooleanObject("off") = Boolean.FALSE
569: * BooleanUtils.toBooleanObject("oFf") = Boolean.FALSE
570: * BooleanUtils.toBooleanObject("blue") = null
571: * </pre>
572: *
573: * @param str the String to check
574: * @return the Boolean value of the string,
575: * <code>null</code> if no match or <code>null</code> input
576: */
577: public static Boolean toBooleanObject(String str) {
578: if ("true".equalsIgnoreCase(str)) {
579: return Boolean.TRUE;
580: } else if ("false".equalsIgnoreCase(str)) {
581: return Boolean.FALSE;
582: } else if ("on".equalsIgnoreCase(str)) {
583: return Boolean.TRUE;
584: } else if ("off".equalsIgnoreCase(str)) {
585: return Boolean.FALSE;
586: } else if ("yes".equalsIgnoreCase(str)) {
587: return Boolean.TRUE;
588: } else if ("no".equalsIgnoreCase(str)) {
589: return Boolean.FALSE;
590: }
591: // no match
592: return null;
593: }
594:
595: /**
596: * <p>Converts a String to a Boolean throwing an exception if no match.</p>
597: *
598: * <pre>
599: * BooleanUtils.toBooleanObject("true", "true", "false", "null") = Boolean.TRUE
600: * BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
601: * BooleanUtils.toBooleanObject("null", "true", "false", "null") = null
602: * </pre>
603: *
604: * @param str the String to check
605: * @param trueString the String to match for <code>true</code>
606: * (case sensitive), may be <code>null</code>
607: * @param falseString the String to match for <code>false</code>
608: * (case sensitive), may be <code>null</code>
609: * @param nullString the String to match for <code>null</code>
610: * (case sensitive), may be <code>null</code>
611: * @return the Boolean value of the string,
612: * <code>null</code> if no match or <code>null</code> input
613: */
614: public static Boolean toBooleanObject(String str,
615: String trueString, String falseString, String nullString) {
616: if (str == null) {
617: if (trueString == null) {
618: return Boolean.TRUE;
619: } else if (falseString == null) {
620: return Boolean.FALSE;
621: } else if (nullString == null) {
622: return null;
623: }
624: } else if (str.equals(trueString)) {
625: return Boolean.TRUE;
626: } else if (str.equals(falseString)) {
627: return Boolean.FALSE;
628: } else if (str.equals(nullString)) {
629: return null;
630: }
631: // no match
632: throw new IllegalArgumentException(
633: "The String did not match any specified value");
634: }
635:
636: // String to boolean methods
637: //-----------------------------------------------------------------------
638: /**
639: * <p>Converts a String to a boolean (optimised for performance).</p>
640: *
641: * <p><code>'true'</code>, <code>'on'</code> or <code>'yes'</code>
642: * (case insensitive) will return <code>true</code>. Otherwise,
643: * <code>false</code> is returned.</p>
644: *
645: * <p>This method performs 4 times faster (JDK1.4) than
646: * <code>Boolean.valueOf(String)</code>. However, this method accepts
647: * 'on' and 'yes' as true values.
648: *
649: * <pre>
650: * BooleanUtils.toBoolean(null) = false
651: * BooleanUtils.toBoolean("true") = true
652: * BooleanUtils.toBoolean("TRUE") = true
653: * BooleanUtils.toBoolean("tRUe") = true
654: * BooleanUtils.toBoolean("on") = true
655: * BooleanUtils.toBoolean("yes") = true
656: * BooleanUtils.toBoolean("false") = false
657: * BooleanUtils.toBoolean("x gti") = false
658: * </pre>
659: *
660: * @param str the String to check
661: * @return the boolean value of the string, <code>false</code> if no match
662: */
663: public static boolean toBoolean(String str) {
664: // Previously used equalsIgnoreCase, which was fast for interned 'true'.
665: // Non interned 'true' matched 15 times slower.
666: //
667: // Optimisation provides same performance as before for interned 'true'.
668: // Similar performance for null, 'false', and other strings not length 2/3/4.
669: // 'true'/'TRUE' match 4 times slower, 'tRUE'/'True' 7 times slower.
670: if (str == "true") {
671: return true;
672: }
673: if (str == null) {
674: return false;
675: }
676: switch (str.length()) {
677: case 2: {
678: char ch0 = str.charAt(0);
679: char ch1 = str.charAt(1);
680: return (ch0 == 'o' || ch0 == 'O')
681: && (ch1 == 'n' || ch1 == 'N');
682: }
683: case 3: {
684: char ch = str.charAt(0);
685: if (ch == 'y') {
686: return (str.charAt(1) == 'e' || str.charAt(1) == 'E')
687: && (str.charAt(2) == 's' || str.charAt(2) == 'S');
688: }
689: if (ch == 'Y') {
690: return (str.charAt(1) == 'E' || str.charAt(1) == 'e')
691: && (str.charAt(2) == 'S' || str.charAt(2) == 's');
692: }
693: }
694: case 4: {
695: char ch = str.charAt(0);
696: if (ch == 't') {
697: return (str.charAt(1) == 'r' || str.charAt(1) == 'R')
698: && (str.charAt(2) == 'u' || str.charAt(2) == 'U')
699: && (str.charAt(3) == 'e' || str.charAt(3) == 'E');
700: }
701: if (ch == 'T') {
702: return (str.charAt(1) == 'R' || str.charAt(1) == 'r')
703: && (str.charAt(2) == 'U' || str.charAt(2) == 'u')
704: && (str.charAt(3) == 'E' || str.charAt(3) == 'e');
705: }
706: }
707: }
708: return false;
709: }
710:
711: // public static void main(String[] args) {
712: // long start = System.currentTimeMillis();
713: // boolean flag = true;
714: // int count = 0;
715: // for (int i = 0; i < 100000000; i++) {
716: // flag = toBoolean("YES");
717: // }
718: // long end = System.currentTimeMillis();
719: // System.out.println((end - start) + " " + flag + " " + count);
720: // }
721:
722: /**
723: * <p>Converts a String to a Boolean throwing an exception if no match found.</p>
724: *
725: * <p>null is returned if there is no match.</p>
726: *
727: * <pre>
728: * BooleanUtils.toBoolean("true", "true", "false") = true
729: * BooleanUtils.toBoolean("false", "true", "false") = false
730: * </pre>
731: *
732: * @param str the String to check
733: * @param trueString the String to match for <code>true</code>
734: * (case sensitive), may be <code>null</code>
735: * @param falseString the String to match for <code>false</code>
736: * (case sensitive), may be <code>null</code>
737: * @return the boolean value of the string
738: * @throws IllegalArgumentException if the String doesn't match
739: */
740: public static boolean toBoolean(String str, String trueString,
741: String falseString) {
742: if (str == null) {
743: if (trueString == null) {
744: return true;
745: } else if (falseString == null) {
746: return false;
747: }
748: } else if (str.equals(trueString)) {
749: return true;
750: } else if (str.equals(falseString)) {
751: return false;
752: }
753: // no match
754: throw new IllegalArgumentException(
755: "The String did not match either specified value");
756: }
757:
758: // Boolean to String methods
759: //-----------------------------------------------------------------------
760: /**
761: * <p>Converts a Boolean to a String returning <code>'true'</code>,
762: * <code>'false'</code>, or <code>null</code>.</p>
763: *
764: * <pre>
765: * BooleanUtils.toStringTrueFalse(Boolean.TRUE) = "true"
766: * BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
767: * BooleanUtils.toStringTrueFalse(null) = null;
768: * </pre>
769: *
770: * @param bool the Boolean to check
771: * @return <code>'true'</code>, <code>'false'</code>,
772: * or <code>null</code>
773: */
774: public static String toStringTrueFalse(Boolean bool) {
775: return toString(bool, "true", "false", null);
776: }
777:
778: /**
779: * <p>Converts a Boolean to a String returning <code>'on'</code>,
780: * <code>'off'</code>, or <code>null</code>.</p>
781: *
782: * <pre>
783: * BooleanUtils.toStringOnOff(Boolean.TRUE) = "on"
784: * BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
785: * BooleanUtils.toStringOnOff(null) = null;
786: * </pre>
787: *
788: * @param bool the Boolean to check
789: * @return <code>'on'</code>, <code>'off'</code>,
790: * or <code>null</code>
791: */
792: public static String toStringOnOff(Boolean bool) {
793: return toString(bool, "on", "off", null);
794: }
795:
796: /**
797: * <p>Converts a Boolean to a String returning <code>'yes'</code>,
798: * <code>'no'</code>, or <code>null</code>.</p>
799: *
800: * <pre>
801: * BooleanUtils.toStringYesNo(Boolean.TRUE) = "yes"
802: * BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
803: * BooleanUtils.toStringYesNo(null) = null;
804: * </pre>
805: *
806: * @param bool the Boolean to check
807: * @return <code>'yes'</code>, <code>'no'</code>,
808: * or <code>null</code>
809: */
810: public static String toStringYesNo(Boolean bool) {
811: return toString(bool, "yes", "no", null);
812: }
813:
814: /**
815: * <p>Converts a Boolean to a String returning one of the input Strings.</p>
816: *
817: * <pre>
818: * BooleanUtils.toString(Boolean.TRUE, "true", "false", null) = "true"
819: * BooleanUtils.toString(Boolean.FALSE, "true", "false", null) = "false"
820: * BooleanUtils.toString(null, "true", "false", null) = null;
821: * </pre>
822: *
823: * @param bool the Boolean to check
824: * @param trueString the String to return if <code>true</code>,
825: * may be <code>null</code>
826: * @param falseString the String to return if <code>false</code>,
827: * may be <code>null</code>
828: * @param nullString the String to return if <code>null</code>,
829: * may be <code>null</code>
830: * @return one of the three input Strings
831: */
832: public static String toString(Boolean bool, String trueString,
833: String falseString, String nullString) {
834: if (bool == null) {
835: return nullString;
836: }
837: return bool.booleanValue() ? trueString : falseString;
838: }
839:
840: // boolean to String methods
841: //-----------------------------------------------------------------------
842: /**
843: * <p>Converts a boolean to a String returning <code>'true'</code>
844: * or <code>'false'</code>.</p>
845: *
846: * <pre>
847: * BooleanUtils.toStringTrueFalse(true) = "true"
848: * BooleanUtils.toStringTrueFalse(false) = "false"
849: * </pre>
850: *
851: * @param bool the Boolean to check
852: * @return <code>'true'</code>, <code>'false'</code>,
853: * or <code>null</code>
854: */
855: public static String toStringTrueFalse(boolean bool) {
856: return toString(bool, "true", "false");
857: }
858:
859: /**
860: * <p>Converts a boolean to a String returning <code>'on'</code>
861: * or <code>'off'</code>.</p>
862: *
863: * <pre>
864: * BooleanUtils.toStringOnOff(true) = "on"
865: * BooleanUtils.toStringOnOff(false) = "off"
866: * </pre>
867: *
868: * @param bool the Boolean to check
869: * @return <code>'on'</code>, <code>'off'</code>,
870: * or <code>null</code>
871: */
872: public static String toStringOnOff(boolean bool) {
873: return toString(bool, "on", "off");
874: }
875:
876: /**
877: * <p>Converts a boolean to a String returning <code>'yes'</code>
878: * or <code>'no'</code>.</p>
879: *
880: * <pre>
881: * BooleanUtils.toStringYesNo(true) = "yes"
882: * BooleanUtils.toStringYesNo(false) = "no"
883: * </pre>
884: *
885: * @param bool the Boolean to check
886: * @return <code>'yes'</code>, <code>'no'</code>,
887: * or <code>null</code>
888: */
889: public static String toStringYesNo(boolean bool) {
890: return toString(bool, "yes", "no");
891: }
892:
893: /**
894: * <p>Converts a boolean to a String returning one of the input Strings.</p>
895: *
896: * <pre>
897: * BooleanUtils.toString(true, "true", "false") = "true"
898: * BooleanUtils.toString(false, "true", "false") = "false"
899: * </pre>
900: *
901: * @param bool the Boolean to check
902: * @param trueString the String to return if <code>true</code>,
903: * may be <code>null</code>
904: * @param falseString the String to return if <code>false</code>,
905: * may be <code>null</code>
906: * @return one of the two input Strings
907: */
908: public static String toString(boolean bool, String trueString,
909: String falseString) {
910: return bool ? trueString : falseString;
911: }
912:
913: // xor methods
914: // ----------------------------------------------------------------------
915: /**
916: * <p>Performs an xor on a set of booleans.</p>
917: *
918: * <pre>
919: * BooleanUtils.xor(new boolean[] { true, true }) = false
920: * BooleanUtils.xor(new boolean[] { false, false }) = false
921: * BooleanUtils.xor(new boolean[] { true, false }) = true
922: * </pre>
923: *
924: * @param array an array of <code>boolean<code>s
925: * @return <code>true</code> if the xor is successful.
926: * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
927: * @throws IllegalArgumentException if <code>array</code> is empty.
928: */
929: public static boolean xor(boolean[] array) {
930: // Validates input
931: if (array == null) {
932: throw new IllegalArgumentException(
933: "The Array must not be null");
934: } else if (array.length == 0) {
935: throw new IllegalArgumentException("Array is empty");
936: }
937:
938: // Loops through array, comparing each item
939: int trueCount = 0;
940: for (int i = 0; i < array.length; i++) {
941: // If item is true, and trueCount is < 1, increments count
942: // Else, xor fails
943: if (array[i]) {
944: if (trueCount < 1) {
945: trueCount++;
946: } else {
947: return false;
948: }
949: }
950: }
951:
952: // Returns true if there was exactly 1 true item
953: return trueCount == 1;
954: }
955:
956: /**
957: * <p>Performs an xor on an array of Booleans.</p>
958: *
959: * <pre>
960: * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE }) = Boolean.FALSE
961: * BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
962: * BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE }) = Boolean.TRUE
963: * </pre>
964: *
965: * @param array an array of <code>Boolean<code>s
966: * @return <code>true</code> if the xor is successful.
967: * @throws IllegalArgumentException if <code>array</code> is <code>null</code>
968: * @throws IllegalArgumentException if <code>array</code> is empty.
969: * @throws IllegalArgumentException if <code>array</code> contains a <code>null</code>
970: */
971: public static Boolean xor(Boolean[] array) {
972: if (array == null) {
973: throw new IllegalArgumentException(
974: "The Array must not be null");
975: } else if (array.length == 0) {
976: throw new IllegalArgumentException("Array is empty");
977: }
978: boolean[] primitive = null;
979: try {
980: primitive = ArrayUtils.toPrimitive(array);
981: } catch (NullPointerException ex) {
982: throw new IllegalArgumentException(
983: "The array must not contain any null elements");
984: }
985: return xor(primitive) ? Boolean.TRUE : Boolean.FALSE;
986: }
987:
988: }
|