From a1aeb842d01d1fd979f709600087be87ae549f94 Mon Sep 17 00:00:00 2001 From: naruse Date: Wed, 15 Feb 2012 01:23:00 +0000 Subject: Correct documentation of r34608. * correct explanation of ASCII-8BIT. * "Locale encoding" is the name of the encoding derived from Encoding.locale_encoding. Its correct name is "Script encoding". * Add Locale encoding and Filesystem encoding. * default external is set by locale encoding if -E is not given. * functional methods normally written as functional style on ruby's doc. * fix typo. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@34613 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- encoding.c | 63 ++++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/encoding.c b/encoding.c index cd55dc2fa8..dd20477906 100644 --- a/encoding.c +++ b/encoding.c @@ -1621,7 +1621,7 @@ rb_enc_aliases(VALUE klass) * "some string".encoding * #=> # * - * string = "some string".encode Encoding::ISO_8859_1 + * string = "some string".encode(Encoding::ISO_8859_1) * #=> "some string" * string.encoding * #=> # @@ -1629,14 +1629,15 @@ rb_enc_aliases(VALUE klass) * "some string".encode "ISO-8859-1" * #=> "some string" * - * Encoding::ASCII_8BIT is a special encoding that does not - * correspond to any character encoding. In fact it represents the absence of - * encoding and objects with this encoding can be seen as binary data. + * Encoding::ASCII_8BIT is a special encoding that is usually + * used for a byte string, not a character string. But as the name insists, + * its characters in the range of ASCII are considered as ASCII characters. + * This is useful when you use ASCII-8BIT characters with other ASCII + * compatible characters. * * == Changing an encoding * - * The associated Encoding of a String can can be changed in two different - * ways. + * The associated Encoding of a String can be changed in two different ways. * * First, it is possible to set the Encoding of a string to a new Encoding * without changing the internal byte representation of the string, with @@ -1647,8 +1648,8 @@ rb_enc_aliases(VALUE klass) * #=> "R\xC3\xA9sum\xC3\xA9" * string.encoding * #=> # - * string.force_encoding Encoding::UTF-8 - * #=> "Résumé" + * string.force_encoding(Encoding::UTF-8) + * #=> "R\u00E9sum\u00E9" * * Second, it is possible to transcode a string, i.e. translate its internal * byte representation to another encoding. Its associated encoding is also @@ -1660,17 +1661,17 @@ rb_enc_aliases(VALUE klass) * #=> "R\u00E9sum\u00E9" * string.encoding * #=> # - * string = string.encode! Encoding::ISO_8859_1 + * string = string.encode!(Encoding::ISO_8859_1) * #=> "R\xE9sum\xE9" * string.encoding * #=> # * - * == Locale encoding + * == Script encoding * - * All Ruby source code has an associated Encoding which any String literal + * All Ruby script code has an associated Encoding which any String literal * created in the source code will be associated to. * - * The default locale encoding is Encoding::US-ASCII, but it can + * The default script encoding is Encoding::US-ASCII, but it can * be changed by a magic comment on the first line of the source code file (or * second line, if there is a shebang line on the first). The comment must * contain the word coding or encoding, followed @@ -1681,8 +1682,8 @@ rb_enc_aliases(VALUE klass) * "some string".encoding * #=> # * - * The __ENCODING__ keyword returns the locale encoding that is - * currently active: + * The __ENCODING__ keyword returns the script encoding of the file + * which the keyword is written: * * # encoding: ISO-8859-1 * @@ -1690,15 +1691,29 @@ rb_enc_aliases(VALUE klass) * #=> # * * ruby -K will change the default locale encoding, but this is - * not recommended. Ruby source files should include the locale encoding - * comment even when they depend on US-ASCII strings or regular expressions. + * not recommended. Ruby source files should declare its script encoding by a + * magic comment even when they only depend on US-ASCII strings or regular + * expressions. + * + * == Locale encoding + * + * The default encoding of the environment. Usually derived from locale. + * + * see Encoding.locale_charmap, Encoding.find('locale') + * + * == Filesystem encoding + * + * The default encoding of strings from the filesystem of the environment. + * This is used for strings of file names or paths. + * + * see Encoding.find('filesystem') * * == External encoding * * Each IO object has an external encoding which indicates the encoding that * Ruby will use to read its data. By default Ruby sets the external encoding - * of an IO object to the default external encoding (initialized from the - * user's environment, set with the interpreter -E option). + * of an IO object to the default external encoding. The default external + * encoding is set by locale encoding or the interpreter -E option. * Encoding.default_external returns the current value of the external * encoding. * @@ -1757,20 +1772,20 @@ rb_enc_aliases(VALUE klass) * * == IO encoding example * - * In the following example a UTF-8 encoded string "R.sum." is transcoded for + * In the following example a UTF-8 encoded string "R\u00E9sum\u00E9" is transcoded for * output to ISO-8859-1 encoding, then read back in and transcoded to UTF-8: * * string = "R\u00E9sum\u00E9" * - * open "transcoded.txt", "w:ISO-8859-1" do |io| - * io.write string + * open("transcoded.txt", "w:ISO-8859-1") do |io| + * io.write(string) * end * * puts "raw text:" - * p File.binread "transcoded.txt" + * p File.binread("transcoded.txt") * puts * - * open "transcoded.txt", "r:ISO-8859-1:UTF-8" do |io| + * open("transcoded.txt", "r:ISO-8859-1:UTF-8") do |io| * puts "transcoded text:" * p io.read * end @@ -1784,7 +1799,7 @@ rb_enc_aliases(VALUE klass) * "R\xE9sum\xE9" * * transcoded text: - * "R.sum." + * "R\u00E9sum\u00E9" * */ -- cgit v1.2.3