Project

General

Profile

Bug #12246 ยป doc_extension_lang.patch

stomar (Marcus Stollsteimer), 04/02/2016 08:45 PM

View differences:

doc/extension.rdoc
9 9
types, so data will need to be converted between the languages.
10 10

  
11 11
Data in Ruby are represented by the C type `VALUE'.  Each VALUE data
12
has its data-type.
12
has its data type.
13 13

  
14 14
To retrieve C data from a VALUE, you need to:
15 15

  
......
18 18

  
19 19
Converting to the wrong data type may cause serious problems.
20 20

  
21
== Data-Types
21
== Data Types
22 22

  
23 23
The Ruby interpreter has the following data types:
24 24

  
......
74 74
      break;
75 75
  }
76 76

  
77
There is the data-type check function
77
There is the data type check function
78 78

  
79 79
  void Check_Type(VALUE value, int type)
80 80

  
......
94 94
Note that Qfalse is false in C also (i.e. 0), but not Qnil.
95 95

  
96 96
The T_FIXNUM data is a 31bit or 63bit length fixed integer.
97
This size is depend on the size of long: if long is 32bit then
97
This size depends on the size of long: if long is 32bit then
98 98
T_FIXNUM is 31bit, if long is 64bit then T_FIXNUM is 63bit.
99 99
T_FIXNUM can be converted to a C integer by using the
100 100
FIX2INT() macro or FIX2LONG().  Though you have to check that the
......
102 102
never raises exceptions, but FIX2INT() raises RangeError if the
103 103
result is bigger or smaller than the size of int.
104 104
There are also NUM2INT() and NUM2LONG() which converts any Ruby
105
numbers into C integers.  These macros includes a type check,
105
numbers into C integers.  These macros include a type check,
106 106
so an exception will be raised if the conversion failed.  NUM2DBL()
107 107
can be used to retrieve the double float value in the same way.
108 108

  
109 109
You can use the macros
110 110
StringValue() and StringValuePtr() to get a char* from a VALUE.
111 111
StringValue(var) replaces var's value with the result of "var.to_str()".
112
StringValuePtr(var) does same replacement and returns char*
112
StringValuePtr(var) does the same replacement and returns the char*
113 113
representation of var.  These macros will skip the replacement if var
114 114
is a String.  Notice that the macros take only the lvalue as their
115 115
argument, to change the value of var in place.
116 116

  
117 117
You can also use the macro named StringValueCStr(). This is just
118
like StringValuePtr(), but always add NUL character at the end of
119
the result. If the result contains NUL character, this macro causes
118
like StringValuePtr(), but always adds a NUL character at the end of
119
the result. If the result contains a NUL character, this macro causes
120 120
the ArgumentError exception.
121 121
StringValuePtr() doesn't guarantee the existence of a NUL at the end
122 122
of the result, and the result may contain NUL.
......
126 126
structure can be cast to retrieve the pointer to the struct.  The
127 127
casting macro will be of the form RXXXX for each data type; for
128 128
instance, RARRAY(obj).  See "ruby.h".  However, we do not recommend
129
to access RXXXX data directly because these data structure is complex.
130
Use corresponding rb_xxx() functions to access internal struct.
129
to access RXXXX data directly because these data structures are complex.
130
Use corresponding rb_xxx() functions to access the internal struct.
131 131
For example, to access an entry of array, use rb_ary_entry(ary, offset)
132 132
and rb_ary_store(ary, offset, obj).
133 133

  
......
145 145

  
146 146
FIXNUM ::
147 147

  
148
  left shift 1 bit, and turn on LSB.
148
  left shift 1 bit, and turn on its least significant bit (LSB).
149 149

  
150 150
Other pointer values ::
151 151

  
152 152
  cast to VALUE.
153 153

  
154
You can determine whether a VALUE is pointer or not by checking its LSB.
154
You can determine whether a VALUE is a pointer or not by checking its LSB.
155 155

  
156
Notice Ruby does not allow arbitrary pointer values to be a VALUE.  They
156
Notice: Ruby does not allow arbitrary pointer values to be a VALUE.  They
157 157
should be pointers to the structures which Ruby knows about.  The known
158 158
structures are defined in <ruby.h>.
159 159

  
160
To convert C numbers to Ruby values, use these macros.
160
To convert C numbers to Ruby values, use these macros:
161 161

  
162 162
INT2FIX() :: for integers within 31bits.
163
INT2NUM() :: for arbitrary sized integer.
163
INT2NUM() :: for arbitrary sized integers.
164 164

  
165 165
INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
166 166
range, but is a bit slower.
......
258 258

  
259 259
rb_str_resize(VALUE str, long len) ::
260 260

  
261
  Resizes Ruby string to len bytes.  If str is not modifiable, this
261
  Resizes a Ruby string to len bytes.  If str is not modifiable, this
262 262
  function raises an exception.  The length of str must be set in
263 263
  advance.  If len is less than the old length the content beyond
264 264
  len bytes is discarded, else if len is greater than the old length
......
268 268

  
269 269
rb_str_set_len(VALUE str, long len) ::
270 270

  
271
  Sets the length of Ruby string.  If str is not modifiable, this
271
  Sets the length of a Ruby string.  If str is not modifiable, this
272 272
  function raises an exception.  This function preserves the content
273
  upto len bytes, regardless RSTRING_LEN(str).  len must not exceed
273
  up to len bytes, regardless RSTRING_LEN(str).  len must not exceed
274 274
  the capacity of str.
275 275

  
276 276
=== Array Functions
......
400 400
  void rb_define_protected_method(VALUE klass, const char *name,
401 401
			          VALUE (*func)(), int argc)
402 402

  
403
At last, rb_define_module_function defines a module functions,
403
At last, rb_define_module_function defines a module function,
404 404
which are private AND singleton methods of the module.
405
For example, sqrt is the module function defined in Math module.
405
For example, sqrt is a module function defined in the Math module.
406 406
It can be called in the following way:
407 407

  
408 408
  Math.sqrt(4)
......
478 478

  
479 479
  VALUE rb_eval_string_protect(const char *str, int *state)
480 480

  
481
It returns nil when an error occur. Moreover, *state is zero if str was
481
It returns nil when an error occurred. Moreover, *state is zero if str was
482 482
successfully evaluated, or nonzero otherwise.
483 483

  
484 484
=== ID or Symbol
......
562 562

  
563 563
= Information Sharing Between Ruby and C
564 564

  
565
=== Ruby Constants That C Can Be Accessed From C
565
=== Ruby Constants That Can Be Accessed From C
566 566

  
567 567
As stated in section 1.3,
568 568
the following Ruby constants can be referred from C.
......
746 746

  
747 747
See the example below for details.
748 748

  
749
= Example - Creating dbm Extension
749
= Example - Creating the dbm Extension
750 750

  
751 751
OK, here's the example of making an extension library.  This is the
752 752
extension to access DBMs.  The full source is included in the ext/
......
1249 1249

  
1250 1250
  char * -> String
1251 1251

  
1252
== Defining Class and Module
1252
== Defining Classes and Modules
1253 1253

  
1254 1254
VALUE rb_define_class(const char *name, VALUE super) ::
1255 1255