pango 3.1.0-x64-mingw32 → 3.1.1-x64-mingw32

data/vendor/local/include/unicode/ureldatefmt.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 *****************************************************************************************
 * Copyright (C) 2016, International Business Machines
@@ -58,11 +60,13 @@ typedef enum UDateRelativeDateTimeFormatterStyle {
    */
   UDAT_STYLE_NARROW,
 
-  /**
-   * The number of styles.
-   * @stable ICU 54
-   */
-  UDAT_STYLE_COUNT
+#ifndef U_HIDE_DEPRECATED_API
+    /**
+     * One more than the highest normal UDateRelativeDateTimeFormatterStyle value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+     */
+    UDAT_STYLE_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } UDateRelativeDateTimeFormatterStyle;
 
 #ifndef U_HIDE_DRAFT_API
@@ -162,11 +166,13 @@ typedef enum URelativeDateTimeUnit {
      * @draft ICU 57
      */
     UDAT_REL_UNIT_SATURDAY,
+#ifndef U_HIDE_DEPRECATED_API
     /**
-     * Count of URelativeDateTimeUnit values	 
-     * @draft ICU 57
+     * One more than the highest normal URelativeDateTimeUnit value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
      */
     UDAT_REL_UNIT_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } URelativeDateTimeUnit;
 #endif  /* U_HIDE_DRAFT_API */
 

data/vendor/local/include/unicode/urename.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 *******************************************************************************
 *   Copyright (C) 2002-2016, International Business Machines
@@ -474,6 +476,9 @@
 #define ubidi_setReorderingOptions U_ICU_ENTRY_POINT_RENAME(ubidi_setReorderingOptions)
 #define ubidi_writeReordered U_ICU_ENTRY_POINT_RENAME(ubidi_writeReordered)
 #define ubidi_writeReverse U_ICU_ENTRY_POINT_RENAME(ubidi_writeReverse)
+#define ubiditransform_close U_ICU_ENTRY_POINT_RENAME(ubiditransform_close)
+#define ubiditransform_open U_ICU_ENTRY_POINT_RENAME(ubiditransform_open)
+#define ubiditransform_transform U_ICU_ENTRY_POINT_RENAME(ubiditransform_transform)
 #define ublock_getCode U_ICU_ENTRY_POINT_RENAME(ublock_getCode)
 #define ubrk_close U_ICU_ENTRY_POINT_RENAME(ubrk_close)
 #define ubrk_countAvailable U_ICU_ENTRY_POINT_RENAME(ubrk_countAvailable)
@@ -1013,6 +1018,7 @@
 #define ulist_getListSize U_ICU_ENTRY_POINT_RENAME(ulist_getListSize)
 #define ulist_getNext U_ICU_ENTRY_POINT_RENAME(ulist_getNext)
 #define ulist_next_keyword_value U_ICU_ENTRY_POINT_RENAME(ulist_next_keyword_value)
+#define ulist_removeString U_ICU_ENTRY_POINT_RENAME(ulist_removeString)
 #define ulist_resetList U_ICU_ENTRY_POINT_RENAME(ulist_resetList)
 #define ulist_reset_keyword_values_iterator U_ICU_ENTRY_POINT_RENAME(ulist_reset_keyword_values_iterator)
 #define ulistfmt_close U_ICU_ENTRY_POINT_RENAME(ulistfmt_close)
@@ -1355,6 +1361,7 @@
 #define uprv_toupper U_ICU_ENTRY_POINT_RENAME(uprv_toupper)
 #define uprv_trunc U_ICU_ENTRY_POINT_RENAME(uprv_trunc)
 #define uprv_tzname U_ICU_ENTRY_POINT_RENAME(uprv_tzname)
+#define uprv_tzname_clear_cache U_ICU_ENTRY_POINT_RENAME(uprv_tzname_clear_cache)
 #define uprv_tzset U_ICU_ENTRY_POINT_RENAME(uprv_tzset)
 #define uprv_uint16Comparator U_ICU_ENTRY_POINT_RENAME(uprv_uint16Comparator)
 #define uprv_uint32Comparator U_ICU_ENTRY_POINT_RENAME(uprv_uint32Comparator)
@@ -1456,10 +1463,7 @@
 #define ures_countArrayItems U_ICU_ENTRY_POINT_RENAME(ures_countArrayItems)
 #define ures_findResource U_ICU_ENTRY_POINT_RENAME(ures_findResource)
 #define ures_findSubResource U_ICU_ENTRY_POINT_RENAME(ures_findSubResource)
-#define ures_getAllArrayItems U_ICU_ENTRY_POINT_RENAME(ures_getAllArrayItems)
-#define ures_getAllArrayItemsWithFallback U_ICU_ENTRY_POINT_RENAME(ures_getAllArrayItemsWithFallback)
-#define ures_getAllTableItems U_ICU_ENTRY_POINT_RENAME(ures_getAllTableItems)
-#define ures_getAllTableItemsWithFallback U_ICU_ENTRY_POINT_RENAME(ures_getAllTableItemsWithFallback)
+#define ures_getAllItemsWithFallback U_ICU_ENTRY_POINT_RENAME(ures_getAllItemsWithFallback)
 #define ures_getBinary U_ICU_ENTRY_POINT_RENAME(ures_getBinary)
 #define ures_getByIndex U_ICU_ENTRY_POINT_RENAME(ures_getByIndex)
 #define ures_getByKey U_ICU_ENTRY_POINT_RENAME(ures_getByKey)
@@ -1607,13 +1611,20 @@
 #define uspoof_areConfusableUTF8 U_ICU_ENTRY_POINT_RENAME(uspoof_areConfusableUTF8)
 #define uspoof_areConfusableUnicodeString U_ICU_ENTRY_POINT_RENAME(uspoof_areConfusableUnicodeString)
 #define uspoof_check U_ICU_ENTRY_POINT_RENAME(uspoof_check)
+#define uspoof_check2 U_ICU_ENTRY_POINT_RENAME(uspoof_check2)
+#define uspoof_check2UTF8 U_ICU_ENTRY_POINT_RENAME(uspoof_check2UTF8)
+#define uspoof_check2UnicodeString U_ICU_ENTRY_POINT_RENAME(uspoof_check2UnicodeString)
 #define uspoof_checkUTF8 U_ICU_ENTRY_POINT_RENAME(uspoof_checkUTF8)
 #define uspoof_checkUnicodeString U_ICU_ENTRY_POINT_RENAME(uspoof_checkUnicodeString)
 #define uspoof_clone U_ICU_ENTRY_POINT_RENAME(uspoof_clone)
 #define uspoof_close U_ICU_ENTRY_POINT_RENAME(uspoof_close)
+#define uspoof_closeCheckResult U_ICU_ENTRY_POINT_RENAME(uspoof_closeCheckResult)
 #define uspoof_getAllowedChars U_ICU_ENTRY_POINT_RENAME(uspoof_getAllowedChars)
 #define uspoof_getAllowedLocales U_ICU_ENTRY_POINT_RENAME(uspoof_getAllowedLocales)
 #define uspoof_getAllowedUnicodeSet U_ICU_ENTRY_POINT_RENAME(uspoof_getAllowedUnicodeSet)
+#define uspoof_getCheckResultChecks U_ICU_ENTRY_POINT_RENAME(uspoof_getCheckResultChecks)
+#define uspoof_getCheckResultNumerics U_ICU_ENTRY_POINT_RENAME(uspoof_getCheckResultNumerics)
+#define uspoof_getCheckResultRestrictionLevel U_ICU_ENTRY_POINT_RENAME(uspoof_getCheckResultRestrictionLevel)
 #define uspoof_getChecks U_ICU_ENTRY_POINT_RENAME(uspoof_getChecks)
 #define uspoof_getInclusionSet U_ICU_ENTRY_POINT_RENAME(uspoof_getInclusionSet)
 #define uspoof_getInclusionUnicodeSet U_ICU_ENTRY_POINT_RENAME(uspoof_getInclusionUnicodeSet)
@@ -1625,6 +1636,7 @@
 #define uspoof_getSkeletonUnicodeString U_ICU_ENTRY_POINT_RENAME(uspoof_getSkeletonUnicodeString)
 #define uspoof_internalInitStatics U_ICU_ENTRY_POINT_RENAME(uspoof_internalInitStatics)
 #define uspoof_open U_ICU_ENTRY_POINT_RENAME(uspoof_open)
+#define uspoof_openCheckResult U_ICU_ENTRY_POINT_RENAME(uspoof_openCheckResult)
 #define uspoof_openFromSerialized U_ICU_ENTRY_POINT_RENAME(uspoof_openFromSerialized)
 #define uspoof_openFromSource U_ICU_ENTRY_POINT_RENAME(uspoof_openFromSource)
 #define uspoof_serialize U_ICU_ENTRY_POINT_RENAME(uspoof_serialize)

data/vendor/local/include/unicode/urep.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 ******************************************************************************
 *   Copyright (C) 1997-2010, International Business Machines

data/vendor/local/include/unicode/ures.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 **********************************************************************
 *   Copyright (C) 1997-2016, International Business Machines
@@ -120,9 +122,13 @@ typedef enum {
     RES_INT_VECTOR=URES_INT_VECTOR,
     /** @deprecated ICU 2.6 Not used. */
     RES_RESERVED=15,
-#endif /* U_HIDE_DEPRECATED_API */
 
+    /**
+     * One more than the highest normal UResType value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+     */
     URES_LIMIT = 16
+#endif  // U_HIDE_DEPRECATED_API
 } UResType;
 
 /*

data/vendor/local/include/unicode/uscript.h

@@ -1,6 +1,8 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
  **********************************************************************
- *   Copyright (C) 1997-2015, International Business Machines
+ *   Copyright (C) 1997-2016, International Business Machines
  *   Corporation and others.  All Rights Reserved.
  **********************************************************************
  *
@@ -32,13 +34,13 @@
  * See UAX #24 Unicode Script Property (http://www.unicode.org/reports/tr24/)
  * and http://www.unicode.org/Public/UCD/latest/ucd/PropertyValueAliases.txt .
  *
- * Starting with ICU 3.6, constants for most ISO 15924 script codes
+ * In addition, constants for many ISO 15924 script codes
  * are included, for use with language tags, CLDR data, and similar.
  * Some of those codes are not used in the Unicode Character Database (UCD).
  * For example, there are no characters that have a UCD script property value of
  * Hans or Hant. All Han ideographs have the Hani script property value in Unicode.
  *
- * Private-use codes Qaaa..Qabx are not included.
+ * Private-use codes Qaaa..Qabx are not included, except as used in the UCD or in CLDR.
  *
  * Starting with ICU 55, script codes are only added when their scripts
  * have been or will certainly be encoded in Unicode,
@@ -424,24 +426,39 @@ typedef enum UScriptCode {
       /** @stable ICU 54 */
       USCRIPT_SIDDHAM                       = 166,/* Sidd */
 
