From e645ec831f00eb3a05237c456372d7b07ee78466 Mon Sep 17 00:00:00 2001 From: Fredrik Westermarck Date: Tue, 23 Sep 2003 19:45:14 +0000 Subject: [PATCH] Added examples in javadoc. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137673 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/commons/lang/BooleanUtils.java | 204 +++++++++++++++++- 1 file changed, 196 insertions(+), 8 deletions(-) diff --git a/src/java/org/apache/commons/lang/BooleanUtils.java b/src/java/org/apache/commons/lang/BooleanUtils.java index e65096180..4b2a06fe1 100644 --- a/src/java/org/apache/commons/lang/BooleanUtils.java +++ b/src/java/org/apache/commons/lang/BooleanUtils.java @@ -66,7 +66,7 @@ * @author Matthew Hawthorne * @author Gary Gregory * @since 2.0 - * @version $Id: BooleanUtils.java,v 1.15 2003/09/07 14:32:34 psteitz Exp $ + * @version $Id: BooleanUtils.java,v 1.16 2003/09/23 19:45:14 fredrik Exp $ */ public class BooleanUtils { @@ -86,6 +86,12 @@ public BooleanUtils() { *

Negates the specified boolean.

* *

If null is passed in, null will be returned.

+ * + * 
+     *   BooleanUtils.negate(Boolean.TRUE)  = Boolean.FALSE;
+     *   BooleanUtils.negate(Boolean.FALSE) = Boolean.TRUE;
+     *   BooleanUtils.negate(null)          = null;
+     *
* * @param bool the Boolean to negate, may be null * @return the negated Boolean, or null if null input @@ -103,7 +109,12 @@ public static Boolean negate(Boolean bool) { *

Boolean factory that avoids creating new Boolean objecs all the time.

* *

This method was added to JDK1.4 but is available here for earlier JDKs.

- * + * + * 
+     *   BooleanUtils.toBooleanObject(false) = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject(true)  = Boolean.TRUE
+     *
+ * * @param bool the boolean to convert * @return Boolean.TRUE or Boolean.FALSE as appropriate */ @@ -114,7 +125,13 @@ public static Boolean toBooleanObject(boolean bool) { /** *

Converts a Boolean to a boolean handling null * by returning false.

- * + * + * 
+     *   BooleanUtils.toBoolean(Boolean.TRUE)  = true
+     *   BooleanUtils.toBoolean(Boolean.FALSE) = false
+     *   BooleanUtils.toBoolean(null)          = false
+     *
+ * * @param bool the boolean to convert * @return true or false, * null returns false @@ -129,6 +146,12 @@ public static boolean toBoolean(Boolean bool) { /** *

Converts a Boolean to a boolean handling null.

* + * 
+     *   BooleanUtils.toBooleanDefaultIfNull(Boolean.TRUE, false) = true
+     *   BooleanUtils.toBooleanDefaultIfNull(Boolean.FALSE, true) = false
+     *   BooleanUtils.toBooleanDefaultIfNull(null, true)          = true
+     *
+ * * @param bool the boolean to convert * @param valueIfNull the boolean value to return if null * @return true or false @@ -146,6 +169,12 @@ public static boolean toBooleanDefaultIfNull(Boolean bool, boolean valueIfNull) *

Converts an int to a boolean using the convention that zero * is false.

* + * 
+     *   BooleanUtils.toBoolean(0) = false
+     *   BooleanUtils.toBoolean(1) = true
+     *   BooleanUtils.toBoolean(2) = true
+     *
+ * * @param value the int to convert * @return true if non-zero, false * if zero @@ -158,6 +187,12 @@ public static boolean toBoolean(int value) { *

Converts an int to a Boolean using the convention that zero * is false.

* + * 
+     *   BooleanUtils.toBoolean(0) = Boolean.FALSE
+     *   BooleanUtils.toBoolean(1) = Boolean.TRUE
+     *   BooleanUtils.toBoolean(2) = Boolean.TRUE
+     *
+ * * @param value the int to convert * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero, * null if null @@ -171,7 +206,13 @@ public static Boolean toBooleanObject(int value) { * is false.

* *

null will be converted to null.

- * + * + * 
+     *   BooleanUtils.toBoolean(new Integer(0))    = Boolean.FALSE
+     *   BooleanUtils.toBoolean(new Integer(1))    = Boolean.TRUE
+     *   BooleanUtils.toBoolean(new Integer(null)) = null
+     *
+ * * @param value the Integer to convert * @return Boolean.TRUE if non-zero, Boolean.FALSE if zero, * null if null input @@ -186,6 +227,13 @@ public static Boolean toBooleanObject(Integer value) { /** *

Converts an int to a boolean specifying the conversion values.

* + * 
+     *   BooleanUtils.toBoolean(0, 1, 0) = false
+     *   BooleanUtils.toBoolean(1, 1, 0) = true
+     *   BooleanUtils.toBoolean(2, 1, 2) = false
+     *   BooleanUtils.toBoolean(2, 2, 0) = true
+     *
+ * * @param value the Integer to convert * @param trueValue the value to match for true * @param falseValue the value to match for false @@ -205,6 +253,14 @@ public static boolean toBoolean(int value, int trueValue, int falseValue) { /** *

Converts an Integer to a boolean specifying the conversion values.

* + * 
+     *   BooleanUtils.toBoolean(new Integer(0), new Integer(1), new Integer(0)) = false
+     *   BooleanUtils.toBoolean(new Integer(1), new Integer(1), new Integer(0)) = true
+     *   BooleanUtils.toBoolean(new Integer(2), new Integer(1), new Integer(2)) = false
+     *   BooleanUtils.toBoolean(new Integer(2), new Integer(2), new Integer(0)) = true
+     *   BooleanUtils.toBoolean(null, null, new Integer(0))                     = true
+     *
+ * * @param value the Integer to convert * @param trueValue the value to match for true, * may be null @@ -232,6 +288,12 @@ public static boolean toBoolean(Integer value, Integer trueValue, Integer falseV /** *

Converts an int to a Boolean specifying the conversion values.

* + * 
+     *   BooleanUtils.toBooleanObject(0, 0, 2, 3) = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject(2, 1, 2, 3) = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject(3, 1, 2, 3) = null
+     *
+ * * @param value the Integer to convert * @param trueValue the value to match for true * @param falseValue the value to match for false @@ -254,6 +316,12 @@ public static Boolean toBooleanObject(int value, int trueValue, int falseValue, /** *

Converts an Integer to a Boolean specifying the conversion values.

* + * 
+     *   BooleanUtils.toBooleanObject(new Integer(0), new Integer(0), new Integer(2), new Integer(3)) = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject(new Integer(2), new Integer(1), new Integer(2), new Integer(3)) = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject(new Integer(3), new Integer(1), new Integer(2), new Integer(3)) = null
+     *
+ * * @param value the Integer to convert * @param trueValue the value to match for true, * may be null @@ -289,7 +357,12 @@ public static Boolean toBooleanObject(Integer value, Integer trueValue, Integer /** *

Converts a boolean to an int using the convention that * zero is false.

- * + * + * 
+     *   BooleanUtils.toInteger(true)  = 1
+     *   BooleanUtils.toInteger(false) = 0
+     *
+ * * @param bool the boolean to convert * @return one if true, zero if false */ @@ -301,6 +374,11 @@ public static int toInteger(boolean bool) { *

Converts a boolean to an Integer using the convention that * zero is false.

* + * 
+     *   BooleanUtils.toIntegerObject(true)  = new Integer(1)
+     *   BooleanUtils.toIntegerObject(false) = new Integer(0)
+     *
+ * * @param bool the boolean to convert * @return one if true, zero if false */ @@ -311,9 +389,14 @@ public static Integer toIntegerObject(boolean bool) { /** *

Converts a Boolean to a Integer using the convention that * zero is false.

- * + * *

null will be converted to null.

- * + * + * 
+     *   BooleanUtils.toIntegerObject(Boolean.TRUE)  = new Integer(1)
+     *   BooleanUtils.toIntegerObject(Boolean.FALSE) = new Integer(0)
+     *
+ * * @param bool the Boolean to convert * @return one if Boolean.TRUE, zero if Boolean.FALSE, null if null */ @@ -327,6 +410,11 @@ public static Integer toIntegerObject(Boolean bool) { /** *

Converts a boolean to an int specifying the conversion values.

* + * 
+     *   BooleanUtils.toInteger(true, 1, 0)  = 1
+     *   BooleanUtils.toInteger(false, 1, 0) = 0
+     *
+ * * @param bool the to convert * @param trueValue the value to return if true * @param falseValue the value to return if false @@ -339,6 +427,12 @@ public static int toInteger(boolean bool, int trueValue, int falseValue) { /** *

Converts a Boolean to an int specifying the conversion values.

* + * 
+     *   BooleanUtils.toInteger(Boolean.TRUE, 1, 0, 2)  = 1
+     *   BooleanUtils.toInteger(Boolean.FALSE, 1, 0, 2) = 0
+     *   BooleanUtils.toInteger(null, 1, 0, 2)          = 2
+     *
+ * * @param bool the Boolean to convert * @param trueValue the value to return if true * @param falseValue the value to return if false @@ -355,6 +449,11 @@ public static int toInteger(Boolean bool, int trueValue, int falseValue, int nul /** *

Converts a boolean to an Integer specifying the conversion values.

* + * 
+     *   BooleanUtils.toIntegerObject(true, new Integer(1), new Integer(0))  = new Integer(1)
+     *   BooleanUtils.toIntegerObject(false, new Integer(1), new Integer(0)) = new Integer(0)
+     *
+ * * @param bool the to convert * @param trueValue the value to return if true, * may be null @@ -369,6 +468,12 @@ public static Integer toIntegerObject(boolean bool, Integer trueValue, Integer f /** *

Converts a Boolean to an Integer specifying the conversion values.

* + * 
+     *   BooleanUtils.toIntegerObject(Boolean.TRUE, new Integer(1), new Integer(0), new Integer(2))  = new Integer(1)
+     *   BooleanUtils.toIntegerObject(Boolean.FALSE, new Integer(1), new Integer(0), new Integer(2)) = new Integer(0)
+     *   BooleanUtils.toIntegerObject(null, new Integer(1), new Integer(0), new Integer(2))          = new Integer(2)
+     *
+ * * @param bool the Boolean to convert * @param trueValue the value to return if true, * may be null @@ -396,6 +501,15 @@ public static Integer toIntegerObject(Boolean bool, Integer trueValue, Integer f * (case insensitive) will return false. * Otherwise, null is returned.

* + * 
+     *   BooleanUtils.toBooleanObject("true")  = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject("false") = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject("on")    = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject("ON")    = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject("off")   = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject("oFf")   = Boolean.FALSE
+     *
+ * * @param str the String to check * @return the Boolean value of the string, * null if no match or null input @@ -421,6 +535,12 @@ public static Boolean toBooleanObject(String str) { /** *

Converts a String to a Boolean throwing an exception if no match.

* + * 
+     *   BooleanUtils.toBooleanObject("true", "true", "false", "null")  = Boolean.TRUE
+     *   BooleanUtils.toBooleanObject("false", "true", "false", "null") = Boolean.FALSE
+     *   BooleanUtils.toBooleanObject("null", "true", "false", "null")  = null
+     *
+ * * @param str the String to check * @param trueString the String to match for true * (case sensitive), may be null @@ -460,6 +580,13 @@ public static Boolean toBooleanObject(String str, String trueString, String fals * (case insensitive) will return true. Otherwise, * false is returned.

* + * 
+     *   BooleanUtils.toBoolean("true")  = true
+     *   BooleanUtils.toBoolean("on")    = true
+     *   BooleanUtils.toBoolean("yes")   = true
+     *   BooleanUtils.toBoolean("false") = false
+     *
+ * * @param str the String to check * @return the boolean value of the string, false if no match */ @@ -480,6 +607,11 @@ public static boolean toBoolean(String str) { * *

null is returned if there is no match.

* + * 
+     *   BooleanUtils.toBoolean("true", "true", "false")  = true
+     *   BooleanUtils.toBoolean("false", "true", "false") = false
+     *
+ * * @param str the String to check * @param trueString the String to match for true * (case sensitive), may be null @@ -510,6 +642,12 @@ public static boolean toBoolean(String str, String trueString, String falseStrin *

Converts a Boolean to a String returning 'true', * 'false', or null.

* + * 
+     *   BooleanUtils.toStringTrueFalse(Boolean.TRUE)  = "true"
+     *   BooleanUtils.toStringTrueFalse(Boolean.FALSE) = "false"
+     *   BooleanUtils.toStringTrueFalse(null)          = null;
+     *
+ * * @param bool the Boolean to check * @return 'true', 'false', * or null @@ -522,6 +660,12 @@ public static String toStringTrueFalse(Boolean bool) { *

Converts a Boolean to a String returning 'on', * 'off', or null.

* + * 
+     *   BooleanUtils.toStringOnOff(Boolean.TRUE)  = "on"
+     *   BooleanUtils.toStringOnOff(Boolean.FALSE) = "off"
+     *   BooleanUtils.toStringOnOff(null)          = null;
+     *
+ * * @param bool the Boolean to check * @return 'on', 'off', * or null @@ -534,6 +678,12 @@ public static String toStringOnOff(Boolean bool) { *

Converts a Boolean to a String returning 'yes', * 'no', or null.

* + * 
+     *   BooleanUtils.toStringYesNo(Boolean.TRUE)  = "yes"
+     *   BooleanUtils.toStringYesNo(Boolean.FALSE) = "no"
+     *   BooleanUtils.toStringYesNo(null)          = null;
+     *
+ * * @param bool the Boolean to check * @return 'yes', 'no', * or null @@ -545,6 +695,12 @@ public static String toStringYesNo(Boolean bool) { /** *

Converts a Boolean to a String returning one of the input Strings.

* + * 
+     *   BooleanUtils.toString(Boolean.TRUE, "true", "false", null)   = "true"
+     *   BooleanUtils.toString(Boolean.FALSE, "true", "false", null)  = "false"
+     *   BooleanUtils.toString(null, "true", "false", null)           = null;
+     *
+ * * @param bool the Boolean to check * @param trueString the String to return if true, * may be null @@ -567,6 +723,11 @@ public static String toString(Boolean bool, String trueString, String falseStrin *

Converts a boolean to a String returning 'true' * or 'false'.

* + * 
+     *   BooleanUtils.toStringTrueFalse(true)   = "true"
+     *   BooleanUtils.toStringTrueFalse(false)  = "false"
+     *
+ * * @param bool the Boolean to check * @return 'true', 'false', * or null @@ -579,6 +740,11 @@ public static String toStringTrueFalse(boolean bool) { *

Converts a boolean to a String returning 'on' * or 'off'.

* + * 
+     *   BooleanUtils.toStringOnOff(true)   = "on"
+     *   BooleanUtils.toStringOnOff(false)  = "off"
+     *
+ * * @param bool the Boolean to check * @return 'on', 'off', * or null @@ -591,6 +757,11 @@ public static String toStringOnOff(boolean bool) { *

Converts a boolean to a String returning 'yes' * or 'no'.

* + * 
+     *   BooleanUtils.toStringYesNo(true)   = "yes"
+     *   BooleanUtils.toStringYesNo(false)  = "no"
+     *
+ * * @param bool the Boolean to check * @return 'yes', 'no', * or null @@ -602,6 +773,11 @@ public static String toStringYesNo(boolean bool) { /** *

Converts a boolean to a String returning one of the input Strings.

* + * 
+     *   BooleanUtils.toString(true, "true", "false")   = "true"
+     *   BooleanUtils.toString(false, "true", "false")  = "false"
+     *
+ * * @param bool the Boolean to check * @param trueString the String to return if true, * may be null @@ -617,7 +793,13 @@ public static String toString(boolean bool, String trueString, String falseStrin // ---------------------------------------------------------------------- /** *

Performs an xor on a set of booleans.

- * + * + * 
+     *   BooleanUtils.xor(new boolean[] { true, true })   = false
+     *   BooleanUtils.xor(new boolean[] { false, false }) = false
+     *   BooleanUtils.xor(new boolean[] { true, false })  = true
+     *
+ * * @param array an array of booleans * @return true if the xor is successful. * @throws IllegalArgumentException if array is null @@ -652,6 +834,12 @@ public static boolean xor(boolean[] array) { /** *

Performs an xor on an array of Booleans.

* + * 
+     *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.TRUE })   = Boolean.FALSE
+     *   BooleanUtils.xor(new Boolean[] { Boolean.FALSE, Boolean.FALSE }) = Boolean.FALSE
+     *   BooleanUtils.xor(new Boolean[] { Boolean.TRUE, Boolean.FALSE })  = Boolean.TRUE
+     *
+ * * @param array an array of Booleans * @return true if the xor is successful. * @throws IllegalArgumentException if array is null