ruby-changes:42682
From: hsbt <ko1@a...>
Date: Mon, 25 Apr 2016 10:30:57 +0900 (JST)
Subject: [ruby-changes:42682] hsbt:r54756 (trunk): * doc/extension.rdoc: Improvements to english grammers.
hsbt 2016-04-25 11:27:34 +0900 (Mon, 25 Apr 2016) New Revision: 54756 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=54756 Log: * doc/extension.rdoc: Improvements to english grammers. [Bug #12246][ruby-core:74792][ci skip] Modified files: trunk/ChangeLog trunk/doc/extension.rdoc Index: doc/extension.rdoc =================================================================== --- doc/extension.rdoc (revision 54755) +++ doc/extension.rdoc (revision 54756) @@ -9,7 +9,7 @@ Ruby variables do not have a static type https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L9 types, so data will need to be converted between the languages. Data in Ruby are represented by the C type `VALUE'. Each VALUE data -has its data-type. +has its data type. To retrieve C data from a VALUE, you need to: @@ -18,7 +18,7 @@ To retrieve C data from a VALUE, you nee https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L18 Converting to the wrong data type may cause serious problems. -== Data-Types +== Data Types The Ruby interpreter has the following data types: @@ -74,7 +74,7 @@ data types, your code will look somethin https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L74 break; } -There is the data-type check function +There is the data type check function void Check_Type(VALUE value, int type) @@ -94,7 +94,7 @@ The equivalent C constants are: Qnil, Qf https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L94 Note that Qfalse is false in C also (i.e. 0), but not Qnil. The T_FIXNUM data is a 31bit or 63bit length fixed integer. -This size is depend on the size of long: if long is 32bit then +This size depends on the size of long: if long is 32bit then T_FIXNUM is 31bit, if long is 64bit then T_FIXNUM is 63bit. T_FIXNUM can be converted to a C integer by using the FIX2INT() macro or FIX2LONG(). Though you have to check that the @@ -102,21 +102,21 @@ data is really FIXNUM before using them, https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L102 never raises exceptions, but FIX2INT() raises RangeError if the result is bigger or smaller than the size of int. There are also NUM2INT() and NUM2LONG() which converts any Ruby -numbers into C integers. These macros includes a type check, +numbers into C integers. These macros include a type check, so an exception will be raised if the conversion failed. NUM2DBL() can be used to retrieve the double float value in the same way. You can use the macros StringValue() and StringValuePtr() to get a char* from a VALUE. StringValue(var) replaces var's value with the result of "var.to_str()". -StringValuePtr(var) does same replacement and returns char* +StringValuePtr(var) does the same replacement and returns the char* representation of var. These macros will skip the replacement if var is a String. Notice that the macros take only the lvalue as their argument, to change the value of var in place. You can also use the macro named StringValueCStr(). This is just -like StringValuePtr(), but always add NUL character at the end of -the result. If the result contains NUL character, this macro causes +like StringValuePtr(), but always adds a NUL character at the end of +the result. If the result contains a NUL character, this macro causes the ArgumentError exception. StringValuePtr() doesn't guarantee the existence of a NUL at the end of the result, and the result may contain NUL. @@ -126,8 +126,8 @@ for T_ARRAY etc. The VALUE of the type w https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L126 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". 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. +to access RXXXX data directly because these data structures are complex. +Use corresponding rb_xxx() functions to access the internal struct. For example, to access an entry of array, use rb_ary_entry(ary, offset) and rb_ary_store(ary, offset, obj). @@ -145,22 +145,22 @@ To convert C data to Ruby values: https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L145 FIXNUM :: - left shift 1 bit, and turn on LSB. + left shift 1 bit, and turn on its least significant bit (LSB). Other pointer values :: cast to VALUE. -You can determine whether a VALUE is pointer or not by checking its LSB. +You can determine whether a VALUE is a pointer or not by checking its LSB. -Notice Ruby does not allow arbitrary pointer values to be a VALUE. They +Notice: Ruby does not allow arbitrary pointer values to be a VALUE. They should be pointers to the structures which Ruby knows about. The known structures are defined in <ruby.h>. -To convert C numbers to Ruby values, use these macros. +To convert C numbers to Ruby values, use these macros: INT2FIX() :: for integers within 31bits. -INT2NUM() :: for arbitrary sized integer. +INT2NUM() :: for arbitrary sized integers. INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM range, but is a bit slower. @@ -258,7 +258,7 @@ rb_utf8_str_new_literal(const char *ptr) https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L258 rb_str_resize(VALUE str, long len) :: - Resizes Ruby string to len bytes. If str is not modifiable, this + Resizes a Ruby string to len bytes. If str is not modifiable, this function raises an exception. The length of str must be set in advance. If len is less than the old length the content beyond len bytes is discarded, else if len is greater than the old length @@ -268,9 +268,9 @@ rb_str_resize(VALUE str, long len) :: https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L268 rb_str_set_len(VALUE str, long len) :: - Sets the length of Ruby string. If str is not modifiable, this + Sets the length of a Ruby string. If str is not modifiable, this function raises an exception. This function preserves the content - upto len bytes, regardless RSTRING_LEN(str). len must not exceed + up to len bytes, regardless RSTRING_LEN(str). len must not exceed the capacity of str. === Array Functions @@ -400,9 +400,9 @@ There are two functions to define privat https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L400 void rb_define_protected_method(VALUE klass, const char *name, VALUE (*func)(), int argc) -At last, rb_define_module_function defines a module functions, +At last, rb_define_module_function defines a module function, which are private AND singleton methods of the module. -For example, sqrt is the module function defined in Math module. +For example, sqrt is a module function defined in the Math module. It can be called in the following way: Math.sqrt(4) @@ -478,7 +478,7 @@ function: https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L478 VALUE rb_eval_string_protect(const char *str, int *state) -It returns nil when an error occur. Moreover, *state is zero if str was +It returns nil when an error occurred. Moreover, *state is zero if str was successfully evaluated, or nonzero otherwise. === ID or Symbol @@ -562,7 +562,7 @@ See also Constant Definition above. https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L562 = Information Sharing Between Ruby and C -=== Ruby Constants That C Can Be Accessed From C +=== Ruby Constants That Can Be Accessed From C As stated in section 1.3, the following Ruby constants can be referred from C. @@ -746,7 +746,7 @@ A pointer to the structure will be assig https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L746 See the example below for details. -= Example - Creating dbm Extension += Example - Creating the dbm Extension OK, here's the example of making an extension library. This is the extension to access DBMs. The full source is included in the ext/ @@ -1249,7 +1249,7 @@ rb_str_new2(s) :: https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L1249 char * -> String -== Defining Class and Module +== Defining Classes and Modules VALUE rb_define_class(const char *name, VALUE super) :: Index: ChangeLog =================================================================== --- ChangeLog (revision 54755) +++ ChangeLog (revision 54756) @@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Mon Apr 25 11:27:27 2016 Marcus Stollsteimer <sto.mar@w...> + + * doc/extension.rdoc: Improvements to english grammers. + [Bug #12246][ruby-core:74792][ci skip] + Mon Apr 25 11:17:50 2016 Marcus Stollsteimer <sto.mar@w...> * encoding.c: Fix return value of `Encoding::ISO8859_1.name` -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/