* README.EXT, README.EXT.ja: remove description of RARRAY_PTR()

and add a caution of accessing internal data structure directly.
  Also add a description of rb_ary_store().
  [Bug #8399]



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

ChangeLog

@@ -1,3 +1,10 @@
+Wed Sep 25 17:41:29 2013  Koichi Sasada  <ko1@atdot.net>
+
+	* README.EXT, README.EXT.ja: remove description of RARRAY_PTR()
+	  and add a caution of accessing internal data structure directly.
+	  Also add a description of rb_ary_store().
+	  [Bug #8399]
+
 Wed Sep 25 17:12:08 2013  Koichi Sasada  <ko1@atdot.net>
 
 	* include/ruby/ruby.h: rename RARRAY_RAWPTR() to RARRAY_CONST_PTR().

README.EXT

@@ -125,12 +125,15 @@ Other data types have corresponding C structures, e.g. struct RArray
 for T_ARRAY etc. The VALUE of the type which has the corresponding
 structure can be cast to retrieve the pointer to the struct.  The
 casting macro will be of the form RXXXX for each data type; for
-instance, RARRAY(obj).  See "ruby.h".
+instance, RARRAY(obj).  See "ruby.h".  However, we do not recommend
+to access RXXXX data directly because these data structure is complex.
+Use corresponding rb_xxx() functions to access internal struct.
+For example, to access an entry of array, use rb_ary_entry(ary, offset)
+and rb_ary_store(ary, offset, obj).
 
 There are some accessing macros for structure members, for example
 `RSTRING_LEN(str)' to get the size of the Ruby String object.  The
-allocated region can be accessed by `RSTRING_PTR(str)'.  For arrays,
-use `RARRAY_LEN(ary)' and `RARRAY_PTR(ary)' respectively.
+allocated region can be accessed by `RSTRING_PTR(str)'.
 
 Notice: Do not change the value of the structure directly, unless you
 are responsible for the result.  This ends up being the cause of
@@ -282,6 +285,10 @@ rb_ary_entry(VALUE ary, long offset) ::
 
   ary[offset]
 
+rb_ary_store(VALUE ary, long offset, VALUE obj) ::
+
+  ary[offset] = obj
+
 rb_ary_subseq(VALUE ary, long beg, long len) ::
 
   ary[beg, len]

README.EXT.ja

@@ -140,13 +140,15 @@ var は lvalue である必要があります．
 あるのは文字列と配列くらいだと思います．
 
 ruby.hでは構造体へキャストするマクロも「RXXXXX()」(全部大文
-字にしたもの)という名前で提供されています(例: RSTRING())．
+字にしたもの)という名前で提供されています(例: RSTRING())．た
+だし、構造体への直接のアクセスはできるだけ避け，対応する 
+rb_xxxx() といった関数を使うようにして下さい．例えば，配列の
+要素へアクセスする場合は，rb_ary_entry(ary, offset)，
+rb_ary_store(ary, offset, obj) を利用するようにして下さい．
 
 構造体からデータを取り出すマクロが提供されています．文字列
 strの長さを得るためには「RSTRING_LEN(str)」とし，文字列strを
-char*として得るためには「RSTRING_PTR(str)」とします．配列の
-場合には，それぞれ「RARRAY_LEN(ary)」，「RARRAY_PTR(ary)」と
-なります．
+char*として得るためには「RSTRING_PTR(str)」とします．
 
 Rubyの構造体を直接アクセスする時に気をつけなければならないこ
 とは，配列や文字列の構造体の中身は参照するだけで，直接変更し
@@ -310,6 +312,10 @@ rb_ary_entry(VALUE ary, long offset)
 
   ary[offset]
 
+rb_ary_store(VALUE ary, long offset, VALUE obj) ::
+
+  ary[offset] = obj
+
 rb_ary_subseq(VALUE ary, long beg, long len)
 
   ary[beg, len]