Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Functions
struct.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Public APIs related to rb_cStruct. More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/intern/vm.h"
#include "ruby/internal/value.h"
Include dependency graph for struct.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

VALUE rb_struct_new (VALUE klass,...)
 Creates an instance of the given struct. More...
 
VALUE rb_struct_define (const char *name,...)
 Defines a struct class. More...
 
VALUE rb_struct_define_under (VALUE space, const char *name,...)
 Identical to rb_struct_define(), except it defines the class under the specified namespace instead of global toplevel. More...
 
VALUE rb_struct_alloc (VALUE klass, VALUE values)
 Identical to rb_struct_new(), except it takes the field values as a Ruby array. More...
 
VALUE rb_struct_initialize (VALUE self, VALUE values)
 Mass-assigns a struct's fields. More...
 
VALUE rb_struct_getmember (VALUE self, ID key)
 Identical to rb_struct_aref(), except it takes ID instead of VALUE. More...
 
VALUE rb_struct_s_members (VALUE klass)
 Queries the list of the names of the fields of the given struct class. More...
 
VALUE rb_struct_members (VALUE self)
 Queries the list of the names of the fields of the class of the given struct object. More...
 
VALUE rb_struct_alloc_noinit (VALUE klass)
 Allocates an instance of the given class. More...
 
VALUE rb_struct_define_without_accessor (const char *name, VALUE super, rb_alloc_func_t func,...)
 Identical to rb_struct_define(), except it does not define accessor methods. More...
 
VALUE rb_struct_define_without_accessor_under (VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc,...)
 Identical to rb_struct_define_without_accessor(), except it defines the class under the specified namespace instead of global toplevel. More...
 
VALUE rb_data_define (VALUE super,...)
 Defines an anonymous data class. More...
 

Detailed Description

Public APIs related to rb_cStruct.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
Warning
Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.
Note
To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file struct.h.

Function Documentation

◆ rb_data_define()

VALUE rb_data_define ( VALUE  super,
  ... 
)

Defines an anonymous data class.

Parameters
[in]superSuperclass of the defining class. Must be a descendant of ::rb_cData, or 0 as ::rb_cData.
[in]...Arbitrary number of const char*, terminated by NULL. Each of which are the name of fields.
Exceptions
rb_eArgErrorDuplicated field name.
Returns
The defined class.
Note
The GC does not collect nor move classes returned by this function. They are immortal.

Definition at line 1699 of file struct.c.

◆ rb_struct_alloc()

VALUE rb_struct_alloc ( VALUE  klass,
VALUE  values 
)

Identical to rb_struct_new(), except it takes the field values as a Ruby array.

Parameters
[in]klassThe class of the instance to allocate.
[in]valuesField values.
Returns
Allocated instance of klass.
Precondition
klass must be a subclass of rb_cStruct.
values must be an instance of struct RArray.

Definition at line 836 of file struct.c.

◆ rb_struct_alloc_noinit()

VALUE rb_struct_alloc_noinit ( VALUE  klass)

Allocates an instance of the given class.

This consequential name is of course because rb_struct_alloc() not only allocates but also initialises an instance. The API design is broken.

Parameters
[in]klassA subclass of rb_cStruct.
Returns
An allocated instance of klass, not initialised.

Definition at line 405 of file struct.c.

◆ rb_struct_define()

VALUE rb_struct_define ( const char *  name,
  ... 
)

Defines a struct class.

Parameters
[in]nameName of the class.
[in]...Arbitrary number of const char*, terminated by NULL. Each of which are the name of fields.
Exceptions
rb_eNameErrorname is not a constant name.
rb_eTypeErrorname is already taken.
rb_eArgErrorDuplicated field name.
Returns
The defined class.
Postcondition
Global toplevel constant name is defined.
Note
name is allowed to be a null pointer. This function creates an anonymous struct class then.
The GC does not collect nor move classes returned by this function. They are immortal.

Definition at line 485 of file struct.c.

◆ rb_struct_define_under()

VALUE rb_struct_define_under ( VALUE  space,
const char *  name,
  ... 
)

Identical to rb_struct_define(), except it defines the class under the specified namespace instead of global toplevel.

