cpan/Locale-Codes/lib/Locale/Country.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Locale::Country - standard codes for country identification
   6
   7 =head1 SYNOPSIS
   8
   9    use Locale::Country;
  10
  11    $country = code2country('jp' [,CODESET]);        # $country gets 'Japan'
  12    $code    = country2code('Norway' [,CODESET]);    # $code gets 'no'
  13
  14    @codes   = all_country_codes( [CODESET]);
  15    @names   = all_country_names();
  16
  17    # semi-private routines
  18    Locale::Country::alias_code('uk' => 'gb');
  19    Locale::Country::rename_country('gb' => 'Great Britain');
  20
  21 =head1 DESCRIPTION
  22
  23 The C<Locale::Country> module provides access to several code sets
  24 that can be used for identifying countries, such as those defined in
  25 ISO 3166-1.
  26
  27 Most of the routines take an optional additional argument which
  28 specifies the code set to use. If not specified, the default ISO
  29 3166-1 two-letter codes will be used.
  30
  31 =head1 SUPPORTED CODE SETS
  32
  33 There are several different code sets you can use for identifying
  34 countries. The ones currently supported are:
  35
  36 =over 4
  37
  38 =item B<alpha-2>
  39
  40 This is the set of two-letter (lowercase) codes from ISO 3166-1, such
  41 as 'tv' for Tuvalu.
  42
  43 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_2>.
  44
  45 This is the default code set.
  46
  47 =item B<alpha-3>
  48
  49 This is the set of three-letter (lowercase) codes from ISO 3166-1,
  50 such as 'brb' for Barbados. These codes are actually defined and
  51 maintained by the U.N. Statistics division.
  52
  53 This code set is identified with the symbol C<LOCALE_CODE_ALPHA_3>.
  54
  55 =item B<numeric>
  56
  57 This is the set of three-digit numeric codes from ISO 3166-1, such as
  58 064 for Bhutan. These codes are actually defined and maintained by the
  59 U.N. Statistics division.
  60
  61 If a 2-digit code is entered, it is converted to 3 digits by prepending
  62 a 0.
  63
  64 This code set is identified with the symbol C<LOCALE_CODE_NUMERIC>.
  65
  66 =item B<fips-10>
  67
  68 The FIPS 10 data are two-letter (uppercase) codes assigned by the
  69 National Geospatial-Intelligence Agency.
  70
  71 This code set is identified with the symbol C<LOCALE_CODE_FIPS>.
  72
  73 =item B<dom>
  74
  75 The IANA is responsible for assigning two-letter (uppercase) top-level
  76 domain names to each country.
  77
  78 This code set is identified with the symbol C<LOCALE_CODE_DOM>.
  79
  80 =back
  81
  82 =head1 ROUTINES
  83
  84 =over 4
  85
  86 =item B<code2country ( CODE [,CODESET] )>
  87
  88 =item B<country2code ( NAME [,CODESET] )>
  89
  90 =item B<country_code2code ( CODE ,CODESET ,CODESET2 )>
  91
  92 =item B<all_country_codes ( [CODESET] )>
  93
  94 =item B<all_country_names ( [CODESET] )>
  95
  96 =item B<Locale::Country::rename_country  ( CODE ,NEW_NAME [,CODESET] )>
  97
  98 =item B<Locale::Country::add_country  ( CODE ,NAME [,CODESET] )>
  99
 100 =item B<Locale::Country::delete_country  ( CODE [,CODESET] )>
 101
 102 =item B<Locale::Country::add_country_alias  ( NAME ,NEW_NAME )>
 103
 104 =item B<Locale::Country::delete_country_alias  ( NAME )>
 105
 106 =item B<Locale::Country::rename_country_code  ( CODE ,NEW_CODE [,CODESET] )>
 107
 108 =item B<Locale::Country::add_country_code_alias  ( CODE ,NEW_CODE [,CODESET] )>
 109
 110 =item B<Locale::Country::delete_country_code_alias  ( CODE [,CODESET] )>
 111
 112 These routines are all documented in the Locale::Codes man page.
 113
 114 =item B<alias_code ( ALIAS, CODE [,CODESET] )>
 115
 116 Version 2.07 included 2 functions for modifying the internal data:
 117 rename_country and alias_code. Both of these could be used only to
 118 modify the internal data for country codes.
 119
 120 As of 3.10, the internal data for all types of codes can be modified.
 121
 122 The alias_code function is preserved for backwards compatibility, but
 123 the following two are identical:
 124
 125    alias_code(ALIAS,CODE [,CODESET]);
 126    rename_country_code(CODE,ALIAS [,CODESET]);
 127
 128 and the latter should be used for consistency.
 129
 130 The alias_code function is deprecated (though there is no currently no
 131 plan to remove it).
 132
 133 B<Note:> this function was previously called _alias_code, but the
 134 leading underscore has been dropped. The old name was supported for
 135 all 2.X releases, but has been dropped as of 3.00.
 136
 137 =back
 138
 139 =head1 SEE ALSO
 140
 141 =over 4
 142
 143 =item B<Locale::Codes>
 144
 145 =item B<Locale::Constants>
 146
 147 =item B<Locale::SubCountry>
 148
 149 ISO codes for country sub-divisions (states, counties, provinces,
 150 etc), as defined in ISO 3166-2.  This module is not part of the
 151 Locale-Codes distribution, but is available from CPAN in
 152 CPAN/modules/by-module/Locale/
 153
 154 =item B<http://www.iso.org/iso/country_codes>
 155
 156 Official home page for the ISO 3166 maintenance agency.
 157
 158 Unfortunately, they do not make the actual ISO available for free,
 159 so I cannot check the alpha-3 and numerical codes here.
 160
 161 =item B<http://www.iso.org/iso/list-en1-semic-3.txt>
 162
 163 The source of ISO 3166-1 two-letter codes used by this
 164 module.
 165
 166 =item B<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>
 167
 168 The source of the official ISO 3166-1 three-letter codes and
 169 three-digit codes.
 170
 171 For some reason, this table is incomplete! Several countries are
 172 missing from it, and I cannot find them anywhere on the UN site.  I
 173 get as much of the data from here as I can.
 174
 175 =item B<http://earth-info.nga.mil/gns/html/digraphs.htm>
 176
 177 The official list of the FIPS 10 codes.
 178
 179 =item B<http://www.iana.org/domains/>
 180
 181 Official source of the top-level domain names.
 182
 183 =item B<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html>
 184
 185 Although not the official source of any of the data, the World
 186 Factbook maintained by the CIA is a great source of the data,
 187 especially since I can't get the official data from the ISO. Since
 188 it's maintained by the CIA, and since it's updated every two weeks, I
 189 use this as the source for some missing data.
 190
 191 =item B<http://www.statoids.com/wab.html>
 192
 193 Another unofficial source of data. Currently, it is not used to get
 194 data, but the notes and explanatory material were very useful for
 195 understanding discrepancies between the sources.
 196
 197 =back
 198
 199 =head1 AUTHOR
 200
 201 See Locale::Codes for full author history.
 202
 203 Currently maintained by Sullivan Beck (sbeck@cpan.org).
 204
 205 =head1 COPYRIGHT
 206
 207    Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 208    Copyright (c) 2001-2010 Neil Bowers
 209    Copyright (c) 2010-2010 Sullivan Beck
 210
 211 This module is free software; you can redistribute it and/or
 212 modify it under the same terms as Perl itself.
 213
 214 =cut