-      /**
-       * One higher than the last script code constant.
-       * This value increases as constants for script codes are added.
-       *
-       * There are constants for Unicode 7 script property values.
-       * There are constants for ISO 15924 script codes assigned on or before 2013-10-12.
-       * There are no constants for private use codes from Qaaa - Qabx
-       * except as used in the UCD.
-       *
-       * @stable ICU 2.2
-       */
-      USCRIPT_CODE_LIMIT    = 167
+      /** @stable ICU 58 */
+      USCRIPT_ADLAM                         = 167,/* Adlm */
+      /** @stable ICU 58 */
+      USCRIPT_BHAIKSUKI                     = 168,/* Bhks */
+      /** @stable ICU 58 */
+      USCRIPT_MARCHEN                       = 169,/* Marc */
+      /** @stable ICU 58 */
+      USCRIPT_NEWA                          = 170,/* Newa */
+      /** @stable ICU 58 */
+      USCRIPT_OSAGE                         = 171,/* Osge */
+
+      /** @stable ICU 58 */
+      USCRIPT_HAN_WITH_BOPOMOFO             = 172,/* Hanb */
+      /** @stable ICU 58 */
+      USCRIPT_JAMO                          = 173,/* Jamo */
+      /** @stable ICU 58 */
+      USCRIPT_SYMBOLS_EMOJI                 = 174,/* Zsye */
+
+#ifndef U_HIDE_DEPRECATED_API
+    /**
+     * One more than the highest normal UScriptCode value.
+     * The highest value is available via u_getIntPropertyMaxValue(UCHAR_SCRIPT).
+     *
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+     */
+    USCRIPT_CODE_LIMIT    = 175
+#endif  // U_HIDE_DEPRECATED_API
 } UScriptCode;
 
 /**
- * Gets the script codes associated with the given locale or ISO 15924 abbreviation or name. 
+ * Gets the script codes associated with the given locale or ISO 15924 abbreviation or name.
  * Fills in USCRIPT_MALAYALAM given "Malayam" OR "Mlym".
- * Fills in USCRIPT_LATIN given "en" OR "en_US" 
+ * Fills in USCRIPT_LATIN given "en" OR "en_US"
  * If the required capacity is greater than the capacity of the destination buffer,
  * then the error code is set to U_BUFFER_OVERFLOW_ERROR and the required capacity is returned.
  *
@@ -454,10 +471,10 @@ typedef enum UScriptCode {
  * @param fillIn the UScriptCode buffer to fill in the script code
  * @param capacity the capacity (size) fo UScriptCode buffer passed in.
  * @param err the error status code.
- * @return The number of script codes filled in the buffer passed in 
+ * @return The number of script codes filled in the buffer passed in
  * @stable ICU 2.4
  */
-U_STABLE int32_t  U_EXPORT2 
+U_STABLE int32_t  U_EXPORT2
 uscript_getCode(const char* nameOrAbbrOrLocale,UScriptCode* fillIn,int32_t capacity,UErrorCode *err);
 
 /**
@@ -470,7 +487,7 @@ uscript_getCode(const char* nameOrAbbrOrLocale,UScriptCode* fillIn,int32_t capac
  * or NULL if scriptCode is invalid
  * @stable ICU 2.4
  */
-U_STABLE const char*  U_EXPORT2 
+U_STABLE const char*  U_EXPORT2
 uscript_getName(UScriptCode scriptCode);
 
 /**
@@ -482,18 +499,18 @@ uscript_getName(UScriptCode scriptCode);
  * @return short script name (4-letter code), or NULL if scriptCode is invalid
  * @stable ICU 2.4
  */
-U_STABLE const char*  U_EXPORT2 
+U_STABLE const char*  U_EXPORT2
 uscript_getShortName(UScriptCode scriptCode);
 
 /**
  * Gets the script code associated with the given codepoint.
- * Returns USCRIPT_MALAYALAM given 0x0D02 
+ * Returns USCRIPT_MALAYALAM given 0x0D02
  * @param codepoint UChar32 codepoint
  * @param err the error status code.
- * @return The UScriptCode, or 0 if codepoint is invalid 
+ * @return The UScriptCode, or 0 if codepoint is invalid
  * @stable ICU 2.4
  */
-U_STABLE UScriptCode  U_EXPORT2 
+U_STABLE UScriptCode  U_EXPORT2
 uscript_getScript(UChar32 codepoint, UErrorCode *err);
 
 /**
@@ -503,9 +520,6 @@ uscript_getScript(UChar32 codepoint, UErrorCode *err);
  *
  * Some characters are commonly used in multiple scripts.
  * For more information, see UAX #24: http://www.unicode.org/reports/tr24/.
- *
- * The Script_Extensions property is provisional. It may be modified or removed
- * in future versions of the Unicode Standard, and thus in ICU.
  * @param c code point
  * @param sc script code
  * @return TRUE if sc is in Script_Extensions(c)
@@ -532,8 +546,6 @@ uscript_hasScript(UChar32 c, UScriptCode sc);
  * U_BUFFER_OVERFLOW_ERROR is set and the number of Script_Extensions is returned.
  * (Usual ICU buffer handling behavior.)
  *
- * The Script_Extensions property is provisional. It may be modified or removed
- * in future versions of the Unicode Standard, and thus in ICU.
  * @param c code point
  * @param scripts output script code array
  * @param capacity capacity of the scripts array

data/vendor/local/include/unicode/usearch.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 **********************************************************************
 *   Copyright (C) 2001-2011,2014 IBM and others. All rights reserved.
@@ -188,11 +190,13 @@ typedef enum {
      */
     USEARCH_ELEMENT_COMPARISON = 2,
 
+#ifndef U_HIDE_DEPRECATED_API
     /**
-     * Count of attribute types
-     * @stable ICU 2.4
+     * One more than the highest normal USearchAttribute value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
      */
     USEARCH_ATTRIBUTE_COUNT = 3
+#endif  // U_HIDE_DEPRECATED_API
 } USearchAttribute;
 
 /**
@@ -262,11 +266,13 @@ typedef enum {
      */
     USEARCH_ANY_BASE_WEIGHT_IS_WILDCARD,
 
+#ifndef U_HIDE_DEPRECATED_API
     /**
-     * Count of attribute values
-     * @stable ICU 2.4
+     * One more than the highest normal USearchAttributeValue value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
      */
     USEARCH_ATTRIBUTE_VALUE_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } USearchAttributeValue;
 
 /* open and close ------------------------------------------------------ */

data/vendor/local/include/unicode/uset.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 *******************************************************************************
 *
