DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (d38398e5144e)

VCS Links

URegionType

Macros

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*****************************************************************************************
* Copyright (C) 2014, International Business Machines
* Corporation and others. All Rights Reserved.
*****************************************************************************************
*/

#ifndef UREGION_H
#define UREGION_H

#include "unicode/utypes.h"
#include "unicode/uenum.h"

/**
 * \file
 * \brief C API: URegion (territory containment and mapping)
 *
 * URegion objects represent data associated with a particular Unicode Region Code, also known as a 
 * Unicode Region Subtag, which is defined based upon the BCP 47 standard. These include:
 * * Two-letter codes defined by ISO 3166-1, with special LDML treatment of certain private-use or
 *   reserved codes;
 * * A subset of 3-digit numeric codes defined by UN M.49.
 * URegion objects can also provide mappings to and from additional codes. There are different types
 * of regions that are important to distinguish:
 * <p>
 * Macroregion - A code for a "macro geographical (continental) region, geographical sub-region, or 
 * selected economic and other grouping" as defined in UN M.49. These are typically 3-digit codes,
 * but contain some 2-letter codes for LDML extensions, such as "QO" for Outlying Oceania.
 * Macroregions are represented in ICU by one of three region types: WORLD (code 001),
 * CONTINENTS (regions contained directly by WORLD), and SUBCONTINENTS (regions contained directly
 * by a continent ).
 * <p>
 * TERRITORY - A Region that is not a Macroregion. These are typically codes for countries, but also
 * include areas that are not separate countries, such as the code "AQ" for Antarctica or the code 
 * "HK" for Hong Kong (SAR China). Overseas dependencies of countries may or may not have separate 
 * codes. The codes are typically 2-letter codes aligned with ISO 3166, but BCP47 allows for the use
 * of 3-digit codes in the future.
 * <p>
 * UNKNOWN - The code ZZ is defined by Unicode LDML for use in indicating that region is unknown,
 * or that the value supplied as a region was invalid.
 * <p>
 * DEPRECATED - Region codes that have been defined in the past but are no longer in modern usage,
 * usually due to a country splitting into multiple territories or changing its name.
 * <p>
 * GROUPING - A widely understood grouping of territories that has a well defined membership such
 * that a region code has been assigned for it.  Some of these are UN M.49 codes that don't fall into 
 * the world/continent/sub-continent hierarchy, while others are just well-known groupings that have
 * their own region code. Region "EU" (European Union) is one such region code that is a grouping.
 * Groupings will never be returned by the uregion_getContainingRegion, since a different type of region
 * (WORLD, CONTINENT, or SUBCONTINENT) will always be the containing region instead.
 *
 * URegion objects are const/immutable, owned and maintained by ICU itself, so there are not functions
 * to open or close them.
 */

/**
 * URegionType is an enumeration defining the different types of regions.  Current possible
 * values are URGN_WORLD, URGN_CONTINENT, URGN_SUBCONTINENT, URGN_TERRITORY, URGN_GROUPING,
 * URGN_DEPRECATED, and URGN_UNKNOWN.
 * 
 * @stable ICU 51 
 */
typedef enum URegionType {
    /**
     * Type representing the unknown region.
     * @stable ICU 51 
     */
    URGN_UNKNOWN,

    /**
     * Type representing a territory.
     * @stable ICU 51 
     */
    URGN_TERRITORY,

    /**
     * Type representing the whole world.
     * @stable ICU 51 
     */
    URGN_WORLD,

    /**
     * Type representing a continent.
     * @stable ICU 51 
     */
    URGN_CONTINENT,

    /**
     * Type representing a sub-continent.
     * @stable ICU 51 
     */
    URGN_SUBCONTINENT,

    /**
     * Type representing a grouping of territories that is not to be used in
     * the normal WORLD/CONTINENT/SUBCONTINENT/TERRITORY containment tree.
     * @stable ICU 51 
     */
    URGN_GROUPING,

    /**
     * Type representing a region whose code has been deprecated, usually
     * due to a country splitting into multiple territories or changing its name.
     * @stable ICU 51 
     */
    URGN_DEPRECATED,

#ifndef U_HIDE_DEPRECATED_API
    /**
     * One more than the highest normal URegionType value.
     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
     */
    URGN_LIMIT
#endif  // U_HIDE_DEPRECATED_API
} URegionType;

#if !UCONFIG_NO_FORMATTING

/**
 * Opaque URegion object for use in C programs.
 * @stable ICU 52
 */
struct URegion;
typedef struct URegion URegion; /**< @stable ICU 52 */

/**
 * Returns a pointer to a URegion for the specified region code: A 2-letter or 3-letter ISO 3166
 * code, UN M.49 numeric code (superset of ISO 3166 numeric codes), or other valid Unicode Region
 * Code as defined by the LDML specification. The code will be canonicalized internally. If the
 * region code is NULL or not recognized, the appropriate error code will be set
 * (U_ILLEGAL_ARGUMENT_ERROR).
 * @stable ICU 52
 */