Parameters
[out]spaceNamespace that the defining class shall reside.
[in]nameName of the class.
[in]...Arbitrary number of const char*, terminated by NULL. Each of which are the name of fields.
Exceptions
rb_eNameErrorname is not a constant name.
rb_eTypeErrorname is already taken.
rb_eArgErrorDuplicated field name.
Returns
The defined class.
Postcondition
name is a constant under space.
Note
In contrast to rb_struct_define(), it doesn't make any sense to pass a null pointer to this function.
The GC does not collect nor move classes returned by this function. They are immortal.

Definition at line 505 of file struct.c.

◆ rb_struct_define_without_accessor()

VALUE rb_struct_define_without_accessor ( const char *  name,
VALUE  super,
rb_alloc_func_t  func,
  ... 
)

Identical to rb_struct_define(), except it does not define accessor methods.

You have to define them yourself. Forget about the allocator function parameter; it is for internal use only. Extension libraries are unable to properly allocate a ruby struct, because RStruct is opaque.

Parameters
[in]nameName of the class.
[in]superSuperclass of the defining class.
[in]funcMust be 0 for extension libraries.
[in]...Arbitrary number of const char*, terminated by NULL. Each of which are the name of fields.
Exceptions
rb_eNameErrorname is not a constant name.
rb_eTypeErrorname is already taken.
rb_eArgErrorDuplicated field name.
Returns
The defined class.
Postcondition
Global toplevel constant name is defined.
Note
name is allowed to be a null pointer. This function creates an anonymous struct class then.

Definition at line 472 of file struct.c.

◆ rb_struct_define_without_accessor_under()

VALUE rb_struct_define_without_accessor_under ( VALUE  outer,
const char *  class_name,
VALUE  super,
rb_alloc_func_t  alloc,
  ... 
)

Identical to rb_struct_define_without_accessor(), except it defines the class under the specified namespace instead of global toplevel.

It can also be seen as a routine identical to rb_struct_define_under(), except it does not define accessor methods.

Parameters
[out]outerNamespace that the defining class shall reside.
[in]class_nameName of the class.
[in]superSuperclass of the defining class.
[in]allocMust be 0 for extension libraries.
[in]...Arbitrary number of const char*, terminated by NULL. Each of which are the name of fields.
Exceptions
rb_eNameErrorclass_name is not a constant name.
rb_eTypeErrorclass_name is already taken.
rb_eArgErrorDuplicated field name.
Returns
The defined class.
Postcondition
class_name is a constant under outer.
Note
In contrast to rb_struct_define_without_accessor(), it doesn't make any sense to pass a null name.
The GC does not collect nor move classes returned by this function. They are immortal.

Definition at line 459 of file struct.c.

◆ rb_struct_getmember()

VALUE rb_struct_getmember ( VALUE  self,
ID  key 
)

Identical to rb_struct_aref(), except it takes ID instead of VALUE.

Parameters
[in]selfAn instance of a struct class.
[in]keyKey to query.
Exceptions
rb_eTypeErrorself is not a struct.
rb_eNameErrorNo such field.
Returns
The value stored at key in self.

Definition at line 232 of file struct.c.

◆ rb_struct_initialize()

VALUE rb_struct_initialize ( VALUE  self,
VALUE  values 
)

Mass-assigns a struct's fields.

Parameters
[out]selfAn instance of a struct class to squash.
[in]valuesNew values.
Returns
RUBY_Qnil.

Definition at line 794 of file struct.c.

◆ rb_struct_members()

VALUE rb_struct_members ( VALUE  self)

Queries the list of the names of the fields of the class of the given struct object.

This is almost the same as calling rb_struct_s_members() over the class of the receiver.

Parameters
[in]selfAn instance of a subclass of rb_cStruct.
Returns
The list of the names of the fields.

Definition at line 81 of file struct.c.

◆ rb_struct_new()

VALUE rb_struct_new ( VALUE  klass,
  ... 
)

Creates an instance of the given struct.

Parameters
[in]klassThe class of the instance to allocate.
[in]...The fields.
Returns
Allocated instance of klass.
Precondition
klass must be a subclass of rb_cStruct.
Note
Number of variadic arguments must much that of the passed klass' fields.

Definition at line 842 of file struct.c.

◆ rb_struct_s_members()

VALUE rb_struct_s_members ( VALUE  klass)

Queries the list of the names of the fields of the given struct class.

Parameters
[in]klassA subclass of rb_cStruct.
Returns
The list of the names of the fields of klass.

Definition at line 67 of file struct.c.

Referenced by rb_struct_members().