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

   1 =pod
   2
   3 =head1 NAME
   4
   5 Locale::Codes::Country - standard codes for country identification
   6
   7 =head1 SYNOPSIS
   8
   9    use Locale::Codes::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::Codes::Country::alias_code('uk' => 'gb');
  19    Locale::Codes::Country::rename_country('gb' => 'Great Britain');
  20
  21 =head1 DESCRIPTION
  22
  23 This 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. A code set may be specified using either a name, or a
  35 constant that is automatically exported by this module.
  36
  37 For example, the two are equivalent:
  38
  39    $country = code2country('jp','alpha-2');
  40    $country = code2country('jp',LOCALE_CODE_ALPHA_2);
  41
  42 The codesets currently supported are:
  43
  44 =over 4
  45
  46 =item B<alpha-2, LOCALE_CODE_ALPHA_2>
  47
  48 This is the set of two-letter (lowercase) codes from ISO 3166-1, such
  49 as 'tv' for Tuvalu.
  50
  51 This is the default code set.
  52
  53 =item B<alpha-3, LOCALE_CODE_ALPHA_3>
  54
  55 This is the set of three-letter (lowercase) codes from ISO 3166-1,
  56 such as 'brb' for Barbados. These codes are actually defined and
  57 maintained by the U.N. Statistics division.
  58
  59 =item B<numeric, LOCALE_CODE_NUMERIC>
  60
  61 This is the set of three-digit numeric codes from ISO 3166-1, such as
  62 064 for Bhutan. These codes are actually defined and maintained by the
  63 U.N. Statistics division.
  64
  65 If a 2-digit code is entered, it is converted to 3 digits by prepending
  66 a 0.
  67
  68 =item B<dom, LOCALE_CODE_DOM>
  69
  70 The IANA is responsible for delegating management of the top level country
  71 domains.  The country domains are the two-letter (lowercase) codes from ISO 3166
  72 with a few other additions.
  73
  74 =back
  75
  76 NOTE: As of version 3.27, the FIPS code set is no longer supported.  See the
  77 Locale::Codes::Changes document for details.
  78
  79 =head1 ROUTINES
  80
  81 =over 4
  82
  83 =item B<code2country(CODE [,CODESET] [,'retired'])>
  84
  85 =item B<country2code(NAME [,CODESET] [,'retired'])>
  86
  87 =item B<country_code2code(CODE ,CODESET ,CODESET2)>
  88
  89 =item B<all_country_codes([CODESET] [,'retired'])>
  90
  91 =item B<all_country_names([CODESET] [,'retired'])>
  92
  93 =item B<Locale::Codes::Country::rename_country(CODE ,NEW_NAME [,CODESET])>
  94
  95 =item B<Locale::Codes::Country::add_country(CODE ,NAME [,CODESET])>
  96
  97 =item B<Locale::Codes::Country::delete_country(CODE [,CODESET])>
  98
  99 =item B<Locale::Codes::Country::add_country_alias(NAME ,NEW_NAME)>
 100
 101 =item B<Locale::Codes::Country::delete_country_alias(NAME)>
 102
 103 =item B<Locale::Codes::Country::rename_country_code(CODE ,NEW_CODE [,CODESET])>
 104
 105 =item B<Locale::Codes::Country::add_country_code_alias(CODE ,NEW_CODE [,CODESET])>
 106
 107 =item B<Locale::Codes::Country::delete_country_code_alias(CODE [,CODESET])>
 108
 109 These routines are all documented in the L<Locale::Codes::API> man page.
 110
 111 =item B<alias_code ( ALIAS, CODE [,CODESET] )>
 112
 113 Version 2.07 included 2 functions for modifying the internal data:
 114 rename_country and alias_code. Both of these could be used only to
 115 modify the internal data for country codes.
 116
 117 As of 3.10, the internal data for all types of codes can be modified.
 118
 119 The alias_code function is preserved for backwards compatibility, but
 120 the following two are identical:
 121
 122    alias_code(ALIAS,CODE [,CODESET]);
 123    rename_country_code(CODE,ALIAS [,CODESET]);
 124
 125 and the latter should be used for consistency.
 126
 127 The alias_code function is deprecated and will be removed in the December
 128 2014 release.
 129
 130 B<Note:> this function was previously called _alias_code, but the
 131 leading underscore has been dropped. The old name was supported for
 132 all 2.X releases, but has been dropped as of 3.00.
 133
 134 =back
 135
 136 =head1 SEE ALSO
 137
 138 =over 4
 139
 140 =item L<Locale::Codes>
 141
 142 The Locale-Codes distribution.
 143
 144 =item L<Locale::Codes::API>
 145
 146 The list of functions supported by this module.
 147
 148 =item L<Locale::SubCountry>
 149
 150 ISO codes for country sub-divisions (states, counties, provinces,
 151 etc), as defined in ISO 3166-2.  This module is not part of the
 152 Locale-Codes distribution, but is available from CPAN in
 153 CPAN/modules/by-module/Locale/
 154
 155 =item L<http://www.iso.org/iso/home/standards/country_codes.htm>
 156
 157 Official home page for the ISO 3166 maintenance agency.
 158
 159 =item L<http://www.iso.org/iso/home/standards/country_codes/iso-3166-1_decoding_table.htm>
 160
 161 The source of ISO 3166-1 two-letter codes used by this
 162 module.
 163
 164 =item L<http://www.iana.org/domains/root/db/>
 165
 166 Official source of the top-level domain names.
 167
 168 =item L<http://unstats.un.org/unsd/methods/m49/m49alpha.htm>
 169
 170 The source of the official ISO 3166-1 three-letter codes and
 171 three-digit codes.
 172
 173 For some reason, this table is incomplete! Several countries are
 174 missing from it, and I cannot find them anywhere on the UN site.  I
 175 no longer use this as a source of data.
 176
 177 =item L<https://www.cia.gov/library/publications/the-world-factbook/appendix/print_appendix-d.html>
 178
 179 The World Factbook maintained by the CIA is a potential source of
 180 the data.  Unfortunately, it adds/preserves non-standard codes, so it is no
 181 longer used as a source of data.
 182
 183 =item L<http://www.statoids.com/wab.html>
 184
 185 Another unofficial source of data. Currently, it is not used to get
 186 data, but the notes and explanatory material were very useful for
 187 understanding discrepancies between the sources.
 188
 189 =back
 190
 191 =head1 AUTHOR
 192
 193 See Locale::Codes for full author history.
 194
 195 Currently maintained by Sullivan Beck (sbeck@cpan.org).
 196
 197 =head1 COPYRIGHT
 198
 199    Copyright (c) 1997-2001 Canon Research Centre Europe (CRE).
 200    Copyright (c) 2001-2010 Neil Bowers
 201    Copyright (c) 2010-2015 Sullivan Beck
 202
 203 This module is free software; you can redistribute it and/or
 204 modify it under the same terms as Perl itself.
 205
 206 =cut