-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
188 lines (131 loc) · 7.19 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<link href='https://fonts.googleapis.com/css?family=Architects+Daughter' rel='stylesheet' type='text/css'>
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<title>Globalphone by GlobalPhone</title>
</head>
<body>
<header>
<div class="inner">
<h1>Globalphone</h1>
<h2>GlobalPhone parses, validates, and formats local and international phone numbers</h2>
<a href="https://github.com/GlobalPhone" class="button"><small>Follow me on</small> GitHub</a>
</div>
</header>
<div id="content-wrapper">
<div class="inner clearfix">
<section id="main-content">
<p>GlobalPhone parses, validates, and formats local and international phone numbers according to the <a href="http://en.wikipedia.org/wiki/E.164">E.164 standard</a>.</p>
<p><strong>Store and display phone numbers in your app.</strong> Accept phone number input in national or international format. Convert phone numbers to international strings (<code>+13125551212</code>) for storage and retrieval. Present numbers in national format (<code>(312) 555-1212</code>) in your UI.</p>
<p><strong>Designed with the future in mind.</strong> GlobalPhone uses format specifications from Google's open-source <a href="http://code.google.com/p/libphonenumber/">libphonenumber</a> database. No need to upgrade the library when a new phone format is introduced—just generate a new copy of the database and check it into your app.</p>
<h2>
<a id="installation" class="anchor" href="#installation" aria-hidden="true"><span class="octicon octicon-link"></span></a>Installation</h2>
<ol>
<li>
<p>Add the <code>GlobalPhone</code> nuget package to your app. For example, using Package Manager Console:</p>
<pre><code>PM> Install-Package GlobalPhone
</code></pre>
</li>
<li>
<p>Use <code>GlobalPhoneDbgen</code> to convert Google's libphonenumber <code>PhoneNumberMetaData.xml</code> file into a JSON database for GlobalPhone. You can either install it using nuget in some project:</p>
<pre><code>PM> Install-Package GlobalPhoneDbgen
</code></pre>
</li>
</ol>
<p>Or you can add it as a solution level package.</p>
<p>However you have installed it, you can then use the command prompt to execute the exe: </p>
<pre><code> CMD> .\packages\GlobalPhoneDbgen\tools\GlobalPhoneDbgen.exe > db/global_phone.json
</code></pre>
<ol>
<li>
<p>Tell GlobalPhone where to find the database:</p>
<pre><code>GlobalPhone.DbPath = "db/global_phone.json";
</code></pre>
</li>
</ol>
<h2>
<a id="examples" class="anchor" href="#examples" aria-hidden="true"><span class="octicon octicon-link"></span></a>Examples</h2>
<p>Parse an international number string into a <code>GlobalPhone::Number</code> object:</p>
<pre><code>var number = GlobalPhone.Parse("+1-312-555-1212");
# => #<GlobalPhone::Number Territory=#<GlobalPhone::Territory CountryCode=1 Name=US> NationalString="3125551212">
</code></pre>
<p>Query the country code and likely territory name of the number:</p>
<pre><code>number.CountryCode
# => "1"
number.Territory.Name
# => "US"
</code></pre>
<p>Present the number in national and international formats:</p>
<pre><code>number.NationalFormat
# => "(312) 555-1212"
number.InternationalFormat
# => "+1 312-555-1212"
</code></pre>
<p>Is the number valid? (Note: this is not definitive. For example, the number here is "IsValid" by format, but there are no US numbers that start with 555. The <code>IsValid</code> method may return false positives, but <em>should not</em> return false negatives unless the database is out of date.)</p>
<pre><code>number.IsValid
# => true
</code></pre>
<p>Get the number's normalized E.164 international string:</p>
<pre><code>number.InternationalString
# => "+13125551212"
</code></pre>
<p>Parse a number in national format for a given territory:</p>
<pre><code>number = GlobalPhone.Parse("(0) 20-7031-3000", "gb");
# => #<GlobalPhone::Number Territory=#<GlobalPhone::Territory CountryCode=44 Name=GB> NationalString="2070313000">
</code></pre>
<p>Parse an international number using a territory's international dialing prefix:</p>
<pre><code>number = GlobalPhone.Parse("00 1 3125551212", "gb");
# => #<GlobalPhone::Number Territory=#<GlobalPhone::Territory CountryCode=1 Name=US> NationalString="3125551212">
</code></pre>
<p>Set the default territory to Great Britain (territory names are <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 Alpha-2</a> codes):</p>
<pre><code>GlobalPhone.DefaultTerritoryName = "gb";
# => "gb"
GlobalPhone.Parse("(0) 20-7031-3000");
# => #<GlobalPhone::Number Territory=#<GlobalPhone::Territory CountryCode=44 Name=GB> NationalString="2070313000">
</code></pre>
<p>Shortcuts for validating a phone number:</p>
<pre><code>GlobalPhone.Validate("+1 312-555-1212");
# => true
GlobalPhone.Validate("+442070313000");
# => true
GlobalPhone.Validate("(0) 20-7031-3000");
# => false
GlobalPhone.Validate("(0) 20-7031-3000", "gb");
# => true
</code></pre>
<p>Shortcuts for normalizing a phone number in E.164 format:</p>
<pre><code>GlobalPhone.Normalize("(312) 555-1212");
# => "+13125551212"
GlobalPhone.Normalize("+442070313000");
# => "+442070313000"
GlobalPhone.Normalize("(0) 20-7031-3000");
# => #<GlobalPhone::FailedToParseNumberException>
GlobalPhone.Normalize("(0) 20-7031-3000", "gb");
# => "+442070313000"
</code></pre>
<h2>
<a id="caveats" class="anchor" href="#caveats" aria-hidden="true"><span class="octicon octicon-link"></span></a>Caveats</h2>
<p>GlobalPhone currently does not parse emergency numbers or SMS short code numbers.</p>
<p>Validation is not definitive and may return false positives, but <em>should not</em> return false negatives unless the database is out of date.</p>
<p>Territory heuristics are imprecise. Parsing a number will usually result in the territory being set to the primary territory of the region. For example, Canadian numbers will be parsed with a territory of <code>US</code>. (In most cases this does not matter, but if your application needs to perform geolocation using phone numbers, GlobalPhone may not be a good fit.)</p>
<h3>
<a id="license" class="anchor" href="#license" aria-hidden="true"><span class="octicon octicon-link"></span></a>License</h3>
<p>Copyright © 2013 Sam Stephenson, Oskar Gewalli</p>
<p>Released under the MIT license. See <a href="LICENSE"><code>LICENSE</code></a> for details.</p>
</section>
<aside id="sidebar">
<p>This page was generated by <a href="https://pages.github.com">GitHub Pages</a> using the Architect theme by <a href="https://twitter.com/jasonlong">Jason Long</a>.</p>
</aside>
</div>
</div>
</body>
</html>