U_STABLE const URegion* U_EXPORT2
uregion_getRegionFromCode(const char *regionCode, UErrorCode *status);

/**
 * Returns a pointer to a URegion for the specified numeric region code. If the numeric region
 * code is not recognized, the appropriate error code will be set (U_ILLEGAL_ARGUMENT_ERROR).
 * @stable ICU 52
 */
U_STABLE const URegion* U_EXPORT2
uregion_getRegionFromNumericCode (int32_t code, UErrorCode *status);

/**
 * Returns an enumeration over the canonical codes of all known regions that match the given type.
 * The enumeration must be closed with with uenum_close().
 * @stable ICU 52
 */
U_STABLE UEnumeration* U_EXPORT2
uregion_getAvailable(URegionType type, UErrorCode *status);

/**
 * Returns true if the specified uregion is equal to the specified otherRegion.
 * @stable ICU 52
 */
U_STABLE UBool U_EXPORT2
uregion_areEqual(const URegion* uregion, const URegion* otherRegion);

/**
 * Returns a pointer to the URegion that contains the specified uregion. Returns NULL if the
 * specified uregion is code "001" (World) or "ZZ" (Unknown region). For example, calling
 * this method with region "IT" (Italy) returns the URegion for "039" (Southern Europe).
 * @stable ICU 52
 */
U_STABLE const URegion* U_EXPORT2
uregion_getContainingRegion(const URegion* uregion);

/**
 * Return a pointer to the URegion that geographically contains this uregion and matches the
 * specified type, moving multiple steps up the containment chain if necessary. Returns NULL if no
 * containing region can be found that matches the specified type. Will return NULL if URegionType
 * is URGN_GROUPING, URGN_DEPRECATED, or URGN_UNKNOWN which are not appropriate for this API.
 * For example, calling this method with uregion "IT" (Italy) for type URGN_CONTINENT returns the
 * URegion "150" (Europe).
 * @stable ICU 52
 */
U_STABLE const URegion* U_EXPORT2
uregion_getContainingRegionOfType(const URegion* uregion, URegionType type);

/**
 * Return an enumeration over the canonical codes of all the regions that are immediate children
 * of the specified uregion in the region hierarchy. These returned regions could be either macro
 * regions, territories, or a mixture of the two, depending on the containment data as defined in
 * CLDR. This API returns NULL if this uregion doesn't have any sub-regions. For example, calling
 * this function for uregion "150" (Europe) returns an enumeration containing the various
 * sub-regions of Europe: "039" (Southern Europe), "151" (Eastern Europe), "154" (Northern Europe),
 * and "155" (Western Europe). The enumeration must be closed with with uenum_close().
 * @stable ICU 52
 */
U_STABLE UEnumeration* U_EXPORT2
uregion_getContainedRegions(const URegion* uregion, UErrorCode *status);

/**
 * Returns an enumeration over the canonical codes of all the regions that are children of the
 * specified uregion anywhere in the region hierarchy and match the given type. This API may return
 * an empty enumeration if this uregion doesn't have any sub-regions that match the given type.
 * For example, calling this method with region "150" (Europe) and type URGN_TERRITORY" returns an
 * enumeration containing all the territories in Europe: "FR" (France), "IT" (Italy), "DE" (Germany),
 * etc. The enumeration must be closed with with uenum_close().
 * @stable ICU 52
 */
U_STABLE UEnumeration* U_EXPORT2
uregion_getContainedRegionsOfType(const URegion* uregion, URegionType type, UErrorCode *status);

/**
 * Returns true if the specified uregion contains the specified otherRegion anywhere in the region
 * hierarchy.
 * @stable ICU 52
 */
U_STABLE UBool U_EXPORT2
uregion_contains(const URegion* uregion, const URegion* otherRegion);

/**
 * If the specified uregion is deprecated, returns an enumeration over the canonical codes of the
 * regions that are the preferred replacement regions for the specified uregion. If the specified
 * uregion is not deprecated, returns NULL. For example, calling this method with uregion
 * "SU" (Soviet Union) returns a list of the regions containing "RU" (Russia), "AM" (Armenia),
 * "AZ" (Azerbaijan), etc... The enumeration must be closed with with uenum_close().
 * @stable ICU 52
 */
U_STABLE UEnumeration* U_EXPORT2
uregion_getPreferredValues(const URegion* uregion, UErrorCode *status);

/**
 * Returns the specified uregion's canonical code.
 * @stable ICU 52
 */
U_STABLE const char* U_EXPORT2
uregion_getRegionCode(const URegion* uregion);

/**
 * Returns the specified uregion's numeric code, or a negative value if there is no numeric code
 * for the specified uregion.
 * @stable ICU 52
 */
U_STABLE int32_t U_EXPORT2
uregion_getNumericCode(const URegion* uregion);

/**
 * Returns the URegionType of the specified uregion.
 * @stable ICU 52
 */
U_STABLE URegionType U_EXPORT2
uregion_getType(const URegion* uregion);


#endif /* #if !UCONFIG_NO_FORMATTING */

#endif