vendor/github.com/johngb/langreg/README.md

   1 [![GoDoc](https://godoc.org/github.com/johngb/langreg?status.svg)](https://godoc.org/github.com/johngb/langreg)
   2 [![wercker status](https://app.wercker.com/status/6774907cc34f2b397f3b29e39948f799/s/master "wercker status")](https://app.wercker.com/project/bykey/6774907cc34f2b397f3b29e39948f799)
   3
   4 langreg
   5 =====
   6
   7 langreg is a lightweight Go package to handle ISO language and region (sometimes called country) codes. This only uses ISO 639-1 language codes, and ISO 3166-1 alpha-2 region codes.  These are commonly used for language and region settings.  E.g. `en_US`, `en_GB`, `zu_ZA`.
   8
   9 ## Installation
  10
  11 ```
  12 go get github.com/johngb/langreg
  13 ```
  14
  15 ## Usage
  16
  17 Language codes must be lowercase, while region codes must be uppercase (blame ISO for that).
  18
  19 With a language code, it is possible to:
  20 - validate the code
  21 - look up its English name
  22 - look up its native name(s) in its native script(s)
  23
  24 With a region code, it is possible to:
  25 - validate the code
  26 - look up the English region name
  27
  28 ### Examples
  29
  30 The library is quite simple, but here are a few example use cases:
  31
  32 **Validate a composite (e.g. "en_US") code**
  33 ```go
  34 code := "en_US"
  35 if langreg.IsValidLangRegCode(code) {
  36         ...
  37         // do something
  38 }
  39 ```
  40
  41 **Get a language in its native script**
  42 ```go
  43 lang := "zh"
  44 name := langreg.LangNativeName(lang)
  45 fmt.Println(name)
  46 ```
  47
  48 ```Result: 中文(Zhōngwén); 汉语; 漢語```
  49
  50 **Get a language in English**
  51 ```go
  52 lang := "xh"
  53 name := langreg.LangEnglishName(lang)
  54 fmt.Println(name)
  55 ```
  56
  57 ```Result: Xhosa```
  58
  59 **Get a region name**
  60 ```go
  61 regCode := "DZ"
  62 region := langreg.RegionName(regCode)
  63 fmt.Println(region)
  64 ```
  65
  66 ```Result: Algeria```
  67
  68
  69 ## Data Source
  70
  71 All data sources that have been used are in the public domain.
  72
  73 The data used for the language codes and English names, come from the [official source](http://loc.gov/standards/iso639-2/ISO-639-2_utf-8.txt) at the Library of Congress.  As the official specification doesn't include native names (What were they thinking?!), I've scraped the native names from Wikipedia's [list of ISO 639-1 codes](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
  74
  75 As this is intended for general use cases, rather than distinguishing between ancient and modern languages, some of the names from the official source have been simplified where I felt they would be clear.  For example "Greek, Modern (1453-)" - the official ISO name - is less clear than "Greek", and so I used "Greek".  There are a few other minor cases like this, but nothing significant.
  76
  77 The data used for the region codes and data has been scraped from Wikipedia's [ISO 3166-1 page](http://en.wikipedia.org/wiki/ISO_3166-1). I couldn't find any single download from ISO without paying for it or scraping a page per letter of the alphabet, so I stuck with Wikipedia - because lazy.
  78
  79 ## Design and Benchmarks
  80
  81 This was designed primarily as a lightweight lookup table that would be called infrequently.  I tested various options for this, and narrowed it down to either a map or a switch statement.  The switch statement for a single lookup table was a little slower at 67-78 ns/op vs the maps' 38-50 ns/op, but had no data to load into memory first, while the startup time for loading the map into memory was 48 µs (48k ns).
  82
  83 Update: with some suggestions from @attilaolah to use nested switch statements, the switch version's performance is now significantly faster than even a pre-loaded map.
  84
  85 The worst case benchmarks results on a MacBook Pro are:
  86 ```
  87 BenchmarkIsValidLangRegCode             100000000               23.2 ns/op
  88
  89 BenchmarkLangCodeInfo                   100000000               10.7 ns/op
  90 BenchmarkIsValidLanguageCode    100000000               11.2 ns/op
  91 BenchmarkLangEnglishName                100000000               12.5 ns/op
  92 BenchmarkLangNativeName                 100000000               12.1 ns/op
  93
  94 BenchmarkRegionCodeInfo                 200000000               9.73 ns/op
  95 BenchmarkIsValidRegionCode              100000000               10.4 ns/op
  96 BenchmarkRegionName                             100000000               12.0 ns/op
  97 ```
  98
  99 ## Stability
 100
 101 This code is currently being used in a live environment, but should still be considered Alpha, as the code may still change.
 102
 103 ## Testing
 104
 105 The code has full test coverage of all logic functions, but due to the use of a long switch statement for the lookup table, it's not practial to test the full switch statement.
 106
 107 ## Support
 108
 109 If you find any errors, or simply have constructive feedback, please post an issue directly, and I'll get to it as soon as I can.
 110
 111 ## License
 112
 113 The MIT License (MIT)
 114
 115 Copyright (c) 2014 John Beckett
 116
 117 Permission is hereby granted, free of charge, to any person obtaining a copy
 118 of this software and associated documentation files (the "Software"), to deal
 119 in the Software without restriction, including without limitation the rights
 120 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 121 copies of the Software, and to permit persons to whom the Software is
 122 furnished to do so, subject to the following conditions:
 123
 124 The above copyright notice and this permission notice shall be included in all
 125 copies or substantial portions of the Software.
 126
 127 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 128 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 129 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 130 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 131 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 132 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 133 SOFTWARE.