ICU-21267 stop defining & using FALSE & TRUE macros in public headers

See #1282

docs/userguide/dev/codingguidelines.md

@@ -439,12 +439,30 @@ includes other header files. The most common types are `uint8_t`, `uint16_t`,
 `uint32_t`, `int8_t`, `int16_t`, `int32_t`, `char16_t`,
 `UChar` (same as `char16_t`), `UChar32` (signed, 32-bit), and `UErrorCode`.
 
-The language built-in type bool and constants true and false may be used
+The language built-in type `bool` and constants `true` and `false` may be used
 internally, for local variables and parameters of internal functions. The ICU
 type `UBool` must be used in public APIs and in the definition of any persistent
-data structures. `UBool` is guaranteed to be one byte in size and signed; bool is
+data structures. `UBool` is guaranteed to be one byte in size and signed; `bool` is
 not.
 
+Traditionally, ICU4C has defined its own `FALSE`=0 / `TRUE`=1 macros for use with `UBool`.
+Starting with ICU 68 (2020q4), we no longer define these in public header files
+(unless `U_DEFINE_FALSE_AND_TRUE`=1),
+in order to avoid name collisions with code outside ICU defining enum constants and similar
+with these names.
+
+Instead, the versions of the C and C++ standards we require now do define type `bool`
+and values `false` & `true`, and we and our users can use these values.
+
+As of ICU 68, we are not changing ICU4C API from `UBool` to `bool`.
+Doing so in C API, or in structs that cross the library boundary,
+would break binary compatibility.
+Doing so only in other places in C++ could be confusingly inconsistent.
+We may revisit this.
+
+Note that the details of type `bool` (e.g., `sizeof`) depend on the compiler and
+may differ between C and C++.
+
 #### File Names (.h, .c, .cpp, data files if possible, etc.)
 
 Limit file names to 31 lowercase ASCII characters. (Older versions of MacOS have

icu4c/source/common/cmemory.h

@@ -292,7 +292,7 @@ class MaybeStackArray {
     /**
      * Default constructor initializes with internal T[stackCapacity] buffer.
      */
-    MaybeStackArray() : ptr(stackArray), capacity(stackCapacity), needToRelease(FALSE) {}
+    MaybeStackArray() : ptr(stackArray), capacity(stackCapacity), needToRelease(false) {}
     /**
      * Automatically allocates the heap array if the argument is larger than the stack capacity.
      * Intended for use when an approximate capacity is known at compile time but the true
@@ -362,7 +362,7 @@ class MaybeStackArray {
             releaseArray();
             ptr=otherArray;
             capacity=otherCapacity;
-            needToRelease=FALSE;
+            needToRelease=false;
         }
     }
     /**
@@ -400,7 +400,7 @@ class MaybeStackArray {
     void resetToStackArray() {
         ptr=stackArray;
         capacity=stackCapacity;
-        needToRelease=FALSE;
+        needToRelease=false;
     }
     /* No comparison operators with other MaybeStackArray's. */
     bool operator==(const MaybeStackArray & /*other*/) = delete;
@@ -458,7 +458,7 @@ inline T *MaybeStackArray<T, stackCapacity>::resize(int32_t newCapacity, int32_t
             releaseArray();
             ptr=p;
             capacity=newCapacity;
-            needToRelease=TRUE;
+            needToRelease=true;
         }
         return p;
     } else {
@@ -514,7 +514,7 @@ class MaybeStackHeaderAndArray {
     /**
      * Default constructor initializes with internal H+T[stackCapacity] buffer.
      */
-    MaybeStackHeaderAndArray() : ptr(&stackHeader), capacity(stackCapacity), needToRelease(FALSE) {}
+    MaybeStackHeaderAndArray() : ptr(&stackHeader), capacity(stackCapacity), needToRelease(false) {}
     /**
      * Destructor deletes the memory (if owned).
      */
@@ -563,7 +563,7 @@ class MaybeStackHeaderAndArray {
             releaseMemory();
             ptr=otherMemory;
             capacity=otherCapacity;
-            needToRelease=FALSE;
+            needToRelease=false;
         }
     }
     /**
@@ -602,8 +602,8 @@ class MaybeStackHeaderAndArray {
         }
     }
     /* No comparison operators with other MaybeStackHeaderAndArray's. */
-    bool operator==(const MaybeStackHeaderAndArray & /*other*/) {return FALSE;}
-    bool operator!=(const MaybeStackHeaderAndArray & /*other*/) {return TRUE;}
+    bool operator==(const MaybeStackHeaderAndArray & /*other*/) {return false;}
+    bool operator!=(const MaybeStackHeaderAndArray & /*other*/) {return true;}
     /* No ownership transfer: No copy constructor, no assignment operator. */
     MaybeStackHeaderAndArray(const MaybeStackHeaderAndArray & /*other*/) {}
     void operator=(const MaybeStackHeaderAndArray & /*other*/) {}
@@ -632,7 +632,7 @@ inline H *MaybeStackHeaderAndArray<H, T, stackCapacity>::resize(int32_t newCapac
             releaseMemory();
             ptr=p;
             capacity=newCapacity;
-            needToRelease=TRUE;
+            needToRelease=true;
         }
         return p;
     } else {
@@ -664,7 +664,7 @@ inline H *MaybeStackHeaderAndArray<H, T, stackCapacity>::orphanOrClone(int32_t l
     resultCapacity=length;
     ptr=&stackHeader;
     capacity=stackCapacity;
-    needToRelease=FALSE;
+    needToRelease=false;
     return p;
 }
 

icu4c/source/common/normalizer2impl.h

@@ -171,7 +171,7 @@ class U_COMMON_API ReorderingBuffer : public UMemory {
                  UErrorCode &errorCode);
     UBool appendBMP(UChar c, uint8_t cc, UErrorCode &errorCode) {
         if(remainingCapacity==0 && !resize(1, errorCode)) {
-            return FALSE;
+            return false;
         }
         if(lastCC<=cc || cc==0) {
             *limit++=c;
@@ -183,7 +183,7 @@ class U_COMMON_API ReorderingBuffer : public UMemory {
             insert(c, cc);
         }
         --remainingCapacity;
-        return TRUE;
+        return true;
     }
     UBool appendZeroCC(UChar32 c, UErrorCode &errorCode);
     UBool appendZeroCC(const UChar *s, const UChar *sLimit, UErrorCode &errorCode);

icu4c/source/common/resource.h

@@ -60,7 +60,7 @@ class U_COMMON_API ResourceArray {
     /**
      * @param i Array item index.
      * @param value Output-only, receives the value of the i'th item.
-     * @return TRUE if i is non-negative and less than getSize().
+     * @return true if i is non-negative and less than getSize().
      */
     UBool getValue(int32_t i, ResourceValue &value) const;
 
@@ -97,14 +97,14 @@ class U_COMMON_API ResourceTable {
      * @param i Table item index.
      * @param key Output-only, receives the key of the i'th item.
      * @param value Output-only, receives the value of the i'th item.
-     * @return TRUE if i is non-negative and less than getSize().
+     * @return true if i is non-negative and less than getSize().
      */
     UBool getKeyAndValue(int32_t i, const char *&key, ResourceValue &value) const;
 
     /**
      * @param key Key string to find in the table.
      * @param value Output-only, receives the value of the item with that key.
-     * @return TRUE if the table contains the key.
+     * @return true if the table contains the key.
      */
     UBool findValue(const char *key, ResourceValue &value) const;
 
@@ -141,7 +141,7 @@ class U_COMMON_API ResourceValue : public UObject {
     inline UnicodeString getUnicodeString(UErrorCode &errorCode) const {
         int32_t len = 0;
         const UChar *r = getString(len, errorCode);
-        return UnicodeString(TRUE, r, len);
+        return UnicodeString(true, r, len);
     }
 
     /**
@@ -152,7 +152,7 @@ class U_COMMON_API ResourceValue : public UObject {
     inline UnicodeString getAliasUnicodeString(UErrorCode &errorCode) const {
         int32_t len = 0;
         const UChar *r = getAliasString(len, errorCode);
-        return UnicodeString(TRUE, r, len);
+        return UnicodeString(true, r, len);
     }
 
     /**
@@ -199,7 +199,7 @@ class U_COMMON_API ResourceValue : public UObject {
      * CLDR no-fallback data values of (three empty-set symbols)=={2205, 2205, 2205}
      * when enumerating tables with fallback from the specific resource bundle to root.
      *
-     * @return TRUE if this is a no-inheritance marker string
+     * @return true if this is a no-inheritance marker string
      */
     virtual UBool isNoInheritanceMarker() const = 0;
 

icu4c/source/common/unicode/appendable.h

@@ -45,7 +45,7 @@ class UnicodeString;
  *
  * The methods do not take UErrorCode parameters.
  * If an error occurs (e.g., out-of-memory),
- * in addition to returning FALSE from failing operations,
+ * in addition to returning false from failing operations,
  * the implementation must prevent unexpected behavior (e.g., crashes)
  * from further calls and should make the error condition available separately
  * (e.g., store a UErrorCode, make/keep a UnicodeString bogus).
@@ -62,7 +62,7 @@ class U_COMMON_API Appendable : public UObject {
     /**
      * Appends a 16-bit code unit.
      * @param c code unit
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendCodeUnit(char16_t c) = 0;
@@ -71,7 +71,7 @@ class U_COMMON_API Appendable : public UObject {
      * Appends a code point.
      * The default implementation calls appendCodeUnit(char16_t) once or twice.
      * @param c code point 0..0x10ffff
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendCodePoint(UChar32 c);
@@ -81,7 +81,7 @@ class U_COMMON_API Appendable : public UObject {
      * The default implementation calls appendCodeUnit(char16_t) for each code unit.
      * @param s string, must not be NULL if length!=0
      * @param length string length, or -1 if NUL-terminated
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendString(const char16_t *s, int32_t length);
@@ -90,9 +90,9 @@ class U_COMMON_API Appendable : public UObject {
      * Tells the object that the caller is going to append roughly
      * appendCapacity char16_ts. A subclass might use this to pre-allocate
      * a larger buffer if necessary.
-     * The default implementation does nothing. (It always returns TRUE.)
+     * The default implementation does nothing. (It always returns true.)
      * @param appendCapacity estimated number of char16_ts that will be appended
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool reserveAppendCapacity(int32_t appendCapacity);
@@ -171,15 +171,15 @@ class U_COMMON_API UnicodeStringAppendable : public Appendable {
     /**
      * Appends a 16-bit code unit to the string.
      * @param c code unit
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendCodeUnit(char16_t c);
 
     /**
      * Appends a code point to the string.
      * @param c code point 0..0x10ffff
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendCodePoint(UChar32 c);
@@ -188,7 +188,7 @@ class U_COMMON_API UnicodeStringAppendable : public Appendable {
      * Appends a string to the UnicodeString.
      * @param s string, must not be NULL if length!=0
      * @param length string length, or -1 if NUL-terminated
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool appendString(const char16_t *s, int32_t length);
@@ -197,7 +197,7 @@ class U_COMMON_API UnicodeStringAppendable : public Appendable {
      * Tells the UnicodeString that the caller is going to append roughly
      * appendCapacity char16_ts.
      * @param appendCapacity estimated number of char16_ts that will be appended
-     * @return TRUE if the operation succeeded
+     * @return true if the operation succeeded
      * @stable ICU 4.8
      */
     virtual UBool reserveAppendCapacity(int32_t appendCapacity);

icu4c/source/common/unicode/brkiter.h

@@ -564,7 +564,7 @@ class U_COMMON_API BreakIterator : public UObject {
      * BreakIterator::createXXXInstance to avoid undefined behavior.
      * @param key the registry key returned by a previous call to registerInstance
      * @param status the in/out status code, no special meanings are assigned
-     * @return TRUE if the iterator for the key was successfully unregistered
+     * @return true if the iterator for the key was successfully unregistered
      * @stable ICU 2.4
      */
     static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
@@ -655,7 +655,7 @@ class U_COMMON_API BreakIterator : public UObject {
 
 inline UBool BreakIterator::isBufferClone()
 {
-    return FALSE;
+    return false;
 }
 
 #endif /* U_HIDE_DEPRECATED_API */

icu4c/source/common/unicode/bytestream.h

@@ -197,7 +197,7 @@ class U_COMMON_API CheckedArrayByteSink : public ByteSink {
    * Returns the sink to its original state, without modifying the buffer.
    * Useful for reusing both the buffer and the sink for multiple streams.
    * Resets the state to NumberOfBytesWritten()=NumberOfBytesAppended()=0
-   * and Overflowed()=FALSE.
+   * and Overflowed()=false.
    * @return *this
    * @stable ICU 4.6
    */
@@ -236,7 +236,7 @@ class U_COMMON_API CheckedArrayByteSink : public ByteSink {
   /**
    * Returns true if any bytes were discarded, i.e., if there was an
    * attempt to write more than 'capacity' bytes.
-   * @return TRUE if more than 'capacity' bytes were Append()ed
+   * @return true if more than 'capacity' bytes were Append()ed
    * @stable ICU 4.2
    */
   UBool Overflowed() const { return overflowed_; }

icu4c/source/common/unicode/bytestrie.h

@@ -253,16 +253,16 @@ class U_COMMON_API BytesTrie : public UMemory {
     /**
      * Determines whether all byte sequences reachable from the current state
      * map to the same value.
-     * @param uniqueValue Receives the unique value, if this function returns TRUE.
+     * @param uniqueValue Receives the unique value, if this function returns true.
      *                    (output-only)
-     * @return TRUE if all byte sequences reachable from the current state
+     * @return true if all byte sequences reachable from the current state
      *         map to the same value.
      * @stable ICU 4.8
      */
     inline UBool hasUniqueValue(int32_t &uniqueValue) const {
         const uint8_t *pos=pos_;
         // Skip the rest of a pending linear-match node.
-        return pos!=NULL && findUniqueValue(pos+remainingMatchLength_+1, FALSE, uniqueValue);
+        return pos!=NULL && findUniqueValue(pos+remainingMatchLength_+1, false, uniqueValue);
     }
 
     /**
@@ -321,7 +321,7 @@ class U_COMMON_API BytesTrie : public UMemory {
         Iterator &reset();
 
         /**
-         * @return TRUE if there are more elements.
+         * @return true if there are more elements.
          * @stable ICU 4.8
          */
         UBool hasNext() const;
@@ -337,7 +337,7 @@ class U_COMMON_API BytesTrie : public UMemory {
          *                  pass the U_SUCCESS() test, or else the function returns
          *                  immediately. Check for U_FAILURE() on output or use with
          *                  function chaining. (See User Guide for details.)
-         * @return TRUE if there is another element.
+         * @return true if there is another element.
          * @stable ICU 4.8
          */
         UBool next(UErrorCode &errorCode);

icu4c/source/common/unicode/bytestriebuilder.h

@@ -140,7 +140,7 @@ class U_COMMON_API BytesTrieBuilder : public StringTrieBuilder {
     virtual int32_t skipElementsBySomeUnits(int32_t i, int32_t byteIndex, int32_t count) const;
     virtual int32_t indexOfElementWithNextUnit(int32_t i, int32_t byteIndex, char16_t byte) const;
 
-    virtual UBool matchNodesCanHaveValues() const { return FALSE; }
+    virtual UBool matchNodesCanHaveValues() const { return false; }
 
     virtual int32_t getMaxBranchLinearSubNodeLength() const { return BytesTrie::kMaxBranchLinearSubNodeLength; }
     virtual int32_t getMinLinearMatch() const { return BytesTrie::kMinLinearMatch; }

icu4c/source/common/unicode/caniter.h

@@ -25,11 +25,11 @@
  */
 
 /** Should permutation skip characters with combining class zero
- *  Should be either TRUE or FALSE. This is a compile time option
+ *  Should be either true or false. This is a compile time option
  *  @stable ICU 2.4
  */
 #ifndef CANITER_SKIP_ZEROES
-#define CANITER_SKIP_ZEROES TRUE
+#define CANITER_SKIP_ZEROES true
 #endif
 
 U_NAMESPACE_BEGIN