@@ -196,11 +198,13 @@ typedef enum USetSpanCondition {
      * @stable ICU 3.8
      */
     USET_SPAN_SIMPLE = 2,
+#ifndef U_HIDE_DEPRECATED_API
     /**
      * One more than the last span condition.
-     * @stable ICU 3.8
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
      */
     USET_SPAN_CONDITION_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } USetSpanCondition;
 
 enum {

data/vendor/local/include/unicode/usetiter.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 **********************************************************************
 * Copyright (c) 2002-2014, International Business Machines

data/vendor/local/include/unicode/ushape.h

@@ -1,3 +1,5 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 ******************************************************************************
 *

data/vendor/local/include/unicode/uspoof.h

@@ -1,6 +1,8 @@
+// Copyright (C) 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 ***************************************************************************
-* Copyright (C) 2008-2015, International Business Machines Corporation
+* Copyright (C) 2008-2016, International Business Machines Corporation
 * and others. All Rights Reserved.
 ***************************************************************************
 *   file name:  uspoof.h
@@ -35,123 +37,350 @@
  * \file
  * \brief Unicode Security and Spoofing Detection, C API.
  *
- * These functions are intended to check strings, typically
- * identifiers of some type, such as URLs, for the presence of
- * characters that are likely to be visually confusing - 
- * for cases where the displayed form of an identifier may
- * not be what it appears to be.
- *
- * Unicode Technical Report #36, http://unicode.org/reports/tr36, and
- * Unicode Technical Standard #39, http://unicode.org/reports/tr39
- * "Unicode security considerations", give more background on 
- * security an spoofing issues with Unicode identifiers.
- * The tests and checks provided by this module implement the recommendations
- * from those Unicode documents.
- *
- * The tests available on identifiers fall into two general categories:
- *   -#  Single identifier tests.  Check whether an identifier is
- *       potentially confusable with any other string, or is suspicious
- *       for other reasons.
- *   -#  Two identifier tests.  Check whether two specific identifiers are confusable.
- *       This does not consider whether either of strings is potentially
- *       confusable with any string other than the exact one specified.
- *
- * The steps to perform confusability testing are
- *   -#  Open a USpoofChecker.
- *   -#  Configure the USPoofChecker for the desired set of tests.  The tests that will
- *       be performed are specified by a set of USpoofChecks flags.
- *   -#  Perform the checks using the pre-configured USpoofChecker.  The results indicate
- *       which (if any) of the selected tests have identified possible problems with the identifier.
- *       Results are reported as a set of USpoofChecks flags;  this mirrors the form in which
- *       the set of tests to perform was originally specified to the USpoofChecker.
- *
- * A USpoofChecker may be used repeatedly to perform checks on any number of identifiers.
- *
- * Thread Safety: The test functions for checking a single identifier, or for testing 
- * whether two identifiers are possible confusable, are thread safe.  
- * They may called concurrently, from multiple threads, using the same USpoofChecker instance.
- *
- * More generally, the standard ICU thread safety rules apply:  functions that take a
- * const USpoofChecker parameter are thread safe.  Those that take a non-const 
- * USpoofChecier are not thread safe.
- *
- *
- * Descriptions of the available checks.
- *
- * When testing whether pairs of identifiers are confusable, with the uspoof_areConfusable()
- * family of functions, the relevant tests are
- *
- *   -# USPOOF_SINGLE_SCRIPT_CONFUSABLE:  All of the characters from the two identifiers are
- *      from a single script, and the two identifiers are visually confusable.
- *   -# USPOOF_MIXED_SCRIPT_CONFUSABLE:  At least one of the identifiers contains characters
- *      from more than one script, and the two identifiers are visually confusable.
- *   -# USPOOF_WHOLE_SCRIPT_CONFUSABLE: Each of the two identifiers is of a single script, but
- *      the two identifiers are from different scripts, and they are visually confusable.
- *
- * The safest approach is to enable all three of these checks as a group.
- *
- * USPOOF_ANY_CASE is a modifier for the above tests.  If the identifiers being checked can
- * be of mixed case and are used in a case-sensitive manner, this option should be specified.
- *
- * If the identifiers being checked are used in a case-insensitive manner, and if they are
- * displayed to users in lower-case form only, the USPOOF_ANY_CASE option should not be
- * specified.  Confusabality issues involving upper case letters will not be reported.
- *
- * When performing tests on a single identifier, with the uspoof_check() family of functions,
- * the relevant tests are:
- *
- *    -# USPOOF_MIXED_SCRIPT_CONFUSABLE: the identifier contains characters from multiple
- *       scripts, and there exists an identifier of a single script that is visually confusable.
- *    -# USPOOF_WHOLE_SCRIPT_CONFUSABLE: the identifier consists of characters from a single
- *       script, and there exists a visually confusable identifier.
- *       The visually confusable identifier also consists of characters from a single script.
- *       but not the same script as the identifier being checked.
- *    -# USPOOF_ANY_CASE: modifies the mixed script and whole script confusables tests.  If
- *       specified, the checks will consider confusable characters of any case.  If this flag is not
- *       set, the test is performed assuming case folded identifiers.
- *    -# USPOOF_SINGLE_SCRIPT: check that the identifier contains only characters from a
- *       single script.  (Characters from the 'common' and 'inherited' scripts are ignored.)
- *       This is not a test for confusable identifiers
- *    -# USPOOF_INVISIBLE: check an identifier for the presence of invisible characters,
- *       such as zero-width spaces, or character sequences that are
- *       likely not to display, such as multiple occurrences of the same
- *       non-spacing mark.  This check does not test the input string as a whole
- *       for conformance to any particular syntax for identifiers.
- *    -# USPOOF_CHAR_LIMIT: check that an identifier contains only characters from a specified set
- *       of acceptable characters.  See uspoof_setAllowedChars() and
- *       uspoof_setAllowedLocales().
- *
- *  Note on Scripts:
- *     Characters from the Unicode Scripts "Common" and "Inherited" are ignored when considering
- *     the script of an identifier. Common characters include digits and symbols that
- *     are normally used with text from more than one script.
- *
- *  Identifier Skeletons:  A skeleton is a transformation of an identifier, such that
- *  all identifiers that are confusable with each other have the same skeleton.
- *  Using skeletons, it is possible to build a dictionary data structure for
- *  a set of identifiers, and then quickly test whether a new identifier is
- *  confusable with an identifier already in the set.  The uspoof_getSkeleton()
- *  family of functions will produce the skeleton from an identifier.
- *
- *  Note that skeletons are not guaranteed to be stable between versions 
- *  of Unicode or ICU, so an applications should not rely on creating a permanent,
- *  or difficult to update, database of skeletons.  Instabilities result from
- *  identifying new pairs or sequences of characters that are visually
- *  confusable, and thus must be mapped to the same skeleton character(s).
- *
- *  Skeletons are computed using the algorithm and data describe in Unicode UAX 39.
- *  The latest proposed update, UAX 39 Version 8 draft 1, says "the tables SL, SA, and ML
- *  were still problematic, and discouraged from use in [Uniocde] 7.0.
- *  They were thus removed from version 8.0"
- *
- *  In light of this, the default mapping data included with ICU 55 uses the
- *  Unicode 7 MA (Multi script Any case) table data for the other type options
- *  (Single Script, Any Case), (Single Script, Lower Case) and (Multi Script, Lower Case).
+ * <p>
+ * This class, based on <a href="http://unicode.org/reports/tr36">Unicode Technical Report #36</a> and
+ * <a href="http://unicode.org/reports/tr39">Unicode Technical Standard #39</a>, has two main functions:
+ *
+ * <ol>
+ * <li>Checking whether two strings are visually <em>confusable</em> with each other, such as "Harvest" and
+ * &quot;&Eta;arvest&quot;, where the second string starts with the Greek capital letter Eta.</li>
+ * <li>Checking whether an individual string is likely to be an attempt at confusing the reader (<em>spoof
+ * detection</em>), such as "paypal" with some Latin characters substituted with Cyrillic look-alikes.</li>
+ * </ol>
+ *
+ * <p>
+ * Although originally designed as a method for flagging suspicious identifier strings such as URLs,
+ * <code>USpoofChecker</code> has a number of other practical use cases, such as preventing attempts to evade bad-word
+ * content filters.
+ *
+ * <p>
+ * The functions of this class are exposed as C API, with a handful of syntactical conveniences for C++.
+ *
+ * <h2>Confusables</h2>
+ *
+ * <p>
+ * The following example shows how to use <code>USpoofChecker</code> to check for confusability between two strings:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar* str1 = (UChar*) u"Harvest";
+ * UChar* str2 = (UChar*) u"\u0397arvest";  // with U+0397 GREEK CAPITAL LETTER ETA
+ *
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status);
+ *
+ * int32_t bitmask = uspoof_areConfusable(sc, str1, -1, str2, -1, &status);
+ * UBool result = bitmask != 0;
+ * // areConfusable: 1 (status: U_ZERO_ERROR)
+ * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status));
+ * uspoof_close(sc);
+ * \endcode
+ *
+ * <p>
+ * The call to {@link uspoof_open} creates a <code>USpoofChecker</code> object; the call to {@link uspoof_setChecks}
+ * enables confusable checking and disables all other checks; the call to {@link uspoof_areConfusable} performs the
+ * confusability test; and the following line extracts the result out of the return value. For best performance,
+ * the instance should be created once (e.g., upon application startup), and the efficient
+ * {@link uspoof_areConfusable} method can be used at runtime.
+ *
+ * <p>
+ * The type {@link LocalUSpoofCheckerPointer} is exposed for C++ programmers.  It will automatically call
+ * {@link uspoof_close} when the object goes out of scope:
+ *
+ * \code{.cpp}
+ * UErrorCode status = U_ZERO_ERROR;
+ * LocalUSpoofCheckerPointer sc(uspoof_open(&status));
+ * uspoof_setChecks(sc.getAlias(), USPOOF_CONFUSABLE, &status);
+ * // ...
+ * \endcode
+ *
+ * <p>
+ * UTS 39 defines two strings to be <em>confusable</em> if they map to the same <em>skeleton string</em>. A skeleton can
+ * be thought of as a "hash code". {@link uspoof_getSkeleton} computes the skeleton for a particular string, so
+ * the following snippet is equivalent to the example above:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar* str1 = (UChar*) u"Harvest";
+ * UChar* str2 = (UChar*) u"\u0397arvest";  // with U+0397 GREEK CAPITAL LETTER ETA
+ *
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status);
+ *
+ * // Get skeleton 1
+ * int32_t skel1Len = uspoof_getSkeleton(sc, 0, str1, -1, NULL, 0, &status);
+ * UChar* skel1 = (UChar*) malloc(++skel1Len * sizeof(UChar));
+ * status = U_ZERO_ERROR;
+ * uspoof_getSkeleton(sc, 0, str1, -1, skel1, skel1Len, &status);
+ *
+ * // Get skeleton 2
+ * int32_t skel2Len = uspoof_getSkeleton(sc, 0, str2, -1, NULL, 0, &status);
+ * UChar* skel2 = (UChar*) malloc(++skel2Len * sizeof(UChar));
+ * status = U_ZERO_ERROR;
+ * uspoof_getSkeleton(sc, 0, str2, -1, skel2, skel2Len, &status);
+ *
+ * // Are the skeletons the same?
+ * UBool result = u_strcmp(skel1, skel2) == 0;
+ * // areConfusable: 1 (status: U_ZERO_ERROR)
+ * printf("areConfusable: %d (status: %s)\n", result, u_errorName(status));
+ * uspoof_close(sc);
+ * free(skel1);
+ * free(skel2);
+ * \endcode
+ *
+ * <p>
+ * If you need to check if a string is confusable with any string in a dictionary of many strings, rather than calling
+ * {@link uspoof_areConfusable} many times in a loop, {@link uspoof_getSkeleton} can be used instead, as shown below:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * #define DICTIONARY_LENGTH 2
+ * UChar* dictionary[DICTIONARY_LENGTH] = { (UChar*) u"lorem", (UChar*) u"ipsum" };
+ * UChar* skeletons[DICTIONARY_LENGTH];
+ * UChar* str = (UChar*) u"1orern";
+ *
+ * // Setup:
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setChecks(sc, USPOOF_CONFUSABLE, &status);
+ * for (size_t i=0; i<DICTIONARY_LENGTH; i++) {
+ *     UChar* word = dictionary[i];
+ *     int32_t len = uspoof_getSkeleton(sc, 0, word, -1, NULL, 0, &status);
+ *     skeletons[i] = (UChar*) malloc(++len * sizeof(UChar));
+ *     status = U_ZERO_ERROR;
+ *     uspoof_getSkeleton(sc, 0, word, -1, skeletons[i], len, &status);
+ * }
+ *
+ * // Live Check:
+ * {
+ *     int32_t len = uspoof_getSkeleton(sc, 0, str, -1, NULL, 0, &status);
+ *     UChar* skel = (UChar*) malloc(++len * sizeof(UChar));
+ *     status = U_ZERO_ERROR;
+ *     uspoof_getSkeleton(sc, 0, str, -1, skel, len, &status);
+ *     UBool result = FALSE;
+ *     for (size_t i=0; i<DICTIONARY_LENGTH; i++) {
+ *         result = u_strcmp(skel, skeletons[i]) == 0;
+ *         if (result == TRUE) { break; }
+ *     }
+ *     // Has confusable in dictionary: 1 (status: U_ZERO_ERROR)
+ *     printf("Has confusable in dictionary: %d (status: %s)\n", result, u_errorName(status));
+ *     free(skel);
+ * }
+ *
+ * for (size_t i=0; i<DICTIONARY_LENGTH; i++) {
+ *     free(skeletons[i]);
+ * }
+ * uspoof_close(sc);
+ * \endcode
+ *
+ * <p>
+ * <b>Note:</b> Since the Unicode confusables mapping table is frequently updated, confusable skeletons are <em>not</em>
+ * guaranteed to be the same between ICU releases. We therefore recommend that you always compute confusable skeletons
+ * at runtime and do not rely on creating a permanent, or difficult to update, database of skeletons.
+ *
+ * <h2>Spoof Detection</h2>
+ *
+ * <p>
+ * The following snippet shows a minimal example of using <code>USpoofChecker</code> to perform spoof detection on a
+ * string:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar* str = (UChar*) u"p\u0430ypal";  // with U+0430 CYRILLIC SMALL LETTER A
+ *
+ * // Get the default set of allowable characters:
+ * USet* allowed = uset_openEmpty();
+ * uset_addAll(allowed, uspoof_getRecommendedSet(&status));
+ * uset_addAll(allowed, uspoof_getInclusionSet(&status));
+ *
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setAllowedChars(sc, allowed, &status);
+ * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE);
+ *
+ * int32_t bitmask = uspoof_check(sc, str, -1, NULL, &status);
+ * UBool result = bitmask != 0;
+ * // fails checks: 1 (status: U_ZERO_ERROR)
+ * printf("fails checks: %d (status: %s)\n", result, u_errorName(status));
+ * uspoof_close(sc);
+ * uset_close(allowed);
+ * \endcode
+ *
+ * <p>
+ * As in the case for confusability checking, it is good practice to create one <code>USpoofChecker</code> instance at
+ * startup, and call the cheaper {@link uspoof_check} online. We specify the set of
+ * allowed characters to be those with type RECOMMENDED or INCLUSION, according to the recommendation in UTS 39.
+ *
+ * <p>
+ * In addition to {@link uspoof_check}, the function {@link uspoof_checkUTF8} is exposed for UTF8-encoded char* strings,
+ * and {@link uspoof_checkUnicodeString} is exposed for C++ programmers.
+ *
+ * <p>
+ * If the {@link USPOOF_AUX_INFO} check is enabled, a limited amount of information on why a string failed the checks
+ * is available in the returned bitmask.  For complete information, use the {@link uspoof_check2} class of functions
+ * with a {@link USpoofCheckResult} parameter:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar* str = (UChar*) u"p\u0430ypal";  // with U+0430 CYRILLIC SMALL LETTER A
+ *
+ * // Get the default set of allowable characters:
+ * USet* allowed = uset_openEmpty();
+ * uset_addAll(allowed, uspoof_getRecommendedSet(&status));
+ * uset_addAll(allowed, uspoof_getInclusionSet(&status));
+ *
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setAllowedChars(sc, allowed, &status);
+ * uspoof_setRestrictionLevel(sc, USPOOF_MODERATELY_RESTRICTIVE);
+ *
+ * USpoofCheckResult* checkResult = uspoof_openCheckResult(&status);
+ * int32_t bitmask = uspoof_check2(sc, str, -1, checkResult, &status);
+ *
+ * int32_t failures1 = bitmask;
+ * int32_t failures2 = uspoof_getCheckResultChecks(checkResult, &status);
+ * assert(failures1 == failures2);
+ * // checks that failed: 0x00000010 (status: U_ZERO_ERROR)
+ * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status));
+ *
+ * // Cleanup:
+ * uspoof_close(sc);
+ * uset_close(allowed);
+ * uspoof_closeCheckResult(checkResult);
+ * \endcode
+ *
+ * C++ users can take advantage of a few syntactical conveniences.  The following snippet is functionally
+ * equivalent to the one above:
+ *
+ * \code{.cpp}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UnicodeString str((UChar*) u"p\u0430ypal");  // with U+0430 CYRILLIC SMALL LETTER A
+ *
+ * // Get the default set of allowable characters:
+ * UnicodeSet allowed;
+ * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status));
+ * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status));
+ *
+ * LocalUSpoofCheckerPointer sc(uspoof_open(&status));
+ * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status);
+ * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE);
+ *
+ * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status));
+ * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status);
+ *
+ * int32_t failures1 = bitmask;
+ * int32_t failures2 = uspoof_getCheckResultChecks(checkResult.getAlias(), &status);
+ * assert(failures1 == failures2);
+ * // checks that failed: 0x00000010 (status: U_ZERO_ERROR)
+ * printf("checks that failed: %#010x (status: %s)\n", failures1, u_errorName(status));
+ *
+ * // Explicit cleanup not necessary.
+ * \endcode
+ *
+ * <p>
+ * The return value is a bitmask of the checks that failed. In this case, there was one check that failed:
+ * {@link USPOOF_RESTRICTION_LEVEL}, corresponding to the fifth bit (16). The possible checks are:
+ *
+ * <ul>
+ * <li><code>RESTRICTION_LEVEL</code>: flags strings that violate the
+ * <a href="http://unicode.org/reports/tr39/#Restriction_Level_Detection">Restriction Level</a> test as specified in UTS
+ * 39; in most cases, this means flagging strings that contain characters from multiple different scripts.</li>
+ * <li><code>INVISIBLE</code>: flags strings that contain invisible characters, such as zero-width spaces, or character
+ * sequences that are likely not to display, such as multiple occurrences of the same non-spacing mark.</li>
+ * <li><code>CHAR_LIMIT</code>: flags strings that contain characters outside of a specified set of acceptable
+ * characters. See {@link uspoof_setAllowedChars} and {@link uspoof_setAllowedLocales}.</li>
+ * <li><code>MIXED_NUMBERS</code>: flags strings that contain digits from multiple different numbering systems.</li>
+ * </ul>
+ *
+ * <p>
+ * These checks can be enabled independently of each other. For example, if you were interested in checking for only the
+ * INVISIBLE and MIXED_NUMBERS conditions, you could do:
+ *
+ * \code{.c}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UChar* str = (UChar*) u"8\u09EA";  // 8 mixed with U+09EA BENGALI DIGIT FOUR
+ *
+ * USpoofChecker* sc = uspoof_open(&status);
+ * uspoof_setChecks(sc, USPOOF_INVISIBLE | USPOOF_MIXED_NUMBERS, &status);
+ *
+ * int32_t bitmask = uspoof_check2(sc, str, -1, NULL, &status);
+ * UBool result = bitmask != 0;
+ * // fails checks: 1 (status: U_ZERO_ERROR)
+ * printf("fails checks: %d (status: %s)\n", result, u_errorName(status));
+ * uspoof_close(sc);
+ * \endcode
+ *
+ * <p>
+ * Here is an example in C++ showing how to compute the restriction level of a string:
+ *
+ * \code{.cpp}
+ * UErrorCode status = U_ZERO_ERROR;
+ * UnicodeString str((UChar*) u"p\u0430ypal");  // with U+0430 CYRILLIC SMALL LETTER A
+ *
+ * // Get the default set of allowable characters:
+ * UnicodeSet allowed;
+ * allowed.addAll(*uspoof_getRecommendedUnicodeSet(&status));
+ * allowed.addAll(*uspoof_getInclusionUnicodeSet(&status));
+ *
+ * LocalUSpoofCheckerPointer sc(uspoof_open(&status));
+ * uspoof_setAllowedChars(sc.getAlias(), allowed.toUSet(), &status);
+ * uspoof_setRestrictionLevel(sc.getAlias(), USPOOF_MODERATELY_RESTRICTIVE);
+ * uspoof_setChecks(sc.getAlias(), USPOOF_RESTRICTION_LEVEL | USPOOF_AUX_INFO, &status);
+ *
+ * LocalUSpoofCheckResultPointer checkResult(uspoof_openCheckResult(&status));
+ * int32_t bitmask = uspoof_check2UnicodeString(sc.getAlias(), str, checkResult.getAlias(), &status);
+ *
+ * URestrictionLevel restrictionLevel = uspoof_getCheckResultRestrictionLevel(checkResult.getAlias(), &status);
+ * // Since USPOOF_AUX_INFO was enabled, the restriction level is also available in the upper bits of the bitmask:
+ * assert((restrictionLevel & bitmask) == restrictionLevel);
+ * // Restriction level: 0x50000000 (status: U_ZERO_ERROR)
+ * printf("Restriction level: %#010x (status: %s)\n", restrictionLevel, u_errorName(status));
+ * \endcode
+ *
+ * <p>
+ * The code '0x50000000' corresponds to the restriction level USPOOF_MINIMALLY_RESTRICTIVE.  Since
+ * USPOOF_MINIMALLY_RESTRICTIVE is weaker than USPOOF_MODERATELY_RESTRICTIVE, the string fails the check.
+ *
+ * <p>
+ * <b>Note:</b> The Restriction Level is the most powerful of the checks. The full logic is documented in
+ * <a href="http://unicode.org/reports/tr39/#Restriction_Level_Detection">UTS 39</a>, but the basic idea is that strings
+ * are restricted to contain characters from only a single script, <em>except</em> that most scripts are allowed to have
+ * Latin characters interspersed. Although the default restriction level is <code>HIGHLY_RESTRICTIVE</code>, it is
+ * recommended that users set their restriction level to <code>MODERATELY_RESTRICTIVE</code>, which allows Latin mixed
+ * with all other scripts except Cyrillic, Greek, and Cherokee, with which it is often confusable. For more details on
+ * the levels, see UTS 39 or {@link URestrictionLevel}. The Restriction Level test is aware of the set of
+ * allowed characters set in {@link uspoof_setAllowedChars}. Note that characters which have script code
+ * COMMON or INHERITED, such as numbers and punctuation, are ignored when computing whether a string has multiple
+ * scripts.
+ *
+ * <h2>Additional Information</h2>
+ *
+ * <p>
+ * A <code>USpoofChecker</code> instance may be used repeatedly to perform checks on any number of identifiers.
+ *
+ * <p>
+ * <b>Thread Safety:</b> The test functions for checking a single identifier, or for testing whether
+ * two identifiers are possible confusable, are thread safe. They may called concurrently, from multiple threads,
+ * using the same USpoofChecker instance.
+ *
+ * <p>
+ * More generally, the standard ICU thread safety rules apply: functions that take a const USpoofChecker parameter are
+ * thread safe. Those that take a non-const USpoofChecker are not thread safe..
+ *
+ * @stable ICU 4.6
  */
 
 struct USpoofChecker;
 typedef struct USpoofChecker USpoofChecker; /**< typedef for C of USpoofChecker */
 
