• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Punycode
2
3<!-- YAML
4deprecated: v7.0.0
5-->
6
7<!--introduced_in=v0.10.0-->
8
9> Stability: 0 - Deprecated
10
11<!-- source_link=lib/punycode.js -->
12
13**The version of the punycode module bundled in Node.js is being deprecated.**
14In a future major version of Node.js this module will be removed. Users
15currently depending on the `punycode` module should switch to using the
16userland-provided [Punycode.js][] module instead. For punycode-based URL
17encoding, see [`url.domainToASCII`][] or, more generally, the
18[WHATWG URL API][].
19
20The `punycode` module is a bundled version of the [Punycode.js][] module. It
21can be accessed using:
22
23```js
24const punycode = require('punycode');
25```
26
27[Punycode][] is a character encoding scheme defined by RFC 3492 that is
28primarily intended for use in Internationalized Domain Names. Because host
29names in URLs are limited to ASCII characters only, Domain Names that contain
30non-ASCII characters must be converted into ASCII using the Punycode scheme.
31For instance, the Japanese character that translates into the English word,
32`'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent
33to `'example.com'`) is represented by Punycode as the ASCII string
34`'xn--fsq.com'`.
35
36The `punycode` module provides a simple implementation of the Punycode standard.
37
38The `punycode` module is a third-party dependency used by Node.js and
39made available to developers as a convenience. Fixes or other modifications to
40the module must be directed to the [Punycode.js][] project.
41
42## `punycode.decode(string)`
43
44<!-- YAML
45added: v0.5.1
46-->
47
48* `string` {string}
49
50The `punycode.decode()` method converts a [Punycode][] string of ASCII-only
51characters to the equivalent string of Unicode codepoints.
52
53```js
54punycode.decode('maana-pta'); // 'mañana'
55punycode.decode('--dqo34k'); // '☃-⌘'
56```
57
58## `punycode.encode(string)`
59
60<!-- YAML
61added: v0.5.1
62-->
63
64* `string` {string}
65
66The `punycode.encode()` method converts a string of Unicode codepoints to a
67[Punycode][] string of ASCII-only characters.
68
69```js
70punycode.encode('mañana'); // 'maana-pta'
71punycode.encode('☃-⌘'); // '--dqo34k'
72```
73
74## `punycode.toASCII(domain)`
75
76<!-- YAML
77added: v0.6.1
78-->
79
80* `domain` {string}
81
82The `punycode.toASCII()` method converts a Unicode string representing an
83Internationalized Domain Name to [Punycode][]. Only the non-ASCII parts of the
84domain name will be converted. Calling `punycode.toASCII()` on a string that
85already only contains ASCII characters will have no effect.
86
87```js
88// encode domain names
89punycode.toASCII('mañana.com');  // 'xn--maana-pta.com'
90punycode.toASCII('☃-⌘.com');   // 'xn----dqo34k.com'
91punycode.toASCII('example.com'); // 'example.com'
92```
93
94## `punycode.toUnicode(domain)`
95
96<!-- YAML
97added: v0.6.1
98-->
99
100* `domain` {string}
101
102The `punycode.toUnicode()` method converts a string representing a domain name
103containing [Punycode][] encoded characters into Unicode. Only the [Punycode][]
104encoded parts of the domain name are be converted.
105
106```js
107// decode domain names
108punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com'
109punycode.toUnicode('xn----dqo34k.com');  // '☃-⌘.com'
110punycode.toUnicode('example.com');       // 'example.com'
111```
112
113## `punycode.ucs2`
114
115<!-- YAML
116added: v0.7.0
117-->
118
119### `punycode.ucs2.decode(string)`
120
121<!-- YAML
122added: v0.7.0
123-->
124
125* `string` {string}
126
127The `punycode.ucs2.decode()` method returns an array containing the numeric
128codepoint values of each Unicode symbol in the string.
129
130```js
131punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63]
132// surrogate pair for U+1D306 tetragram for centre:
133punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306]
134```
135
136### `punycode.ucs2.encode(codePoints)`
137
138<!-- YAML
139added: v0.7.0
140-->
141
142* `codePoints` {integer\[]}
143
144The `punycode.ucs2.encode()` method returns a string based on an array of
145numeric code point values.
146
147```js
148punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc'
149punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06'
150```
151
152## `punycode.version`
153
154<!-- YAML
155added: v0.6.1
156-->
157
158* {string}
159
160Returns a string identifying the current [Punycode.js][] version number.
161
162[Punycode]: https://tools.ietf.org/html/rfc3492
163[Punycode.js]: https://github.com/bestiejs/punycode.js
164[WHATWG URL API]: url.md#the-whatwg-url-api
165[`url.domainToASCII`]: url.md#urldomaintoasciidomain
166