vitorsvieira / scala-iso

ISO 3166-1, ISO 3166-2, ISO 4217, E.164, ISO related types in Scala. Country codes, Country Subdivision, Country Currency, Calling Code, etc...

GitHub

scala-iso

Build Status Software License Maven Central

Motivation

  • One stop shop for ISO related types.

Installation

To get started with SBT, simply add the following to your build.sbt or Build.scala file:

libraryDependencies += "com.vitorsvieira" %% "scala-iso" % "0.1.2"

How to use

The easiest way to use the types available is just adding the following import statement:

import com.vitorsvieira.iso._

ISOCountry

ISOCountry can be retrieved using an alpha-2 code or its numerical code.

scala> ISOCountry("US")
ISOCountry = US
scala> ISOCountry(840)
ISOCountry = US
//or just using the country type
scala> val us = ISOCountry.UNITED_STATES

Using the from method to return an Option[ISOCountry] in case the alpha-2 or numerical code does not exist.

scala> ISOCountry.from("US")
Option[ISOCountry] = Some(US)
scala> ISOCountry.from(840)
Option[ISOCountry] = Some(US)

Also, a list of countries can be returned using the fromContinent method passing a ISOContinent as argument.

scala> val countries = ISOCountry.fromContinent(ISOContinent.ANTARCTICA)
countries: Seq[ISOCountry] = Vector(AQ, BV, TF, HM, GS)

Every ISOCountry is composed by 5 properties:

  • Alpha-2 code, Numerical Code, Formal English Name, Alpha-3 code, ISOContinent
ISOCountry("US", 840, "United States of America", "USA", ISOContinent.NORTH_AMERICA)

ISOCountrySubdivision

val subdivision = ISOCountrySubdivision("US-NY")
subdivision: ISOCountrySubdivision = US-NY
//or
val ny = ISOCountrySubdivision.`New York`
ny: ISOCountrySubdivision = US-NY

Using the from method to return an Option[ISOCountry] in case the alpha-2 or numerical code does not exist.

scala> val optSubdivision = ISOCountrySubdivision.from("US-NY")
optSubdivision: Option[ISOCountrySubdivision] = Some(US-NY)

Also, a list of subdivisions can be returned using the fromCountry method passing a ISOCountry as argument.

scala> val subdivisions = ISOCountrySubdivision.fromCountry(ISOCountry.AUSTRALIA)
subdivisions: Seq[ISOCountrySubdivision] = Vector(AU-ACT, AU-NSW, AU-NT, AU-QLD, AU-SA, AU-TAS, AU-VIC, AU-WA)

Every ISOCountrySubdivision is composed by 3 properties:

  • ISOCountry, Formal English Name, 3166-2 code
ISOCountrySubdivision(ISOCountry.UNITED_STATES, "New York", "US-NY")

ISOCurrency

ISOCurrency can be retrieved using the currency code, numerical code, or ISOCountry.

ISOCurrency("USD")
ISOCurrency(840)
ISOCurrency(ISOCountry.UNITED_STATES)
//or
ISOCurrency.US_DOLLAR

ISOCurrency has the same from method to retrieve a Option[ISOCurrency] as the types above using the same parameters as the method apply.

Every ISOCurrency is composed by 4 properties:

  • Currency code, Numerical Code, Minor Unit, collection of ISOCountry.
ISOCurrency(
  "AUD",
  36,
  2,
  ISOCountry.HEARD_ISLAND_AND_MCDONALD_ISLANDS,
  ISOCountry.TUVALU,
  ISOCountry.KIRIBATI,
  ISOCountry.AUSTRALIA,
  ISOCountry.NORFOLK_ISLAND,
  ISOCountry.NAURU,
  ISOCountry.CHRISTMAS_ISLAND,
  ISOCountry.COCOS_ISLANDS
)

CountryCallingCodes

CountryCallingCode(ISOCountry.UNITED_STATES)
CountryCallingCode("1")
CountryCallingCode(1)
//or just
CountryCallingCode.`+1`

Every CountryCallingCodes is composed by 3 properties:

  • Calling code, Numerical Code, collection of ISOCountry
CountryCallingCode("1", 1, ISOCountry.UNITED_STATES, ISOCountry.CANADA)

Roadmap

  • ISO 3166-1 - codes for the names of countries, dependent territories, and special areas of geographical interest.
  • ISO 3166-2 - codes for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1.
  • ISO 4217 - codes for currencies in circulation, composed of a country's two-character Internet country code plus a third character denoting the currency unit.
  • E.164 - country calling codes or country dial in codes are telephone dialing prefixes for the member countries of the International Telecommunication Union.
  • Language / Locales.
  • Banking / Financial.
  • File formats.
  • etc...
  • and other regulated standards direct or indirectly related to ISO.

References

License

This code is open source software licensed under the Apache 2.0 license.