+#ifndef U_HIDE_DRAFT_API
+/**
+ * @see uspoof_openCheckResult
+ */
+struct USpoofCheckResult;
+/**
+ * @see uspoof_openCheckResult
+ */
+typedef struct USpoofCheckResult USpoofCheckResult;
+#endif /* U_HIDE_DRAFT_API */
+
 /**
  * Enum for the kinds of checks that USpoofChecker can perform.
  * These enum values are used both to select the set of checks that
@@ -160,45 +389,61 @@ typedef struct USpoofChecker USpoofChecker; /**< typedef for C of USpoofChecker
  * @stable ICU 4.2
  */
 typedef enum USpoofChecks {
-    /**   Single script confusable test.
-      *   When testing whether two identifiers are confusable, report that they are if
-      *   both are from the same script and they are visually confusable.
-      *   Note: this test is not applicable to a check of a single identifier.
-      */
+    /**
+     * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates
+     * that the two strings are visually confusable and that they are from the same script, according to UTS 39 section
+     * 4.
+     *
+     * @see uspoof_areConfusable
+     * @stable ICU 4.2
+     */
     USPOOF_SINGLE_SCRIPT_CONFUSABLE =   1,
 
-    /** Mixed script confusable test.
-     *  When checking a single identifier, report a problem if
-     *    the identifier contains multiple scripts, and
-     *    is confusable with some other identifier in a single script
-     *  When testing whether two identifiers are confusable, report that they are if
-     *    the two IDs are visually confusable, 
-     *    and at least one contains characters from more than one script.
+    /**
+     * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates
+     * that the two strings are visually confusable and that they are <b>not</b> from the same script, according to UTS
+     * 39 section 4.
+     *
+     * @see uspoof_areConfusable
+     * @stable ICU 4.2
      */
     USPOOF_MIXED_SCRIPT_CONFUSABLE  =   2,
 
-    /** Whole script confusable test.
-     *  When checking a single identifier, report a problem if
-     *    The identifier is of a single script, and
-     *    there exists a confusable identifier in another script.
-     *  When testing whether two identifiers are confusable, report that they are if
-     *    each is of a single script, 
-     *    the scripts of the two identifiers are different, and
-     *    the identifiers are visually confusable.
+    /**
+     * When performing the two-string {@link uspoof_areConfusable} test, this flag in the return value indicates
+     * that the two strings are visually confusable and that they are not from the same script but both of them are
+     * single-script strings, according to UTS 39 section 4.
+     *
+     * @see uspoof_areConfusable
+     * @stable ICU 4.2
      */
     USPOOF_WHOLE_SCRIPT_CONFUSABLE  =   4,
-    
-    /** Any Case Modifier for confusable identifier tests.
-        If specified, consider all characters, of any case, when looking for confusables.
-        If USPOOF_ANY_CASE is not specified, identifiers being checked are assumed to have been
-        case folded.  Upper case confusable characters will not be checked.
-        Selects between Lower Case Confusable and
-        Any Case Confusable.   */
+
+#ifndef U_HIDE_DRAFT_API
+    /**
+     * Enable this flag in {@link uspoof_setChecks} to turn on all types of confusables.  You may set
+     * the checks to some subset of SINGLE_SCRIPT_CONFUSABLE, MIXED_SCRIPT_CONFUSABLE, or WHOLE_SCRIPT_CONFUSABLE to
+     * make {@link uspoof_areConfusable} return only those types of confusables.
+     *
+     * @see uspoof_areConfusable
+     * @see uspoof_getSkeleton
+     * @draft ICU 58
+     */
+    USPOOF_CONFUSABLE               =   USPOOF_SINGLE_SCRIPT_CONFUSABLE | USPOOF_MIXED_SCRIPT_CONFUSABLE | USPOOF_WHOLE_SCRIPT_CONFUSABLE,
+#endif /* U_HIDE_DRAFT_API */
+
+#ifndef U_HIDE_DEPRECATED_API
+    /**
+      * This flag is deprecated and no longer affects the behavior of SpoofChecker.
+      *
+      * @deprecated ICU 58  Any case confusable mappings were removed from UTS 39; the corresponding ICU API was deprecated.
+      */
     USPOOF_ANY_CASE                 =   8,
+#endif  /* U_HIDE_DEPRECATED_API */
 
     /**
       * Check that an identifier is no looser than the specified RestrictionLevel.
-      * The default if uspoof_setRestrctionLevel() is not called is HIGHLY_RESTRICTIVE.
+      * The default if {@link uspoof_setRestrictionLevel} is not called is HIGHLY_RESTRICTIVE.
       *
       * If USPOOF_AUX_INFO is enabled the actual restriction level of the
       * identifier being tested will also be returned by uspoof_check().
@@ -211,7 +456,7 @@ typedef enum USpoofChecks {
       */
     USPOOF_RESTRICTION_LEVEL        = 16,
 
-#ifndef U_HIDE_DEPRECATED_API 
+#ifndef U_HIDE_DEPRECATED_API
     /** Check that an identifier contains only characters from a
       * single script (plus chars from the common and inherited scripts.)
       * Applies to checks of a single identifier check only.
@@ -219,7 +464,7 @@ typedef enum USpoofChecks {
       */
     USPOOF_SINGLE_SCRIPT            =  USPOOF_RESTRICTION_LEVEL,
 #endif  /* U_HIDE_DEPRECATED_API */
-   
+
     /** Check an identifier for the presence of invisible characters,
       * such as zero-width spaces, or character sequences that are
       * likely not to display, such as multiple occurrences of the same
@@ -229,97 +474,119 @@ typedef enum USpoofChecks {
     USPOOF_INVISIBLE                =  32,
 
     /** Check that an identifier contains only characters from a specified set
-      * of acceptable characters.  See uspoof_setAllowedChars() and
-      * uspoof_setAllowedLocales().
+      * of acceptable characters.  See {@link uspoof_setAllowedChars} and
+      * {@link uspoof_setAllowedLocales}.  Note that a string that fails this check
+      * will also fail the {@link USPOOF_RESTRICTION_LEVEL} check.
       */
     USPOOF_CHAR_LIMIT               =  64,
 
    /**
-     * Check that an identifier does not include decimal digits from
-     * more than one numbering system.
-     * 
+     * Check that an identifier does not mix numbers from different numbering systems.
+     * For more information, see UTS 39 section 5.3.
+     *
      * @stable ICU 51
      */
     USPOOF_MIXED_NUMBERS            = 128,
 
    /**
      * Enable all spoof checks.
-     * 
+     *
      * @stable ICU 4.6
      */
     USPOOF_ALL_CHECKS               = 0xFFFF,
 
     /**
       * Enable the return of auxillary (non-error) information in the
-      * upper bits of the check results value. 
+      * upper bits of the check results value.
       *
-      * If this "check" is not enabled, the results of uspoof_check() will be zero when an
-      * identifier passes all of the enabled checks.
+      * If this "check" is not enabled, the results of {@link uspoof_check} will be
+      * zero when an identifier passes all of the enabled checks.
       *
-      * If this "check" is enabled, (uspoof_check() & USPOOF_ALL_CHECKS) will be zero
-      * when an identifier passes all checks.
+      * If this "check" is enabled, (uspoof_check() & {@link USPOOF_ALL_CHECKS}) will
+      * be zero when an identifier passes all checks.
       *
       * @stable ICU 51
       */
     USPOOF_AUX_INFO                  = 0x40000000
 
     } USpoofChecks;
