1 /*
   2  * Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import jdk.internal.HotSpotIntrinsicCandidate;
  29 
  30 /**
  31  * The Boolean class wraps a value of the primitive type
  32  * {@code boolean} in an object. An object of type
  33  * {@code Boolean} contains a single field whose type is
  34  * {@code boolean}.
  35  * <p>
  36  * In addition, this class provides many methods for
  37  * converting a {@code boolean} to a {@code String} and a
  38  * {@code String} to a {@code boolean}, as well as other
  39  * constants and methods useful when dealing with a
  40  * {@code boolean}.
  41  *
  42  * @author  Arthur van Hoff
  43  * @since   1.0
  44  */
  45 public final class Boolean implements java.io.Serializable,
  46                                       Comparable<Boolean>
  47 {
  48     /**
  49      * The {@code Boolean} object corresponding to the primitive
  50      * value {@code true}.
  51      */
  52     public static final Boolean TRUE = new Boolean(true);
  53 
  54     /**
  55      * The {@code Boolean} object corresponding to the primitive
  56      * value {@code false}.
  57      */
  58     public static final Boolean FALSE = new Boolean(false);
  59 
  60     /**
  61      * The Class object representing the primitive type boolean.
  62      *
  63      * @since   1.1
  64      */
  65     @SuppressWarnings("unchecked")
  66     public static final Class<Boolean> TYPE = (Class<Boolean>) Class.getPrimitiveClass("boolean");
  67 
  68     /**
  69      * The value of the Boolean.
  70      *
  71      * @serial
  72      */
  73     private final boolean value;
  74 
  75     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  76     private static final long serialVersionUID = -3665804199014368530L;
  77 
  78     /**
  79      * Allocates a {@code Boolean} object representing the
  80      * {@code value} argument.
  81      *
  82      * @param   value   the value of the {@code Boolean}.
  83      *
  84      * @deprecated
  85      * It is rarely appropriate to use this constructor. The static factory
  86      * {@link #valueOf(boolean)} is generally a better choice, as it is
  87      * likely to yield significantly better space and time performance.
  88      * Also consider using the final fields {@link #TRUE} and {@link #FALSE}
  89      * if possible.
  90      */
  91     @Deprecated(since="9")
  92     public Boolean(boolean value) {
  93         this.value = value;
  94     }
  95 
  96     /**
  97      * Allocates a {@code Boolean} object representing the value
  98      * {@code true} if the string argument is not {@code null}
  99      * and is equal, ignoring case, to the string {@code "true"}.
 100      * Otherwise, allocates a {@code Boolean} object representing the
 101      * value {@code false}.
 102      *
 103      * @param   s   the string to be converted to a {@code Boolean}.
 104      *
 105      * @deprecated
 106      * It is rarely appropriate to use this constructor.
 107      * Use {@link #parseBoolean(String)} to convert a string to a
 108      * {@code boolean} primitive, or use {@link #valueOf(String)}
 109      * to convert a string to a {@code Boolean} object.
 110      */
 111     @Deprecated(since="9")
 112     public Boolean(String s) {
 113         this(parseBoolean(s));
 114     }
 115 
 116     /**
 117      * Parses the string argument as a boolean.  The {@code boolean}
 118      * returned represents the value {@code true} if the string argument
 119      * is not {@code null} and is equal, ignoring case, to the string
 120      * {@code "true"}.
 121      * Otherwise, a false value is returned, including for a null
 122      * argument.<p>
 123      * Example: {@code Boolean.parseBoolean("True")} returns {@code true}.<br>
 124      * Example: {@code Boolean.parseBoolean("yes")} returns {@code false}.
 125      *
 126      * @param      s   the {@code String} containing the boolean
 127      *                 representation to be parsed
 128      * @return     the boolean represented by the string argument
 129      * @since 1.5
 130      */
 131     public static boolean parseBoolean(String s) {
 132         return ((s != null) && s.equalsIgnoreCase("true"));
 133     }
 134 
 135     /**
 136      * Returns the value of this {@code Boolean} object as a boolean
 137      * primitive.
 138      *
 139      * @return  the primitive {@code boolean} value of this object.
 140      */
 141     @HotSpotIntrinsicCandidate
 142     public boolean booleanValue() {
 143         return value;
 144     }
 145 
 146     /**
 147      * Returns a {@code Boolean} instance representing the specified
 148      * {@code boolean} value.  If the specified {@code boolean} value
 149      * is {@code true}, this method returns {@code Boolean.TRUE};
 150      * if it is {@code false}, this method returns {@code Boolean.FALSE}.
 151      * If a new {@code Boolean} instance is not required, this method
 152      * should generally be used in preference to the constructor
 153      * {@link #Boolean(boolean)}, as this method is likely to yield
 154      * significantly better space and time performance.
 155      *
 156      * @param  b a boolean value.
 157      * @return a {@code Boolean} instance representing {@code b}.
 158      * @since  1.4
 159      */
 160     @HotSpotIntrinsicCandidate
 161     public static Boolean valueOf(boolean b) {
 162         return (b ? TRUE : FALSE);
 163     }
 164 
 165     /**
 166      * Returns a {@code Boolean} with a value represented by the
 167      * specified string.  The {@code Boolean} returned represents a
 168      * true value if the string argument is not {@code null}
 169      * and is equal, ignoring case, to the string {@code "true"}.
 170      * Otherwise, a false value is returned, including for a null
 171      * argument.
 172      *
 173      * @param   s   a string.
 174      * @return  the {@code Boolean} value represented by the string.
 175      */
 176     public static Boolean valueOf(String s) {
 177         return parseBoolean(s) ? TRUE : FALSE;
 178     }
 179 
 180     /**
 181      * Returns a {@code String} object representing the specified
 182      * boolean.  If the specified boolean is {@code true}, then
 183      * the string {@code "true"} will be returned, otherwise the
 184      * string {@code "false"} will be returned.
 185      *
 186      * @param b the boolean to be converted
 187      * @return the string representation of the specified {@code boolean}
 188      * @since 1.4
 189      */
 190     public static String toString(boolean b) {
 191         return b ? "true" : "false";
 192     }
 193 
 194     /**
 195      * Returns a {@code String} object representing this Boolean's
 196      * value.  If this object represents the value {@code true},
 197      * a string equal to {@code "true"} is returned. Otherwise, a
 198      * string equal to {@code "false"} is returned.
 199      *
 200      * @return  a string representation of this object.
 201      */
 202     public String toString() {
 203         return value ? "true" : "false";
 204     }
 205 
 206     /**
 207      * Returns a hash code for this {@code Boolean} object.
 208      *
 209      * @return  the integer {@code 1231} if this object represents
 210      * {@code true}; returns the integer {@code 1237} if this
 211      * object represents {@code false}.
 212      */
 213     @Override
 214     public int hashCode() {
 215         return Boolean.hashCode(value);
 216     }
 217 
 218     /**
 219      * Returns a hash code for a {@code boolean} value; compatible with
 220      * {@code Boolean.hashCode()}.
 221      *
 222      * @param value the value to hash
 223      * @return a hash code value for a {@code boolean} value.
 224      * @since 1.8
 225      */
 226     public static int hashCode(boolean value) {
 227         return value ? 1231 : 1237;
 228     }
 229 
 230    /**
 231      * Returns {@code true} if and only if the argument is not
 232      * {@code null} and is a {@code Boolean} object that
 233      * represents the same {@code boolean} value as this object.
 234      *
 235      * @param   obj   the object to compare with.
 236      * @return  {@code true} if the Boolean objects represent the
 237      *          same value; {@code false} otherwise.
 238      */
 239     public boolean equals(Object obj) {
 240         if (obj instanceof Boolean) {
 241             return value == ((Boolean)obj).booleanValue();
 242         }
 243         return false;
 244     }
 245 
 246     /**
 247      * Returns {@code true} if and only if the system property named
 248      * by the argument exists and is equal to, ignoring case, the
 249      * string {@code "true"}.
 250      * A system property is accessible through {@code getProperty}, a
 251      * method defined by the {@code System} class.  <p> If there is no
 252      * property with the specified name, or if the specified name is
 253      * empty or null, then {@code false} is returned.
 254      *
 255      * @param   name   the system property name.
 256      * @return  the {@code boolean} value of the system property.
 257      * @throws  SecurityException for the same reasons as
 258      *          {@link System#getProperty(String) System.getProperty}
 259      * @see     java.lang.System#getProperty(java.lang.String)
 260      * @see     java.lang.System#getProperty(java.lang.String, java.lang.String)
 261      */
 262     public static boolean getBoolean(String name) {
 263         boolean result = false;
 264         try {
 265             result = parseBoolean(System.getProperty(name));
 266         } catch (IllegalArgumentException | NullPointerException e) {
 267         }
 268         return result;
 269     }
 270 
 271     /**
 272      * Compares this {@code Boolean} instance with another.
 273      *
 274      * @param   b the {@code Boolean} instance to be compared
 275      * @return  zero if this object represents the same boolean value as the
 276      *          argument; a positive value if this object represents true
 277      *          and the argument represents false; and a negative value if
 278      *          this object represents false and the argument represents true
 279      * @throws  NullPointerException if the argument is {@code null}
 280      * @see     Comparable
 281      * @since  1.5
 282      */
 283     public int compareTo(Boolean b) {
 284         return compare(this.value, b.value);
 285     }
 286 
 287     /**
 288      * Compares two {@code boolean} values.
 289      * The value returned is identical to what would be returned by:
 290      * <pre>
 291      *    Boolean.valueOf(x).compareTo(Boolean.valueOf(y))
 292      * </pre>
 293      *
 294      * @param  x the first {@code boolean} to compare
 295      * @param  y the second {@code boolean} to compare
 296      * @return the value {@code 0} if {@code x == y};
 297      *         a value less than {@code 0} if {@code !x && y}; and
 298      *         a value greater than {@code 0} if {@code x && !y}
 299      * @since 1.7
 300      */
 301     public static int compare(boolean x, boolean y) {
 302         return (x == y) ? 0 : (x ? 1 : -1);
 303     }
 304 
 305     /**
 306      * Returns the result of applying the logical AND operator to the
 307      * specified {@code boolean} operands.
 308      *
 309      * @param a the first operand
 310      * @param b the second operand
 311      * @return the logical AND of {@code a} and {@code b}
 312      * @see java.util.function.BinaryOperator
 313      * @since 1.8
 314      */
 315     public static boolean logicalAnd(boolean a, boolean b) {
 316         return a && b;
 317     }
 318 
 319     /**
 320      * Returns the result of applying the logical OR operator to the
 321      * specified {@code boolean} operands.
 322      *
 323      * @param a the first operand
 324      * @param b the second operand
 325      * @return the logical OR of {@code a} and {@code b}
 326      * @see java.util.function.BinaryOperator
 327      * @since 1.8
 328      */
 329     public static boolean logicalOr(boolean a, boolean b) {
 330         return a || b;
 331     }
 332 
 333     /**
 334      * Returns the result of applying the logical XOR operator to the
 335      * specified {@code boolean} operands.
 336      *
 337      * @param a the first operand
 338      * @param b the second operand
 339      * @return  the logical XOR of {@code a} and {@code b}
 340      * @see java.util.function.BinaryOperator
 341      * @since 1.8
 342      */
 343     public static boolean logicalXor(boolean a, boolean b) {
 344         return a ^ b;
 345     }
 346 }