ruby.h: export keyword argument functions

* include/ruby/ruby.h (rb_get_kwargs, rb_extract_keywords): export
  keyword argument functions.

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

ChangeLog

@@ -1,3 +1,8 @@
+Wed Nov 26 22:28:12 2014  Nobuyoshi Nakada  <nobu@ruby-lang.org>
+
+	* include/ruby/ruby.h (rb_get_kwargs, rb_extract_keywords): export
+	  keyword argument functions.
+
 Wed Nov 26 21:18:40 2014  SHIBATA Hiroshi  <shibata.hiroshi@gmail.com>
 
 	* test/inlinetest.rb: removed unused test helper.

NEWS

@@ -314,6 +314,9 @@ with all sufficient information, see the ChangeLog file.
 
 * rb_hash_delete() now does not call the block given to the current method.
 
+* rb_extract_keywords() and rb_get_kwargs() exported.  See README.EXT
+  for details.
+
 === Build system updates
 
 * jemalloc is optionally supported via `./configure --with-jemalloc`

README.EXT

@@ -1305,6 +1305,26 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
   The number of given arguments, excluding an option hash or iterator
   block, is returned.
 
+int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
+
+  Retrieves argument VALUEs bound to keywords, which directed by +table+
+  into +values+.  First +required+ number of IDs referred by +table+ are
+  mandatory, and succeeding +optional+ (- +optional+ - 1 if 
+  +optional+ is negative) number of IDs are optional.  If a
+  mandatory key is not contained in +keyword_hash+, raises "missing
+  keyword" +ArgumentError+.  If an optional key is not present in
+  +keyword_hash+, the corresponding element in +values+ is not changed.
+  If +optional+ is negative, rest of +keyword_hash+ are stored in the
+  next to optional +values+ as a new Hash, otherwise raises "unknown
+  keyword" +ArgumentError+.
+
+VALUE rb_extract_keywords(VALUE *original_hash)
+
+  Extrancts pairs whose key is a symbol into a new hash from a hash
+  object referred by +original_hash+.  If the original hash contains
+  non-symbol keys, then they are copied to another hash and the new hash
+  is stored through +original_hash+, else 0 is stored.
+
 == Invoking Ruby method
 
 VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::

README.EXT.ja

@@ -1307,6 +1307,25 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
   返り値は与えられた引数の数です．オプションハッシュおよびイ
   テレータブロックは数えません．
 
+int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
+
+  キーワードで指定された値をtableにしたがって取り出します．
+  tableの最初のrequired個のIDは必須キーワードを表し，続く
+  optional (optionalが負の場合は-optional-1) 個のIDは省略可能
+  キーワードです．必須キーワードがkeyword_hash中にない場合，
+  "missing keyword"ArgumentErrorが発生します．省略可能キーワー
+  ドがない場合は，values中の対応する要素は変更されません．
+  keyword_hashに使用されない要素がある場合は，optionalが負なら
+  新しいHashとして省略可能引数の次に保存されますが，そうでなけ
+  れば"unknown keyword"ArgumentErrorが発生します．
+
+VALUE rb_extract_keywords(VALUE *original_hash)
+
+  original_hashで参照されるHashオブジェクトから，Symbolである
+  キーとその値を新しいHashに取り出します．original_hashの指す
+  先には，元のHashがSymbol以外のキーを含んでいた場合はそれらが
+  コピーされた別の新しいHash，そうでなければ0が保存されます．
+
 == Rubyメソッド呼び出し
 
 VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::

include/ruby/ruby.h

@@ -1475,6 +1475,8 @@ VALUE rb_funcall_with_block(VALUE, ID, int, const VALUE*, VALUE);
 int rb_scan_args(int, const VALUE*, const char*, ...);
 VALUE rb_call_super(int, const VALUE*);
 VALUE rb_current_receiver(void);
+int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *);
+VALUE rb_extract_keywords(VALUE *orighash);
 
 /* rb_scan_args() format allows ':' for optional hash */
 #define HAVE_RB_SCAN_ARGS_OPTIONAL_HASH 1

internal.h

@@ -1064,8 +1064,6 @@ VALUE rb_catch_protect(VALUE t, rb_block_call_func *func, VALUE data, int *state
 
 /* vm_insnhelper.c */
 VALUE rb_equal_opt(VALUE obj1, VALUE obj2);
-int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *);
-VALUE rb_extract_keywords(VALUE *orighash);
 
 /* vm_method.c */
 void Init_eval_method(void);