-    
-    
+
+
     /**
-     * Constants from UAX #39 for use in setRestrictionLevel(), and
+     * Constants from UAX #39 for use in {@link uspoof_setRestrictionLevel}, and
      * for returned identifier restriction levels in check results.
+     *
      * @stable ICU 51
+     *
+     * @see uspoof_setRestrictionLevel
+     * @see uspoof_check
      */
     typedef enum URestrictionLevel {
         /**
-         * Only ASCII characters: U+0000..U+007F
-         * 
+         * All characters in the string are in the identifier profile and all characters in the string are in the
+         * ASCII range.
+         *
          * @stable ICU 51
          */
         USPOOF_ASCII = 0x10000000,
         /**
-          * All characters in each identifier must be from a single script.
-          *
-          * @stable ICU 53
-          */
+         * The string classifies as ASCII-Only, or all characters in the string are in the identifier profile and
+         * the string is single-script, according to the definition in UTS 39 section 5.1.
+         *
+         * @stable ICU 53
+         */
         USPOOF_SINGLE_SCRIPT_RESTRICTIVE = 0x20000000,
         /**
-         * All characters in each identifier must be from a single script, or from the combinations: Latin + Han +
-         * Hiragana + Katakana; Latin + Han + Bopomofo; or Latin + Han + Hangul. Note that this level will satisfy the
-         * vast majority of Latin-script users; also that TR36 has ASCII instead of Latin.
-         * 
+         * The string classifies as Single Script, or all characters in the string are in the identifier profile and
+         * the string is covered by any of the following sets of scripts, according to the definition in UTS 39
+         * section 5.1:
+         * <ul>
+         *   <li>Latin + Han + Bopomofo (or equivalently: Latn + Hanb)</li>
+         *   <li>Latin + Han + Hiragana + Katakana (or equivalently: Latn + Jpan)</li>
+         *   <li>Latin + Han + Hangul (or equivalently: Latn +Kore)</li>
+         * </ul>
+         * This is the default restriction in ICU.
+         *
          * @stable ICU 51
          */
         USPOOF_HIGHLY_RESTRICTIVE = 0x30000000,
         /**
-         * Allow Latin with other scripts except Cyrillic, Greek, Cherokee Otherwise, the same as Highly Restrictive
-         * 
+         * The string classifies as Highly Restrictive, or all characters in the string are in the identifier profile
+         * and the string is covered by Latin and any one other Recommended or Aspirational script, except Cyrillic,
+         * Greek, and Cherokee.
+         *
          * @stable ICU 51
          */
         USPOOF_MODERATELY_RESTRICTIVE = 0x40000000,
         /**
-         * Allow arbitrary mixtures of scripts. Otherwise, the same as Moderately Restrictive.
-         * 
+         * All characters in the string are in the identifier profile.  Allow arbitrary mixtures of scripts.
+         *
          * @stable ICU 51
          */
         USPOOF_MINIMALLY_RESTRICTIVE = 0x50000000,
         /**
          * Any valid identifiers, including characters outside of the Identifier Profile.
-         * 
+         *
          * @stable ICU 51
          */
         USPOOF_UNRESTRICTIVE = 0x60000000,
         /**
-          * Mask for selecting the Restriction Level bits from the return value of uspoof_check().
-          * 
-          * @stable ICU 53
-          */
-         USPOOF_RESTRICTION_LEVEL_MASK = 0x7F000000 
+         * Mask for selecting the Restriction Level bits from the return value of {@link uspoof_check}.
+         *
+         * @stable ICU 53
+         */
+        USPOOF_RESTRICTION_LEVEL_MASK = 0x7F000000,
+#ifndef U_HIDE_INTERNAL_API
+        /**
+         * An undefined restriction level.
+         * @internal
+         */
+        USPOOF_UNDEFINED_RESTRICTIVE = -1
+#endif  /* U_HIDE_INTERNAL_API */
     } URestrictionLevel;
 
 /**
- *  Create a Unicode Spoof Checker, configured to perform all 
+ *  Create a Unicode Spoof Checker, configured to perform all
  *  checks except for USPOOF_LOCALE_LIMIT and USPOOF_CHAR_LIMIT.
  *  Note that additional checks may be added in the future,
  *  resulting in the changes to the default checking behavior.
@@ -359,10 +626,10 @@ uspoof_openFromSerialized(const void *data, int32_t length, int32_t *pActualLeng
 
 /**
   * Open a Spoof Checker from the source form of the spoof data.
-  * The two inputs correspond to the Unicode data files confusables.txt
-  * and confusablesWholeScript.txt as described in Unicode UAX #39.
-  * The syntax of the source data is as described in UAX #39 for
-  * these files, and the content of these files is acceptable input.
+  * The input corresponds to the Unicode data file confusables.txt
+  * as described in Unicode UAX #39.  The syntax of the source data
+  * is as described in UAX #39 for this file, and the content of
+  * this file is acceptable input.
   *
   * The character encoding of the (char *) input text is UTF-8.
   *
@@ -371,10 +638,9 @@ uspoof_openFromSerialized(const void *data, int32_t length, int32_t *pActualLeng
   * @param confusablesLen The length of the confusables text, or -1 if the
   *                    input string is zero terminated.
   * @param confusablesWholeScript
-  *                    a pointer to the whole script confusables definitions,
-  *                    as found in the file confusablesWholeScript.txt from unicode.org.
-  * @param confusablesWholeScriptLen The length of the whole script confusables text, or
-  *                    -1 if the input string is zero terminated.
+  *                    Deprecated in ICU 58.  No longer used.
+  * @param confusablesWholeScriptLen
+  *                    Deprecated in ICU 58.  No longer used.
   * @param errType     In the event of an error in the input, indicates
   *                    which of the input files contains the error.
   *                    The value is one of USPOOF_SINGLE_SCRIPT_CONFUSABLE or
@@ -435,8 +701,33 @@ uspoof_clone(const USpoofChecker *sc, UErrorCode *status);
 
 
 /**
- * Specify the set of checks that will be performed by the check
- * functions of this Spoof Checker.
+ * Specify the bitmask of checks that will be performed by {@link uspoof_check}. Calling this method
+ * overwrites any checks that may have already been enabled. By default, all checks are enabled.
+ *
+ * To enable specific checks and disable all others, the "whitelisted" checks should be ORed together. For
+ * example, to fail strings containing characters outside of the set specified by {@link uspoof_setAllowedChars} and
+ * also strings that contain digits from mixed numbering systems:
+ *
+ * <pre>
+ * {@code
+ * uspoof_setChecks(USPOOF_CHAR_LIMIT | USPOOF_MIXED_NUMBERS);
+ * }
+ * </pre>
+ *
+ * To disable specific checks and enable all others, the "blacklisted" checks should be ANDed away from
+ * ALL_CHECKS. For example, if you are not planning to use the {@link uspoof_areConfusable} functionality,
+ * it is good practice to disable the CONFUSABLE check:
+ *
+ * <pre>
+ * {@code
+ * uspoof_setChecks(USPOOF_ALL_CHECKS & ~USPOOF_CONFUSABLE);
+ * }
+ * </pre>
+ *
+ * Note that methods such as {@link uspoof_setAllowedChars}, {@link uspoof_setAllowedLocales}, and
+ * {@link uspoof_setRestrictionLevel} will enable certain checks when called. Those methods will OR the check they
+ * enable onto the existing bitmask specified by this method. For more details, see the documentation of those
+ * methods.
  *
  * @param sc       The USpoofChecker
  * @param checks         The set of checks that this spoof checker will perform.
@@ -451,7 +742,7 @@ uspoof_setChecks(USpoofChecker *sc, int32_t checks, UErrorCode *status);
 
 /**
  * Get the set of checks that this Spoof Checker has been configured to perform.
- * 
+ *
  * @param sc       The USpoofChecker
  * @param status   The error code, set if this function encounters a problem.
  * @return         The set of checks that this spoof checker will perform.
@@ -464,19 +755,22 @@ U_STABLE int32_t U_EXPORT2
 uspoof_getChecks(const USpoofChecker *sc, UErrorCode *status);
 
 /**
-  * Set the loosest restriction level allowed. The default if this function 
-  * is not called is HIGHLY_RESTRICTIVE.
-  * Calling this function also enables the RESTRICTION_LEVEL check.
-  * @param restrictionLevel The loosest restriction level allowed.
-  * @see URestrictionLevel
-  * @stable ICU 51
-  */
+ * Set the loosest restriction level allowed for strings. The default if this is not called is
+ * {@link USPOOF_HIGHLY_RESTRICTIVE}. Calling this method enables the {@link USPOOF_RESTRICTION_LEVEL} and
+ * {@link USPOOF_MIXED_NUMBERS} checks, corresponding to Sections 5.1 and 5.2 of UTS 39. To customize which checks are
+ * to be performed by {@link uspoof_check}, see {@link uspoof_setChecks}.
+ *
+ * @param sc       The USpoofChecker
+ * @param restrictionLevel The loosest restriction level allowed.
+ * @see URestrictionLevel
+ * @stable ICU 51
+ */
 U_STABLE void U_EXPORT2
 uspoof_setRestrictionLevel(USpoofChecker *sc, URestrictionLevel restrictionLevel);
 
 
 /**
-  * Get the Restriction Level that will be tested if the checks include RESTRICTION_LEVEL.
+  * Get the Restriction Level that will be tested if the checks include {@link USPOOF_RESTRICTION_LEVEL}.
   *
   * @return The restriction level
   * @see URestrictionLevel
@@ -486,7 +780,7 @@ U_STABLE URestrictionLevel U_EXPORT2
 uspoof_getRestrictionLevel(const USpoofChecker *sc);
 
 /**
- * Limit characters that are acceptable in identifiers being checked to those 
+ * Limit characters that are acceptable in identifiers being checked to those
  * normally used with the languages associated with the specified locales.
  * Any previously specified list of locales is replaced by the new settings.
  *
@@ -499,7 +793,7 @@ uspoof_getRestrictionLevel(const USpoofChecker *sc);
  * Supplying an empty string removes all restrictions;
  * characters from any script will be allowed.
  *
- * The USPOOF_CHAR_LIMIT test is automatically enabled for this
+ * The {@link USPOOF_CHAR_LIMIT} test is automatically enabled for this
  * USpoofChecker when calling this function with a non-empty list
  * of locales.
  *
@@ -511,9 +805,9 @@ uspoof_getRestrictionLevel(const USpoofChecker *sc);
  * can be made to the result of uspoof_setAllowedLocales() by
  * fetching the resulting set with uspoof_getAllowedChars(),
  * manipulating it with the Unicode Set API, then resetting the
- * spoof detectors limits with uspoof_setAllowedChars()
+ * spoof detectors limits with uspoof_setAllowedChars().
  *
- * @param sc           The USpoofChecker 
+ * @param sc           The USpoofChecker
  * @param localesList  A list list of locales, from which the language
  *                     and associated script are extracted.  The locales
  *                     are comma-separated if there is more than one.
@@ -537,18 +831,18 @@ uspoof_setAllowedLocales(USpoofChecker *sc, const char *localesList, UErrorCode
  *
  *  uspoof_setAllowedChars() will reset the list of allowed to be empty.
  *
- *  The format of the returned list is the same as that supplied to 
- *  uspoof_setAllowedLocales(), but returned list may not be identical 
- *  to the originally specified string; the string may be reformatted, 
+ *  The format of the returned list is the same as that supplied to
+ *  uspoof_setAllowedLocales(), but returned list may not be identical
+ *  to the originally specified string; the string may be reformatted,
  *  and information other than languages from
  *  the originally specified locales may be omitted.
  *
- * @param sc           The USpoofChecker 
+ * @param sc           The USpoofChecker
  * @param status       The error code, set if this function encounters a problem.
  * @return             A string containing a list of  locales corresponding
  *                     to the acceptable scripts, formatted like an
  *                     HTTP Accept Language value.
- *  
+ *
  * @stable ICU 4.2
  */
 U_STABLE const char * U_EXPORT2
