Merge pull request #182 from Anthony-Gaudino/issue_181_shorter_territ…

…ory_localization_code

Adds method "as_territory" and document territory methods

README.md

@@ -430,6 +430,43 @@ TwitterCldr::Shared::Languages.translate_language("chino tradicional", :es, :en)
 TwitterCldr::Shared::Languages.translate_language("Traditional Chinese", :en, :es)  # "chino tradicional"
 ```
 
+### World Territories
+
+You can use the localize convenience method on territory code symbols to get their equivalents in another language:
+
+```ruby
+:gb.localize(:pt).as_territory                         # "Reino Unido"
+:cz.localize(:pt).as_territory                         # "República Tcheca"
+```
+
+Behind the scenes, these convenience methods are creating instances of `LocalizedSymbol`.  You can do the same thing if you're feeling adventurous:
+
+```ruby
+ls = TwitterCldr::Localized::LocalizedSymbol.new(:gb, :pt)
+ls.as_territory  # "Reino Unido"
+```
+
+In addition to translating territory codes, TwitterCLDR provides access to the full set of supported methods via the `TwitterCldr::Shared::Territories` class:
+
+```ruby
+# get all territories for the default locale
+TwitterCldr::Shared::Territories.all                                                 # { ... :tl=>"East Timor", :tm=>"Turkmenistan" ... }
+
+# get all territories for a specific locale
+TwitterCldr::Shared::Territories.all_for(:pt)                                        # { ... :tl=>"República Democrática de Timor-Leste", :tm=>"Turcomenistão" ... }
+
+# get a territory by its code for the default locale
+TwitterCldr::Shared::Territories.from_territory_code(:'gb')                          # "U.K."
+
+# get a territory from its code for a specific locale
+TwitterCldr::Shared::Territories.from_territory_code_for_locale(:gb, :pt)            # "Reino Unido"
+
+# translate a territory from one locale to another
+# signature: translate_territory(territory_name, source_locale, destination_locale)
+TwitterCldr::Shared::Territories.translate_territory("Reino Unido", :pt, :en)        # "U.K."
+TwitterCldr::Shared::Territories.translate_territory("U.K.", :en, :pt)               # "Reino Unido"
+```
+
 ### Postal Codes
 
 The CLDR contains postal code validation regexes for a number of countries.

README.md.erb

@@ -397,6 +397,43 @@ TwitterCldr::Shared::Languages.translate_language("chino tradicional", :es, :en)
 TwitterCldr::Shared::Languages.translate_language("Traditional Chinese", :en, :es)  # <%= assert(TwitterCldr::Shared::Languages.translate_language("Traditional Chinese", :en, :es), "chino tradicional").inspect %>
 ```
 
+### World Territories
+
+You can use the localize convenience method on territory code symbols to get their equivalents in another language:
+
+```ruby
+:gb.localize(:pt).as_territory                         # <%= assert(:gb.localize(:pt).as_territory, "Reino Unido").inspect %>
+:cz.localize(:pt).as_territory                         # <%= assert(:cz.localize(:pt).as_territory, "República Tcheca").inspect %>
+```
+
+Behind the scenes, these convenience methods are creating instances of `LocalizedSymbol`.  You can do the same thing if you're feeling adventurous:
+
+```ruby
+ls = TwitterCldr::Localized::LocalizedSymbol.new(:gb, :pt)
+ls.as_territory  # <%= assert(TwitterCldr::Localized::LocalizedSymbol.new(:gb, :pt).as_territory, "Reino Unido").inspect %>
+```
+
+In addition to translating territory codes, TwitterCLDR provides access to the full set of supported methods via the `TwitterCldr::Shared::Territories` class:
+
+```ruby
+# get all territories for the default locale
+TwitterCldr::Shared::Territories.all                                                 # <%= ellipsize(assert(slice_hash(TwitterCldr::Shared::Territories.all, [:tl, :tm]), { :tl=>"East Timor", :tm=>"Turkmenistan" })) %>
+
+# get all territories for a specific locale
+TwitterCldr::Shared::Territories.all_for(:pt)                                        # <%= ellipsize(assert(slice_hash(TwitterCldr::Shared::Territories.all_for(:pt), [:tl, :tm]), { :tl=>"República Democrática de Timor-Leste", :tm=>"Turcomenistão" })) %>
+
+# get a territory by its code for the default locale
+TwitterCldr::Shared::Territories.from_territory_code(:'gb')                          # <%= assert(TwitterCldr::Shared::Territories.from_territory_code(:'gb'), "U.K.").inspect %>
+
+# get a territory from its code for a specific locale
+TwitterCldr::Shared::Territories.from_territory_code_for_locale(:gb, :pt)            # <%= assert(TwitterCldr::Shared::Territories.from_territory_code_for_locale(:gb, :pt), "Reino Unido").inspect %>
+
+# translate a territory from one locale to another
+# signature: translate_territory(territory_name, source_locale, destination_locale)
+TwitterCldr::Shared::Territories.translate_territory("Reino Unido", :pt, :en)        # <%= assert(TwitterCldr::Shared::Territories.translate_territory("Reino Unido", :pt, :en), "U.K.").inspect %>
+TwitterCldr::Shared::Territories.translate_territory("U.K.", :en, :pt)               # <%= assert(TwitterCldr::Shared::Territories.translate_territory("U.K.", :en, :pt), "Reino Unido").inspect %>
+```
+
 ### Postal Codes
 
 The CLDR contains postal code validation regexes for a number of countries.

lib/twitter_cldr/localized/localized_symbol.rb

@@ -15,6 +15,10 @@ def as_locale
         TwitterCldr::Shared::Locale.parse(@base_obj.to_s)
       end
 
+      def as_territory
+        TwitterCldr::Shared::Territories::from_territory_code_for_locale(@base_obj, @locale)
+      end
+
       def is_rtl?
         TwitterCldr::Shared::Languages.is_rtl?(@base_obj)
       end

spec/localized/localized_symbol_spec.rb

@@ -28,6 +28,25 @@
     end
   end
 
+  describe "#as_territory" do
+    it "calculates the correct localized territory from the symbol" do
+      expect(:gb.localize.as_territory).to eq("U.K.")
+      TwitterCldr.locale = :pt
+      expect(:gb.localize.as_territory).to eq("Reino Unido")
+    end
+
+    it "returns nil if the symbol doesn't correspond to a territory code" do
+      expect(:blarg.localize.as_territory).to eq(nil)
+    end
+
+    it "calculates the correct value for mapped as well as CLDR language codes" do
+      expect(:gb.localize(:'en-au').as_territory).to eq("U.K.")
+      expect(:gb.localize(:'en-ca').as_territory).to eq("U.K.")
+      expect(:gb.localize(:'en-gb').as_territory).to eq("UK")
+      expect(:gb.localize(:'en').as_territory).to eq("U.K.")
+    end
+  end
+
   describe "#is_rtl?" do
     it "returns true or false depending on the locale" do
       expect(:es.localize.is_rtl?).to be_false