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