From 83e32266b6ebf60b7c5f31dbaa4f90fa4b2e0a06 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Fri, 27 May 2016 12:08:17 -0700 Subject: doc: general improvements to punycode.md copy PR-URL: https://github.com/nodejs/node/pull/7025 Reviewed-By: Benjamin Gruenbaum --- doc/api/punycode.md | 78 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 23 deletions(-) (limited to 'doc/api/punycode.md') diff --git a/doc/api/punycode.md b/doc/api/punycode.md index f94ecb16bf..d34b3fdf2a 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -2,19 +2,39 @@ Stability: 2 - Stable -[Punycode.js][] is bundled with Node.js v0.5.1+. Use `require('punycode')` to -access it. (To use it with other Node.js versions, use npm to install the -`punycode` module first.) +The `punycode` module is a bundled version of the [Punycode.js][] module. It +can be accessed using: + +```js +const punycode = require('punycode'); +``` + +[Punycode][] is a character encoding scheme defined by RFC 3492 that is +primarily intended for use in Internationalized Domain Names. Because host +names in URLs are limited to ASCII characters only, Domain Names that contain +non-ASCII characters must be converted into ASCII using the Punycode scheme. +For instance, the Japanese character that translates into the English word, +`'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent +to `'example.com'`) is represented by Punycode as the ASCII string +`'xn--fsq.com'`. + +The `punycode` module provides a simple implementation of the Punycode standard. + +*Note*: The `punycode` module is a third-party dependency used by Node.js and +made available to developers as a convenience. Fixes or other modifications to +the module must be directed to the [Punycode.js][] project. ## punycode.decode(string) -Converts a Punycode string of ASCII-only symbols to a string of Unicode symbols. +* `string` {String} + +The `punycode.decode()` method converts a [Punycode][] string of ASCII-only +characters to the equivalent string of Unicode codepoints. ```js -// decode domain name parts punycode.decode('maana-pta'); // 'mañana' punycode.decode('--dqo34k'); // '☃-⌘' ``` @@ -24,10 +44,12 @@ punycode.decode('--dqo34k'); // '☃-⌘' added: v0.5.1 --> -Converts a string of Unicode symbols to a Punycode string of ASCII-only symbols. +* `string` {String} + +The `punycode.encode()` method converts a string of Unicode codepoints to a +[Punycode][] string of ASCII-only characters. ```js -// encode domain name parts punycode.encode('mañana'); // 'maana-pta' punycode.encode('☃-⌘'); // '--dqo34k' ``` @@ -37,14 +59,18 @@ punycode.encode('☃-⌘'); // '--dqo34k' added: v0.6.1 --> -Converts a Unicode string representing a domain name to Punycode. Only the -non-ASCII parts of the domain name will be converted, i.e. it doesn't matter if -you call it with a domain that's already in ASCII. +* `domain` {String} + +The `punycode.toASCII()` method converts a Unicode string representing an +Internationalized Domain Name to [Punycode][]. Only the non-ASCII parts of the +domain name will be converted. Calling `punycode.toASCII()` on a string that +already only contains ASCII characters will have no effect. ```js // encode domain names -punycode.toASCII('mañana.com'); // 'xn--maana-pta.com' -punycode.toASCII('☃-⌘.com'); // 'xn----dqo34k.com' +punycode.toASCII('mañana.com'); // 'xn--maana-pta.com' +punycode.toASCII('☃-⌘.com'); // 'xn----dqo34k.com' +punycode.toASCII('example.com'); // 'example.com' ``` ## punycode.toUnicode(domain) @@ -52,14 +78,17 @@ punycode.toASCII('☃-⌘.com'); // 'xn----dqo34k.com' added: v0.6.1 --> -Converts a Punycode string representing a domain name to Unicode. Only the -Punycoded parts of the domain name will be converted, i.e. it doesn't matter if -you call it on a string that has already been converted to Unicode. +* `domain` {String} + +The `punycode.toUnicode()` method converts a string representing a domain name +containing [Punycode][] encoded characters into Unicode. Only the [Punycode][] +encoded parts of the domain name are be converted. ```js // decode domain names punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com' -punycode.toUnicode('xn----dqo34k.com'); // '☃-⌘.com' +punycode.toUnicode('xn----dqo34k.com'); // '☃-⌘.com' +punycode.toUnicode('example.com'); // 'example.com' ``` ## punycode.ucs2 @@ -72,10 +101,10 @@ added: v0.7.0 added: v0.7.0 --> -Creates an array containing the numeric code point values of each Unicode -symbol in the string. While [JavaScript uses UCS-2 internally][], this function -will convert a pair of surrogate halves (each of which UCS-2 exposes as -separate characters) into a single code point, matching UTF-16. +* `string` {String} + +The `punycode.ucs2.decode()` method returns an array containing the numeric +codepoint values of each Unicode symbol in the string. ```js punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63] @@ -88,7 +117,10 @@ punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306] added: v0.7.0 --> -Creates a string based on an array of numeric code point values. +* `codePoints` {Array} + +The `punycode.ucs2.encode()` method returns a string based on an array of +numeric code point values. ```js punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc' @@ -100,7 +132,7 @@ punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06' added: v0.6.1 --> -A string representing the current Punycode.js version number. +Returns a string identifying the current [Punycode.js][] version number. +[Punycode]: https://tools.ietf.org/html/rfc3492 [Punycode.js]: https://mths.be/punycode -[JavaScript uses UCS-2 internally]: https://mathiasbynens.be/notes/javascript-encoding -- cgit v1.2.1