icuSources/common/unicode/ualoc.h

   1 /*
   2 *****************************************************************************************
   3 * Copyright (C) 2014 Apple Inc. All Rights Reserved.
   4 *****************************************************************************************
   5 */
   6
   7 #ifndef UALOC_H
   8 #define UALOC_H
   9
  10 #include "unicode/utypes.h"
  11
  12 #ifndef U_HIDE_DRAFT_API
  13
  14 /**
  15  * Codes for language status in a country or region.
  16  * @draft ICU 54
  17  */
  18 typedef enum {
  19     /**
  20      * The status is unknown, or the language has no special status.
  21      * @draft ICU 54 */
  22     UALANGSTATUS_UNSPECIFIED       = 0,
  23     /**
  24      * The language is official in a region of the specified country,
  25      * e.g. Hawaiian for U.S.
  26      * @draft ICU 54 */
  27     UALANGSTATUS_REGIONAL_OFFICIAL = 4,
  28     /**
  29      * The language is de-facto official for the specified country or region,
  30      * e.g. English for U.S.
  31      * @draft ICU 54 */
  32     UALANGSTATUS_DEFACTO_OFFICIAL  = 8,
  33     /**
  34      * The language is explicitly official for the specified country or region.
  35      * @draft ICU 54 */
  36     UALANGSTATUS_OFFICIAL          = 12
  37 } UALanguageStatus;
  38
  39 /**
  40  * UALANGDATA_CODELEN is the maximum length of a language code
  41  * (language subtag, possible extension, possible script subtag)
  42  * in the UALanguageEntry struct.
  43  * @draft ICU 54
  44  */
  45 #define UALANGDATA_CODELEN 23
  46
  47 /**
  48  * The UALanguageEntry structure provides information about
  49  * one of the languages for a specified region.
  50  * @draft ICU 54
  51  */
  52 typedef struct {
  53     char languageCode[UALANGDATA_CODELEN + 1];  /**< language code, may include script or
  54                                                    other subtags after primary language.
  55                                                    This may be "und" (undetermined) for
  56                                                    some regions such as AQ Antarctica.
  57                                                    @draft ICU 54 */
  58     double userFraction;      /**< fraction of region's population (from 0.0 to 1.0) that
  59                                 uses this language (not necessarily as a first language).
  60                                 This may be 0.0 if the fraction is known to be very small.
  61                                 @draft ICU 54 */
  62     UALanguageStatus status;  /**< status of the language, if any.
  63                                 @draft ICU 54 */
  64 } UALanguageEntry;
  65
  66 /**
  67  * Fills out a provided UALanguageEntry entry with information about the languages
  68  * used in a specified region.
  69  *
  70  * @param regionID
  71  *          The specified regionID (currently only ISO-3166-style IDs are supported).
  72  * @param minimumFraction
  73  *          The minimum fraction of language users for a language to be included
  74  *          in the UALanguageEntry array. Must be in the range 0.0 to 1.0; set to
  75  *          0.0 if no minimum threshold is desired. As an example, as of March 2014
  76  *          ICU lists 74 languages for India; setting minimumFraction to 0.001 (0.1%)
  77  *          skips 27, keeping the top 47 languages for inclusion in the entries array
  78  *          (depending on entriesCapacity); setting minimumFraction to 0.01 (1%)
  79  *          skips 54, keeping the top 20 for inclusion.
  80  * @param entries
  81  *          Caller-provided array of UALanguageEntry elements. This will be filled
  82  *          out with information for languages of the specified region that meet
  83  *          the minimumFraction threshold, sorted in descending order by
  84  *          userFraction, up to the number of elements specified by entriesCapacity
  85  *          (so the number of languages for which data is provided can be limited by
  86  *          total count, by userFraction, or both).
  87  *          Preflight option: You may set this to NULL (and entriesCapacity to 0)
  88  *          to just obtain a count of all of the languages that meet the specified
  89  *          minimumFraction, without actually getting data for any of them.
  90  * @param entriesCapacity
  91  *          The number of elements in the provided entries array. Must be 0 if
  92  *          entries is NULL (preflight option).
  93  * @param status
  94  *          A pointer to a UErrorCode to receive any errors, for example
  95  *          U_MISSING_RESOURCE_ERROR if there is no data available for the
  96  *          specified region.
  97  * @return
  98  *          The number of elements in entries filled out with data, or if
  99  *          entries is NULL and entriesCapacity is 0 (preflight option ), the total
 100  *          number of languages for the specified region that meet the minimumFraction
 101  *          threshold.
 102  * @draft ICU 54
 103  */
 104 U_DRAFT int32_t U_EXPORT2
 105 ualoc_getLanguagesForRegion(const char *regionID, double minimumFraction,
 106                             UALanguageEntry *entries, int32_t entriesCapacity,
 107                             UErrorCode *err);
 108
 109
 110 /**
 111  * Gets the desired lproj parent locale ID for the specified locale,
 112  * using ICU inheritance chain plus Apple additions (for zh*). For
 113  * example, provided any ID in the following chains it would return
 114  * the next one to the right:
 115  *
 116  *                                 en_US → en → root;
 117  *                en_IN → en_GB → en_001 → en → root;
 118  *                                 es_ES → es → root;
 119  *                        es_MX → es_419 → es → root;
 120  *                                        haw → root;
 121  *                                 pt_BR → pt → root;
 122  *                                 pt_PT → pt → root;
 123  *                               sr_Cyrl → sr → root;
 124  *                                    sr_Latn → root;
 125  *                       zh_Hans → zh → zh_CN → root;
 126  *  zh_Hant_MO → zh_Hant_HK → zh_Hant → zh_TW → root;
 127  *                                       root → root;
 128  *                                        tlh → root;
 129  *
 130  * @param localeID  The locale whose parent to get. This can use either '-' or '_' for separator.
 131  * @param parent    Buffer into which the parent localeID will be copied.
 132  *                  This will always use '_' for separator.
 133  * @param parentCapacity  The size of the buffer for parent localeID (including room for null terminator).
 134  * @param err       Pointer to UErrorCode. If on input it indicates failure, function will return 0.
 135  *                  If on output it indicates an error the contents of parent buffer are undefined.
 136  * @return          The actual buffer length of the parent localeID. If it is greater than parentCapacity,
 137  *                  an overflow error will be set and the contents of parent buffer are undefined.
 138  * @draft ICU 53
 139  */
 140 U_DRAFT int32_t U_EXPORT2
 141 ualoc_getAppleParent(const char* localeID,
 142                      char * parent,
 143                      int32_t parentCapacity,
 144                      UErrorCode* err);
 145
 146 #endif /* U_HIDE_DRAFT_API */
 147 #endif /*UALOC_H*/