Ruby C Extension Cheat Sheet

ATTENTION: This page is very out of date. It has not been updated since 2007, and will not be updated in the future.

I got tired of looking all over for call sequences (let alone proper documentation) for functions used for creating Ruby extensions written in C, so I’m making notes about some functions I have found useful in creating Rubygame (and some I just included for completeness). This list is by no means comprehensive! There’s a lot missing, which I either don’t use or didn’t feel like posting. I update this page sporadically.

Here are some decent references I use, and which provided the information I catalog on this page:

• Ruby 1.8.4 Doxygen:
  • Ruby Interpretor Interface
  • ruby.h docs
  • intern.h docs
• Ruby 1.8.6 source:
  • README.EXT
  • ruby.h source
  • intern.h source
• Programming Ruby, Chapter 21 “Extending Ruby” (p. 275 - 314)
  • Converting C types to Ruby and vice versa (p. 280)
  • Wrapping C data (p. 285)
  • Allocation and initialization functions (p. 287 - 290)
  • API reference (p. 305 - 314)

Testing Ruby objects

• RTEST( VALUE )

  True if object would be true in “if( object )” in Ruby, i.e. object is neither ‘false’ nor ‘nil’.

• TYPE( VALUE )

  return T_* (e.g. T_STRING, T_ARRAY, T_FIXNUM, T_SYMBOL, T_DATA) depending on the Ruby type of VALUE. Wrapped objects return T_DATA.

• Qtrue, Qfalse, Qnil

  Variables for the Ruby values of true, false, and nil.

C types -> Ruby objects

• INT2NUM( int ) – convert an integer to Fixnum or Bignum.
• UINT2NUM( unsigned int ) – convert an unsigned integer to Fixnum or Bignum.
• rb_float_new( double ) – convert a double to Float.
• rb_str_new2( char* ) – convert a character string to String.
• rb_intern( char* ) – convert a character string to ID (for Ruby function names, etc.).
• ID2SYM( rb_intern(char*) ) – convert a character string to a ruby Symbol object.

Ruby objects -> C types

• NUM2INT( VALUE ) – convert Numeric to integer.
• NUM2UINT( VALUE ) – convert Numeric to unsigned integer.
• NUM2DBL( VALUE ) – convert Numeric to double.
• RSTRING( VALUE )->len – length of a String.
• RSTRING( VALUE )->ptr – char * pointer to string data.

Wrapping C objects into Ruby objects (and back again)

• Data_Wrap_Struct( cKlass, mark_func, free_func, data* )

  Wrap data (a pointer to a C type instance) as instance of cKlass (which is a VALUE reference to a Ruby class).

• Data_Make_Struct( cKlass, data_type, mark_func, free_funk, data* )

  Like Data_Wrap_Struct, but allocate memory for a new data_type first. I don’t use this much, actually, but I included it for completeness.

• Data_Get_Struct( VALUE, data_type, data* )

  Unwrap the ruby object as a data_type, and set data* to point to it.

Accessing Variables / Constants

• rb_define_const( VALUE module, char* name, VALUE value )

  Create a new constant with this name, under the module, and set its value.

• rb_define_global_const( char* name, VALUE value )

  Create a constant in the global namespace (same as rb_define_const using rb_cObject as the module).

• rb_const_get( VALUE module, ID name )

  Get the value of the constant with this name, defined under the module/class

• rb_const_set( VALUE module, ID name, VALUE value )

  Set the value of the constant with this name, defined under the module/class

Generally Useful Functions

• rb_any_to_s( VALUE object ) – Calls #to_s on the object. Returns a Ruby string.

• rb_inspect( VALUE object ) – Calls #inspect on the object. Returns a Ruby string.

• rb_raise( VALUE error_klass, char *message, […] )

  Like raise in Ruby. The message can have printf-style substitution (%s, etc.). Args after the message are plugged into the substitution.

• rb_warn( char *message, […] )

  Prints a warning message to the console, including the file and line number of the ruby code that called the function that emitted the warning. The message can have printf-style substitution (%s, etc.). Args after the message are plugged into the substitution.

• rb_warning( char *message, […] )

  Like rb_warn, but only prints a message if the Ruby global variable $VERBOSE is true.

Rubygame Helpers

These are reusable functions I created for convenience. They are part of Rubygame, not part of Ruby.

• make_symbol( char* ) – Convert character string to Symbol. Equivalent to ID2SYM( rb_intern( char* ) ).