* sprintf.c: add short documentation about named reference.

  [ruby-core:31294]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@28702 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 17 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 7598f490f9..17efacb077 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Wed Jul 21 15:15:02 2010  NARUSE, Yui  <naruse@ruby-lang.org>
+
+	* sprintf.c: add short documentation about named reference.
+	  [ruby-core:31294]
+
 Wed Jul 21 15:00:19 2010  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* parse.y (local_push_gen): disable unused variable warnings in
diff --git a/sprintf.c b/sprintf.c
index 8a83cb3446..4f3b51701e 100644
--- a/sprintf.c
+++ b/sprintf.c
@@ -420,6 +420,15 @@ get_hash(volatile VALUE *hash, int argc, const VALUE *argv)
  *     sprintf("%1$*2$s %2$d", "hello", -8)       #=> "hello    -8"
  *     sprintf("%+g:% g:%-g", 1.23, 1.23, 1.23)   #=> "+1.23: 1.23:1.23"
  *     sprintf("%u", -123)                        #=> "-123"
+ *
+ *  For more complex formatting, Ruby supports a reference by name.
+ *  %<name>s style uses format style, but ${name} style doesn't.
+ *
+ *  Exapmles:
+ *    sprintf("%<foo>d : %<bar>f" % { :foo => 1, :bar => 2 })
+ *      #=> 1 : 2.000000
+ *    sprintf("%d %{foo}" % { :foo => 'bar' })
+ *      # => "%d bar"
  */
 
 VALUE
diff --git a/test/ruby/test_sprintf.rb b/test/ruby/test_sprintf.rb
index 05bccde066..96a1b62bb7 100644
--- a/test/ruby/test_sprintf.rb
+++ b/test/ruby/test_sprintf.rb
@@ -294,5 +294,8 @@ class TestSprintf < Test::Unit::TestCase
     assert_equal("value", sprintf("%<key>s", :key => "value"))
     assert_raise(ArgumentError) {sprintf("%1$<key2>s", :key => "value")}
     assert_raise(ArgumentError) {sprintf("%<key><key2>s", :key => "value")}
+    assert_equal("value", sprintf("%{key}", :key => "value"))
+    assert_raise(ArgumentError) {sprintf("%1${key2}", :key => "value")}
+    assert_equal("value{key2}", sprintf("%{key}{key2}", :key => "value"))
   end
 end