summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-18 20:58:19 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-18 20:58:19 +0000
commit40e6facf51085c5adccfc6818f2792bed1662b78 (patch)
tree2635e486c599947e2ce6216c318bd8c8d245de1e
parent7dd49ed5a78a2631f1a59635b1a0d6b9e18193cf (diff)
* encoding.c: Improve documentation for Encoding#default_external and
Encoding#default_internal. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31631 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--ChangeLog5
-rw-r--r--encoding.c66
2 files changed, 65 insertions, 6 deletions
diff --git a/ChangeLog b/ChangeLog
index 222f322cf17..cd2078e8fc1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Thu May 19 05:57:52 2011 Eric Hodel <drbrain@segment7.net>
+
+ * encoding.c: Improve documentation for Encoding#default_external and
+ Encoding#default_internal.
+
Wed May 18 22:45:26 2011 Nobuyoshi Nakada <nobu@ruby-lang.org>
* ext/io/console/lib/console/size.rb (IO#console_size): new
diff --git a/encoding.c b/encoding.c
index 58497c268b8..ac6aee7594f 100644
--- a/encoding.c
+++ b/encoding.c
@@ -1246,7 +1246,25 @@ rb_enc_default_external(void)
*
* Returns default external encoding.
*
- * It is initialized by the locale or -E option.
+ * The default external encoding is used by default for strings created from
+ * the following locations:
+ *
+ * * CSV
+ * * File data read from disk
+ * * SDBM
+ * * StringIO
+ * * Zlib::GzipReader
+ * * Zlib::GzipWriter
+ * * String#inspect
+ * * Regexp#inspect
+ *
+ * While strings created from these locations will have this encoding, the
+ * encoding may not be valid. Be sure to check String#valid_encoding?.
+ *
+ * File data written to disk will be transcoded to the default external
+ * encoding when written.
+ *
+ * The default external encoding is initialized by the locale or -E option.
*/
static VALUE
get_default_external(VALUE klass)
@@ -1268,7 +1286,14 @@ rb_enc_set_default_external(VALUE encoding)
* call-seq:
* Encoding.default_external = enc
*
- * Sets default external encoding.
+ * Sets default external encoding. You should not set
+ * Encoding::default_external in ruby code as strings created before changing
+ * the value may have a different encoding from strings created after thevalue
+ * was changed., instead you should use <tt>ruby -E</tt> to invoke ruby with
+ * the correct default_external.
+ *
+ * See Encoding::default_external for information on how the default external
+ * encoding is used.
*/
static VALUE
set_default_external(VALUE klass, VALUE encoding)
@@ -1300,9 +1325,32 @@ rb_enc_default_internal(void)
* call-seq:
* Encoding.default_internal -> enc
*
- * Returns default internal encoding.
+ * Returns default internal encoding. Strings will be transcoded to the
+ * default internal encoding in the following places if the default internal
+ * encoding is not nil:
*
- * It is initialized by the source internal_encoding or -E option.
+ * * CSV
+ * * Etc.sysconfdir and Etc.systmpdir
+ * * File data read from disk
+ * * File names from Dir
+ * * Integer#chr
+ * * String#inspect and Regexp#inspect
+ * * Strings returned from Curses
+ * * Strings returned from Readline
+ * * Strings returned from SDBM
+ * * Time#zone
+ * * Values from ENV
+ * * Values in ARGV including $PROGRAM_NAME
+ * * __FILE__
+ *
+ * Additionally String#encode and String#encode! use the default internal
+ * encoding if no encoding is given.
+ *
+ * The locale encoding (__ENCODING__), not default_internal, is used as the
+ * encoding of created strings.
+ *
+ * Encoding::default_internal is initialized by the source file's
+ * internal_encoding or -E option.
*/
static VALUE
get_default_internal(VALUE klass)
@@ -1321,8 +1369,14 @@ rb_enc_set_default_internal(VALUE encoding)
* call-seq:
* Encoding.default_internal = enc or nil
*
- * Sets default internal encoding.
- * Or removes default internal encoding when passed nil.
+ * Sets default internal encoding or removes default internal encoding when
+ * passed nil. You should not set Encoding::default_internal in ruby code as
+ * strings created before changing the value may have a different encoding
+ * from strings created after the change. Instead you should use
+ * <tt>ruby -E</tt> to invoke ruby with the correct default_internal.
+ *
+ * See Encoding::default_internal for information on how the default internal
+ * encoding is used.
*/
static VALUE
set_default_internal(VALUE klass, VALUE encoding)