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 */
18typedef 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 */
52typedef 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 */
104U_DRAFT int32_t U_EXPORT2
105ualoc_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 */
140U_DRAFT int32_t U_EXPORT2
141ualoc_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*/
148