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