@@ -564,7 +858,7 @@ uspoof_getAllowedLocales(USpoofChecker *sc, UErrorCode *status);
  * The USPOOF_CHAR_LIMIT test is automatically enabled for this
  * USpoofChecker by this function.
  *
- * @param sc       The USpoofChecker 
+ * @param sc       The USpoofChecker
  * @param chars    A Unicode Set containing the list of
  *                 characters that are permitted.  Ownership of the set
  *                 remains with the caller.  The incoming set is cloned by
@@ -591,7 +885,7 @@ uspoof_setAllowedChars(USpoofChecker *sc, const USet *chars, UErrorCode *status)
  * or if a new set of allowed characters is specified.
  *
  *
- * @param sc       The USpoofChecker 
+ * @param sc       The USpoofChecker
  * @param status   The error code, set if this function encounters a problem.
  * @return         A USet containing the characters that are permitted by
  *                 the USPOOF_CHAR_LIMIT test.
@@ -611,7 +905,7 @@ uspoof_getAllowedChars(const USpoofChecker *sc, UErrorCode *status);
  * The USPOOF_CHAR_LIMIT test is automatically enabled for this
  * USoofChecker by this function.
  *
- * @param sc       The USpoofChecker 
+ * @param sc       The USpoofChecker
  * @param chars    A Unicode Set containing the list of
  *                 characters that are permitted.  Ownership of the set
  *                 remains with the caller.  The incoming set is cloned by
@@ -626,7 +920,7 @@ uspoof_setAllowedUnicodeSet(USpoofChecker *sc, const icu::UnicodeSet *chars, UEr
 
 /**
  * Get a UnicodeSet for the characters permitted in an identifier.
- * This corresponds to the limits imposed by the Set Allowed Characters / 
+ * This corresponds to the limits imposed by the Set Allowed Characters /
  * UnicodeSet functions. Limitations imposed by other checks will not be
  * reflected in the set returned by this function.
  *
@@ -638,7 +932,7 @@ uspoof_setAllowedUnicodeSet(USpoofChecker *sc, const icu::UnicodeSet *chars, UEr
  * or if a new set of allowed characters is specified.
  *
  *
- * @param sc       The USpoofChecker 
+ * @param sc       The USpoofChecker
  * @param status   The error code, set if this function encounters a problem.
  * @return         A UnicodeSet containing the characters that are permitted by
  *                 the USPOOF_CHAR_LIMIT test.
@@ -653,17 +947,22 @@ uspoof_getAllowedUnicodeSet(const USpoofChecker *sc, UErrorCode *status);
  * Check the specified string for possible security issues.
  * The text to be checked will typically be an identifier of some sort.
  * The set of checks to be performed is specified with uspoof_setChecks().
- * 
- * @param sc      The USpoofChecker 
+ *
+ * \note
+ *   Consider using the newer API, {@link uspoof_check2}, instead.
+ *   The newer API exposes additional information from the check procedure
+ *   and is otherwise identical to this method.
+ *
+ * @param sc      The USpoofChecker
  * @param id      The identifier to be checked for possible security issues,
  *                in UTF-16 format.
  * @param length  the length of the string to be checked, expressed in
- *                16 bit UTF-16 code units, or -1 if the string is 
+ *                16 bit UTF-16 code units, or -1 if the string is
  *                zero terminated.
- * @param position      An out parameter.
- *                Originally, the index of the first string position that failed a check.
- *                Now, always returns zero.
- *                This parameter may be null.
+ * @param position  Deprecated in ICU 51.  Always returns zero.
+ *                Originally, an out parameter for the index of the first
+ *                string position that failed a check.
+ *                This parameter may be NULL.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
  *                Spoofing or security issues detected with the input string are
@@ -673,11 +972,12 @@ uspoof_getAllowedUnicodeSet(const USpoofChecker *sc, UErrorCode *status);
  *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
  *                will be zero if the input string passes all of the
  *                enabled checks.
+ * @see uspoof_check2
  * @stable ICU 4.2
  */
 U_STABLE int32_t U_EXPORT2
 uspoof_check(const USpoofChecker *sc,
-                         const UChar *id, int32_t length, 
+                         const UChar *id, int32_t length,
                          int32_t *position,
                          UErrorCode *status);
 
@@ -686,16 +986,20 @@ uspoof_check(const USpoofChecker *sc,
  * Check the specified string for possible security issues.
  * The text to be checked will typically be an identifier of some sort.
  * The set of checks to be performed is specified with uspoof_setChecks().
- * 
- * @param sc      The USpoofChecker 
+ *
+ * \note
+ *   Consider using the newer API, {@link uspoof_check2UTF8}, instead.
+ *   The newer API exposes additional information from the check procedure
+ *   and is otherwise identical to this method.
+ *
+ * @param sc      The USpoofChecker
  * @param id      A identifier to be checked for possible security issues, in UTF8 format.
- * @param length  the length of the string to be checked, or -1 if the string is 
+ * @param length  the length of the string to be checked, or -1 if the string is
  *                zero terminated.
- * @param position      An out parameter.
- *                Originally, the index of the first string position that failed a check.
- *                Now, always returns zero.
- *                This parameter may be null.
- *                @deprecated ICU 51
+ * @param position  Deprecated in ICU 51.  Always returns zero.
+ *                Originally, an out parameter for the index of the first
+ *                string position that failed a check.
+ *                This parameter may be NULL.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
  *                Spoofing or security issues detected with the input string are
@@ -707,6 +1011,7 @@ uspoof_check(const USpoofChecker *sc,
  *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
  *                will be zero if the input string passes all of the
  *                enabled checks.
+ * @see uspoof_check2UTF8
  * @stable ICU 4.2
  */
 U_STABLE int32_t U_EXPORT2
@@ -721,14 +1026,18 @@ uspoof_checkUTF8(const USpoofChecker *sc,
  * Check the specified string for possible security issues.
  * The text to be checked will typically be an identifier of some sort.
  * The set of checks to be performed is specified with uspoof_setChecks().
- * 
- * @param sc      The USpoofChecker 
+ *
+ * \note
+ *   Consider using the newer API, {@link uspoof_check2UnicodeString}, instead.
+ *   The newer API exposes additional information from the check procedure
+ *   and is otherwise identical to this method.
+ *
+ * @param sc      The USpoofChecker
  * @param id      A identifier to be checked for possible security issues.
- * @param position      An out parameter.
- *                Originally, the index of the first string position that failed a check.
- *                Now, always returns zero.
- *                This parameter may be null.
- *                @deprecated ICU 51
+ * @param position  Deprecated in ICU 51.  Always returns zero.
+ *                Originally, an out parameter for the index of the first
+ *                string position that failed a check.
+ *                This parameter may be NULL.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
  *                Spoofing or security issues detected with the input string are
@@ -738,45 +1047,249 @@ uspoof_checkUTF8(const USpoofChecker *sc,
  *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
  *                will be zero if the input string passes all of the
  *                enabled checks.
+ * @see uspoof_check2UnicodeString
  * @stable ICU 4.2
  */
 U_STABLE int32_t U_EXPORT2
 uspoof_checkUnicodeString(const USpoofChecker *sc,
-                          const icu::UnicodeString &id, 
+                          const icu::UnicodeString &id,
                           int32_t *position,
                           UErrorCode *status);
+#endif
+
+
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Check the specified string for possible security issues.
+ * The text to be checked will typically be an identifier of some sort.
+ * The set of checks to be performed is specified with uspoof_setChecks().
+ *
+ * @param sc      The USpoofChecker
+ * @param id      The identifier to be checked for possible security issues,
+ *                in UTF-16 format.
+ * @param length  the length of the string to be checked, or -1 if the string is
+ *                zero terminated.
+ * @param checkResult  An instance of USpoofCheckResult to be filled with
+ *                details about the identifier.  Can be NULL.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.
+ *                Spoofing or security issues detected with the input string are
+ *                not reported here, but through the function's return value.
+ * @return        An integer value with bits set for any potential security
+ *                or spoofing issues detected.  The bits are defined by
+ *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
+ *                will be zero if the input string passes all of the
+ *                enabled checks.  Any information in this bitmask will be
+ *                consistent with the information saved in the optional
+ *                checkResult parameter.
+ * @see uspoof_openCheckResult
+ * @see uspoof_check2UTF8
+ * @see uspoof_check2UnicodeString
+ * @draft ICU 58
+ */
+U_DRAFT int32_t U_EXPORT2
+uspoof_check2(const USpoofChecker *sc,
+    const UChar* id, int32_t length,
+    USpoofCheckResult* checkResult,
+    UErrorCode *status);
 
+/**
+ * Check the specified string for possible security issues.
+ * The text to be checked will typically be an identifier of some sort.
+ * The set of checks to be performed is specified with uspoof_setChecks().
+ *
+ * This version of {@link uspoof_check} accepts a USpoofCheckResult, which
+ * returns additional information about the identifier.  For more
+ * information, see {@link uspoof_openCheckResult}.
+ *
+ * @param sc      The USpoofChecker
+ * @param id      A identifier to be checked for possible security issues, in UTF8 format.
+ * @param length  the length of the string to be checked, or -1 if the string is
+ *                zero terminated.
+ * @param checkResult  An instance of USpoofCheckResult to be filled with
+ *                details about the identifier.  Can be NULL.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.
+ *                Spoofing or security issues detected with the input string are
+ *                not reported here, but through the function's return value.
+ * @return        An integer value with bits set for any potential security
+ *                or spoofing issues detected.  The bits are defined by
+ *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
+ *                will be zero if the input string passes all of the
+ *                enabled checks.  Any information in this bitmask will be
+ *                consistent with the information saved in the optional
+ *                checkResult parameter.
+ * @see uspoof_openCheckResult
+ * @see uspoof_check2
+ * @see uspoof_check2UnicodeString
+ * @draft ICU 58
+ */
+U_DRAFT int32_t U_EXPORT2
+uspoof_check2UTF8(const USpoofChecker *sc,
+    const char *id, int32_t length,
+    USpoofCheckResult* checkResult,
+    UErrorCode *status);
+
+#if U_SHOW_CPLUSPLUS_API
+/**
+ * Check the specified string for possible security issues.
+ * The text to be checked will typically be an identifier of some sort.
+ * The set of checks to be performed is specified with uspoof_setChecks().
+ *
+ * @param sc      The USpoofChecker
+ * @param id      A identifier to be checked for possible security issues.
+ * @param checkResult  An instance of USpoofCheckResult to be filled with
+ *                details about the identifier.  Can be NULL.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.
+ *                Spoofing or security issues detected with the input string are
+ *                not reported here, but through the function's return value.
+ * @return        An integer value with bits set for any potential security
+ *                or spoofing issues detected.  The bits are defined by
+ *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
+ *                will be zero if the input string passes all of the
+ *                enabled checks.  Any information in this bitmask will be
+ *                consistent with the information saved in the optional
+ *                checkResult parameter.
+ * @see uspoof_openCheckResult
+ * @see uspoof_check2
+ * @see uspoof_check2UTF8
+ * @draft ICU 58
+ */
+U_DRAFT int32_t U_EXPORT2
+uspoof_check2UnicodeString(const USpoofChecker *sc,
+    const icu::UnicodeString &id,
+    USpoofCheckResult* checkResult,
+    UErrorCode *status);
 #endif
 
+/**
+ * Create a USpoofCheckResult, used by the {@link uspoof_check2} class of functions to return
+ * information about the identifier.  Information includes:
+ * <ul>
+ *   <li>A bitmask of the checks that failed</li>
+ *   <li>The identifier's restriction level (UTS 39 section 5.2)</li>
+ *   <li>The set of numerics in the string (UTS 39 section 5.3)</li>
+ * </ul>
+ * The data held in a USpoofCheckResult is cleared whenever it is passed into a new call
+ * of {@link uspoof_check2}.
+ *
+ * @param status  The error code, set if this function encounters a problem.
+ * @return        the newly created USpoofCheckResult
+ * @see uspoof_check2
+ * @see uspoof_check2UTF8
+ * @see uspoof_check2UnicodeString
+ * @draft ICU 58
+ */
+U_DRAFT USpoofCheckResult* U_EXPORT2
+uspoof_openCheckResult(UErrorCode *status);
+
+/**
+ * Close a USpoofCheckResult, freeing any memory that was being held by
+ *   its implementation.
+ *
+ * @param checkResult  The instance of USpoofCheckResult to close
+ * @draft ICU 58
+ */
+U_DRAFT void U_EXPORT2
+uspoof_closeCheckResult(USpoofCheckResult *checkResult);
+
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalUSpoofCheckResultPointer
+ * "Smart pointer" class, closes a USpoofCheckResult via {@link uspoof_closeCheckResult}.
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @draft ICU 58
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUSpoofCheckResultPointer, USpoofCheckResult, uspoof_closeCheckResult);
+
+U_NAMESPACE_END
+
+#endif
+
+/**
+ * Indicates which of the spoof check(s) have failed. The value is a bitwise OR of the constants for the tests
+ * in question: USPOOF_RESTRICTION_LEVEL, USPOOF_CHAR_LIMIT, and so on.
+ *
+ * @param checkResult  The instance of USpoofCheckResult created by {@link uspoof_openCheckResult}
+ * @param status       The error code, set if an error occurred.
+ * @return        An integer value with bits set for any potential security
+ *                or spoofing issues detected.  The bits are defined by
+ *                enum USpoofChecks.  (returned_value & USPOOF_ALL_CHECKS)
+ *                will be zero if the input string passes all of the
+ *                enabled checks.
+ * @see uspoof_setChecks
+ * @draft ICU 58
+ */
+U_DRAFT int32_t U_EXPORT2
+uspoof_getCheckResultChecks(const USpoofCheckResult *checkResult, UErrorCode *status);
+
+/**
+ * Gets the restriction level that the text meets, if the USPOOF_RESTRICTION_LEVEL check
+ * was enabled; otherwise, undefined.
+ *
+ * @param checkResult  The instance of USpoofCheckResult created by {@link uspoof_openCheckResult}
+ * @param status       The error code, set if an error occurred.
+ * @return             The restriction level contained in the USpoofCheckResult
+ * @see uspoof_setRestrictionLevel
+ * @draft ICU 58
+ */
+U_DRAFT URestrictionLevel U_EXPORT2
+uspoof_getCheckResultRestrictionLevel(const USpoofCheckResult *checkResult, UErrorCode *status);
+
+/**
+ * Gets the set of numerics found in the string, if the USPOOF_MIXED_NUMBERS check was enabled;
+ * otherwise, undefined.  The set will contain the zero digit from each decimal number system found
+ * in the input string.  Ownership of the returned USet remains with the USpoofCheckResult.
+ * The USet will be free'd when {@link uspoof_closeCheckResult} is called.
+ *
+ * @param checkResult  The instance of USpoofCheckResult created by {@link uspoof_openCheckResult}
+ * @return             The set of numerics contained in the USpoofCheckResult
+ * @param status       The error code, set if an error occurred.
+ * @draft ICU 58
+ */
+U_DRAFT const USet* U_EXPORT2
+uspoof_getCheckResultNumerics(const USpoofCheckResult *checkResult, UErrorCode *status);
+#endif /* U_HIDE_DRAFT_API */
+
 
 /**
  * Check the whether two specified strings are visually confusable.
- * The types of confusability to be tested - single script, mixed script,
- * or whole script - are determined by the check options set for the
- * USpoofChecker.
- *
- * The tests to be performed are controlled by the flags
- *   USPOOF_SINGLE_SCRIPT_CONFUSABLE 
- *   USPOOF_MIXED_SCRIPT_CONFUSABLE  
- *   USPOOF_WHOLE_SCRIPT_CONFUSABLE
- * At least one of these tests must be selected.
- * 
- * USPOOF_ANY_CASE is a modifier for the tests.  Select it if the identifiers
- *   may be of mixed case.
- * If identifiers are case folded for comparison and
- * display to the user, do not select the USPOOF_ANY_CASE option.
+ *
+ * If the strings are confusable, the return value will be nonzero, as long as
+ * {@link USPOOF_CONFUSABLE} was enabled in uspoof_setChecks().
+ *
+ * The bits in the return value correspond to flags for each of the classes of
+ * confusables applicable to the two input strings.  According to UTS 39
+ * section 4, the possible flags are:
+ *
+ * <ul>
+ *   <li>{@link USPOOF_SINGLE_SCRIPT_CONFUSABLE}</li>
+ *   <li>{@link USPOOF_MIXED_SCRIPT_CONFUSABLE}</li>
+ *   <li>{@link USPOOF_WHOLE_SCRIPT_CONFUSABLE}</li>
+ * </ul>
+ *
+ * If one or more of the above flags were not listed in uspoof_setChecks(), this
+ * function will never report that class of confusable.  The check
+ * {@link USPOOF_CONFUSABLE} enables all three flags.
  *
  *
  * @param sc      The USpoofChecker
- * @param id1     The first of the two identifiers to be compared for 
+ * @param id1     The first of the two identifiers to be compared for
  *                confusability.  The strings are in UTF-16 format.
  * @param length1 the length of the first identifer, expressed in
- *                16 bit UTF-16 code units, or -1 if the string is 
+ *                16 bit UTF-16 code units, or -1 if the string is
  *                nul terminated.
- * @param id2     The second of the two identifiers to be compared for 
+ * @param id2     The second of the two identifiers to be compared for
  *                confusability.  The identifiers are in UTF-16 format.
  * @param length2 The length of the second identifiers, expressed in
- *                16 bit UTF-16 code units, or -1 if the string is 
+ *                16 bit UTF-16 code units, or -1 if the string is
  *                nul terminated.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
@@ -786,6 +1299,7 @@ uspoof_checkUnicodeString(const USpoofChecker *sc,
  *                the type of confusability found, as defined by
  *                enum USpoofChecks.  Zero is returned if the identifiers
  *                are not confusable.
+ *
  * @stable ICU 4.2
  */
 U_STABLE int32_t U_EXPORT2
@@ -797,19 +1311,16 @@ uspoof_areConfusable(const USpoofChecker *sc,
 
 
 /**
- * Check the whether two specified strings are visually confusable.
- * The types of confusability to be tested - single script, mixed script,
- * or whole script - are determined by the check options set for the
- * USpoofChecker.
+ * A version of {@link uspoof_areConfusable} accepting strings in UTF-8 format.
  *
  * @param sc      The USpoofChecker
- * @param id1     The first of the two identifiers to be compared for 
+ * @param id1     The first of the two identifiers to be compared for
  *                confusability.  The strings are in UTF-8 format.
- * @param length1 the length of the first identifiers, in bytes, or -1 
+ * @param length1 the length of the first identifiers, in bytes, or -1
  *                if the string is nul terminated.
- * @param id2     The second of the two identifiers to be compared for 
+ * @param id2     The second of the two identifiers to be compared for
  *                confusability.  The strings are in UTF-8 format.
- * @param length2 The length of the second string in bytes, or -1 
+ * @param length2 The length of the second string in bytes, or -1
  *                if the string is nul terminated.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
@@ -819,7 +1330,10 @@ uspoof_areConfusable(const USpoofChecker *sc,
  *                the type of confusability found, as defined by
  *                enum USpoofChecks.  Zero is returned if the strings
  *                are not confusable.
+ *
  * @stable ICU 4.2
+ *
+ * @see uspoof_areConfusable
  */
 U_STABLE int32_t U_EXPORT2
 uspoof_areConfusableUTF8(const USpoofChecker *sc,
@@ -832,15 +1346,12 @@ uspoof_areConfusableUTF8(const USpoofChecker *sc,
 
 #if U_SHOW_CPLUSPLUS_API
 /**
- * Check the whether two specified strings are visually confusable.
- * The types of confusability to be tested - single script, mixed script,
- * or whole script - are determined by the check options set for the
- * USpoofChecker.
+ * A version of {@link uspoof_areConfusable} accepting UnicodeStrings.
  *
  * @param sc      The USpoofChecker
- * @param s1     The first of the two identifiers to be compared for 
+ * @param s1     The first of the two identifiers to be compared for
  *                confusability.  The strings are in UTF-8 format.
- * @param s2     The second of the two identifiers to be compared for 
+ * @param s2     The second of the two identifiers to be compared for
  *                confusability.  The strings are in UTF-8 format.
  * @param status  The error code, set if an error occurred while attempting to
  *                perform the check.
@@ -850,7 +1361,10 @@ uspoof_areConfusableUTF8(const USpoofChecker *sc,
  *                the type of confusability found, as defined by
  *                enum USpoofChecks.  Zero is returned if the identifiers
  *                are not confusable.
+ *
  * @stable ICU 4.2
+ *
+ * @see uspoof_areConfusable
  */
 U_STABLE int32_t U_EXPORT2
 uspoof_areConfusableUnicodeString(const USpoofChecker *sc,
@@ -861,112 +1375,107 @@ uspoof_areConfusableUnicodeString(const USpoofChecker *sc,
 
 
 /**
-  *  Get the "skeleton" for an identifier.
-  *  Skeletons are a transformation of the input identifier;
-  *  Two identifiers are confusable if their skeletons are identical.
-  *  See Unicode UAX #39 for additional information.
-  *
-  *  Using skeletons directly makes it possible to quickly check
-  *  whether an identifier is confusable with any of some large
-  *  set of existing identifiers, by creating an efficiently
-  *  searchable collection of the skeletons.
-  *
-  * @param sc      The USpoofChecker
-  * @param type    The type of skeleton, corresponding to which
-  *                of the Unicode confusable data tables to use.
-  *                The default is Mixed-Script, Lowercase.
-  *                Allowed options are USPOOF_SINGLE_SCRIPT_CONFUSABLE and
-  *                USPOOF_ANY_CASE.  The two flags may be ORed.
-  * @param id      The input identifier whose skeleton will be computed.
-  * @param length  The length of the input identifier, expressed in 16 bit
-  *                UTF-16 code units, or -1 if the string is zero terminated.
-  * @param dest    The output buffer, to receive the skeleton string.
-  * @param destCapacity  The length of the output buffer, in 16 bit units.
-  *                The destCapacity may be zero, in which case the function will
-  *                return the actual length of the skeleton.
-  * @param status  The error code, set if an error occurred while attempting to
-  *                perform the check.
-  * @return        The length of the skeleton string.  The returned length
-  *                is always that of the complete skeleton, even when the
-  *                supplied buffer is too small (or of zero length)
-  *                
-  * @stable ICU 4.2
-  */
+ *  Get the "skeleton" for an identifier.
+ *  Skeletons are a transformation of the input identifier;
+ * Two identifiers are confusable if their skeletons are identical.
+ *  See Unicode UAX #39 for additional information.
+ *
+ *  Using skeletons directly makes it possible to quickly check
+ *  whether an identifier is confusable with any of some large
+ *  set of existing identifiers, by creating an efficiently
+ *  searchable collection of the skeletons.
+ *
+ * @param sc      The USpoofChecker
+ * @param type    Deprecated in ICU 58.  You may pass any number.
+ *                Originally, controlled which of the Unicode confusable data
+ *                tables to use.
+ * @param id      The input identifier whose skeleton will be computed.
+ * @param length  The length of the input identifier, expressed in 16 bit
+ *                UTF-16 code units, or -1 if the string is zero terminated.
+ * @param dest    The output buffer, to receive the skeleton string.
+ * @param destCapacity  The length of the output buffer, in 16 bit units.
+ *                The destCapacity may be zero, in which case the function will
+ *                return the actual length of the skeleton.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.
+ * @return        The length of the skeleton string.  The returned length
+ *                is always that of the complete skeleton, even when the
+ *                supplied buffer is too small (or of zero length)
+ *
+ * @stable ICU 4.2
+ * @see uspoof_areConfusable
+ */
 U_STABLE int32_t U_EXPORT2
 uspoof_getSkeleton(const USpoofChecker *sc,
                    uint32_t type,
                    const UChar *id,  int32_t length,
                    UChar *dest, int32_t destCapacity,
                    UErrorCode *status);
-    
+
 /**
-  *  Get the "skeleton" for an identifier.
-  *  Skeletons are a transformation of the input identifier;
-  *  Two identifiers are confusable if their skeletons are identical.
-  *  See Unicode UAX #39 for additional information.
-  *
-  *  Using skeletons directly makes it possible to quickly check
-  *  whether an identifier is confusable with any of some large
-  *  set of existing identifiers, by creating an efficiently
-  *  searchable collection of the skeletons.
-  *
-  * @param sc      The USpoofChecker 
-  * @param type    The type of skeleton, corresponding to which
-  *                of the Unicode confusable data tables to use.
-  *                The default is Mixed-Script, Lowercase.
-  *                Allowed options are USPOOF_SINGLE_SCRIPT_CONFUSABLE and
-  *                USPOOF_ANY_CASE.  The two flags may be ORed.
-  * @param id      The UTF-8 format identifier whose skeleton will be computed.
-  * @param length  The length of the input string, in bytes,
-  *                or -1 if the string is zero terminated.
-  * @param dest    The output buffer, to receive the skeleton string.
-  * @param destCapacity  The length of the output buffer, in bytes.
-  *                The destCapacity may be zero, in which case the function will
-  *                return the actual length of the skeleton.
-  * @param status  The error code, set if an error occurred while attempting to
-  *                perform the check.  Possible Errors include U_INVALID_CHAR_FOUND
-  *                   for invalid UTF-8 sequences, and
-  *                   U_BUFFER_OVERFLOW_ERROR if the destination buffer is too small
-  *                   to hold the complete skeleton.
-  * @return        The length of the skeleton string, in bytes.  The returned length
-  *                is always that of the complete skeleton, even when the
-  *                supplied buffer is too small (or of zero length)
-  *                
-  * @stable ICU 4.2
-  */   
+ *  Get the "skeleton" for an identifier.
+ *  Skeletons are a transformation of the input identifier;
+ *  Two identifiers are confusable if their skeletons are identical.
+ *  See Unicode UAX #39 for additional information.
+ *
+ *  Using skeletons directly makes it possible to quickly check
+ *  whether an identifier is confusable with any of some large
+ *  set of existing identifiers, by creating an efficiently
+ *  searchable collection of the skeletons.
+ *
+ * @param sc      The USpoofChecker
+ * @param type    Deprecated in ICU 58.  You may pass any number.
+ *                Originally, controlled which of the Unicode confusable data
+ *                tables to use.
+ * @param id      The UTF-8 format identifier whose skeleton will be computed.
+ * @param length  The length of the input string, in bytes,
+ *                or -1 if the string is zero terminated.
+ * @param dest    The output buffer, to receive the skeleton string.
+ * @param destCapacity  The length of the output buffer, in bytes.
+ *                The destCapacity may be zero, in which case the function will
+ *                return the actual length of the skeleton.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.  Possible Errors include U_INVALID_CHAR_FOUND
+ *                   for invalid UTF-8 sequences, and
+ *                   U_BUFFER_OVERFLOW_ERROR if the destination buffer is too small
+ *                   to hold the complete skeleton.
+ * @return        The length of the skeleton string, in bytes.  The returned length
+ *                is always that of the complete skeleton, even when the
+ *                supplied buffer is too small (or of zero length)
+ *
+ * @stable ICU 4.2
+ */
 U_STABLE int32_t U_EXPORT2
 uspoof_getSkeletonUTF8(const USpoofChecker *sc,
                        uint32_t type,
                        const char *id,  int32_t length,
                        char *dest, int32_t destCapacity,
                        UErrorCode *status);
-    
+
 #if U_SHOW_CPLUSPLUS_API
 /**
-  *  Get the "skeleton" for an identifier.
-  *  Skeletons are a transformation of the input identifier;
-  *  Two identifiers are confusable if their skeletons are identical.
-  *  See Unicode UAX #39 for additional information.
-  *
-  *  Using skeletons directly makes it possible to quickly check
-  *  whether an identifier is confusable with any of some large
-  *  set of existing identifiers, by creating an efficiently
-  *  searchable collection of the skeletons.
-  *
-  * @param sc      The USpoofChecker.
-  * @param type    The type of skeleton, corresponding to which
-  *                of the Unicode confusable data tables to use.
-  *                The default is Mixed-Script, Lowercase.
-  *                Allowed options are USPOOF_SINGLE_SCRIPT_CONFUSABLE and
-  *                USPOOF_ANY_CASE.  The two flags may be ORed.
-  * @param id      The input identifier whose skeleton will be computed.
-  * @param dest    The output identifier, to receive the skeleton string.
-  * @param status  The error code, set if an error occurred while attempting to
-  *                perform the check.
-  * @return        A reference to the destination (skeleton) string.
-  *                
-  * @stable ICU 4.2
-  */   
+ *  Get the "skeleton" for an identifier.
+ *  Skeletons are a transformation of the input identifier;
+ *  Two identifiers are confusable if their skeletons are identical.
+ *  See Unicode UAX #39 for additional information.
+ *
+ *  Using skeletons directly makes it possible to quickly check
+ *  whether an identifier is confusable with any of some large
+ *  set of existing identifiers, by creating an efficiently
+ *  searchable collection of the skeletons.
+ *
+ * @param sc      The USpoofChecker.
+ * @param type    Deprecated in ICU 58.  You may pass any number.
+ *                Originally, controlled which of the Unicode confusable data
+ *                tables to use.
+ * @param id      The input identifier whose skeleton will be computed.
+ * @param dest    The output identifier, to receive the skeleton string.
+ * @param status  The error code, set if an error occurred while attempting to
+ *                perform the check.
+ * @return        A reference to the destination (skeleton) string.
+ *
+ * @stable ICU 4.2
+ */
 U_I18N_API icu::UnicodeString & U_EXPORT2
 uspoof_getSkeletonUnicodeString(const USpoofChecker *sc,
                                 uint32_t type,
@@ -977,7 +1486,8 @@ uspoof_getSkeletonUnicodeString(const USpoofChecker *sc,
 
 /**
   * Get the set of Candidate Characters for Inclusion in Identifiers, as defined
-  * in Unicode UAX #31, http://www.unicode.org/reports/tr31/#Table_Candidate_Characters_for_Inclusion_in_Identifiers
+  * in http://unicode.org/Public/security/latest/xidmodifications.txt
+  * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms.
   *
   * The returned set is frozen. Ownership of the set remains with the ICU library; it must not
   * be deleted by the caller.
@@ -991,7 +1501,8 @@ uspoof_getInclusionSet(UErrorCode *status);
 
 /**
   * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined
-  * in Unicode UAX #31, http://www.unicode.org/reports/tr31/#Table_Recommended_Scripts
+  * in http://unicode.org/Public/security/latest/xidmodifications.txt
+  * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms.
   *
   * The returned set is frozen. Ownership of the set remains with the ICU library; it must not
   * be deleted by the caller.
@@ -1007,7 +1518,8 @@ uspoof_getRecommendedSet(UErrorCode *status);
 
 /**
   * Get the set of Candidate Characters for Inclusion in Identifiers, as defined
-  * in Unicode UAX #31, http://www.unicode.org/reports/tr31/#Table_Candidate_Characters_for_Inclusion_in_Identifiers
+  * in http://unicode.org/Public/security/latest/xidmodifications.txt
+  * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms.
   *
   * The returned set is frozen. Ownership of the set remains with the ICU library; it must not
   * be deleted by the caller.
@@ -1021,7 +1533,8 @@ uspoof_getInclusionUnicodeSet(UErrorCode *status);
 
 /**
   * Get the set of characters from Recommended Scripts for Inclusion in Identifiers, as defined
-  * in Unicode UAX #31, http://www.unicode.org/reports/tr31/#Table_Recommended_Scripts
+  * in http://unicode.org/Public/security/latest/xidmodifications.txt
+  * and documented in http://www.unicode.org/reports/tr39/, Unicode Security Mechanisms.
   *
   * The returned set is frozen. Ownership of the set remains with the ICU library; it must not
   * be deleted by the caller.
@@ -1041,7 +1554,7 @@ uspoof_getRecommendedUnicodeSet(UErrorCode *status);
  * instantiate a new Spoof Detector.
  *
  * The serialized spoof checker includes only the data compiled from the
- * Unicode data tables by uspoof_openFromSource(); it does not include 
+ * Unicode data tables by uspoof_openFromSource(); it does not include
  * include any other state or configuration that may have been set.
  *
  * @param sc   the Spoof Detector whose data is to be serialized.