Ruby: include/ruby/internal/intern/struct.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Functions
struct.h File Reference

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"`

Go to the source code of this file.

## Functions
VALUE | rb_struct_new (VALUE klass,...)
| Creates an instance of the given struct.
VALUE | rb_struct_define (const char *name,...)
| Defines a struct class.
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.
VALUE | rb_struct_alloc (VALUE klass, VALUE values)
| Identical to rb_struct_new(), except it takes the field values as a Ruby array.
VALUE | rb_struct_initialize (VALUE self, VALUE values)
| Mass-assigns a struct's fields.
VALUE | rb_struct_getmember (VALUE self, ID key)
| Identical to rb_struct_aref(), except it takes ID instead of VALUE.
VALUE | rb_struct_s_members (VALUE klass)
| Queries the list of the names of the fields of the given struct class.
VALUE | rb_struct_members (VALUE self)
| Queries the list of the names of the fields of the class of the given struct object.
VALUE | rb_struct_alloc_noinit (VALUE klass)
| Allocates an instance of the given class.
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.
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.

## 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

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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_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] | klass | The class of the instance to allocate.
  [in] | values | Field 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 874 of file struct.c.

Referenced by rb_struct_alloc().

## ◆ 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] | klass | A subclass of rb_cStruct.

Returns
  An allocated instance of `klass`, not initialised.

Definition at line 406 of file struct.c.

Referenced by rb_struct_alloc_noinit().

## ◆ rb_struct_define()

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

Defines a struct class.

Parameters

  [in] | name | Name of the class.
  [in] | ... | Arbitrary number of `const char*`, terminated by zero. Each of which are the name of fields.

Exceptions

  rb_eNameError | `name` is not a constant name.
  rb_eTypeError | `name` is already taken.
  rb_eArgError | Duplicated 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 489 of file struct.c.

Referenced by rb_struct_define().

## ◆ 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] | space | Namespace that the defining class shall reside.
  [in] | name | Name of the class.
  [in] | ... | Arbitrary number of `const char*`, terminated by zero. Each of which are the name of fields.

Exceptions

  rb_eNameError | `name` is not a constant name.
  rb_eTypeError | `name` is already taken.
  rb_eArgError | Duplicated 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.

Definition at line 509 of file struct.c.

Referenced by rb_struct_define_under().

## ◆ 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] | name | Name of the class.
  [in] | super | Superclass of the defining class.
  [in] | func | Must be 0 for extension libraries.
  [in] | ... | Arbitrary number of `const char*`, terminated by zero. Each of which are the name of fields.

Exceptions

  rb_eNameError | `name` is not a constant name.
  rb_eTypeError | `name` is already taken.
  rb_eArgError | Duplicated 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 476 of file struct.c.

Referenced by rb_struct_define_without_accessor().

## ◆ 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] | outer | Namespace that the defining class shall reside.
  [in] | class_name | Name of the class.
  [in] | super | Superclass of the defining class.
  [in] | alloc | Must be 0 for extension libraries.
  [in] | ... | Arbitrary number of `const char*`, terminated by zero. Each of which are the name of fields.

Exceptions

  rb_eNameError | `class_name` is not a constant name.
  rb_eTypeError | `class_name` is already taken.
  rb_eArgError | Duplicated 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.

Definition at line 463 of file struct.c.

Referenced by rb_struct_define_without_accessor_under().

## ◆ 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] | self | An instance of a struct class.
  [in] | key | Key to query.

Exceptions

  rb_eTypeError | `self` is not a struct.
  rb_eNameError | No such field.

Returns
  The value stored at `key` in `self`.

Definition at line 233 of file struct.c.

Referenced by rb_struct_getmember().

## ◆ rb_struct_initialize()

VALUE rb_struct_initialize | ( | VALUE | self,
|  | VALUE | values )

Mass-assigns a struct's fields.

Parameters

  [out] | self | An instance of a struct class to squash.
  [in] | values | New values.

Returns
  RUBY_Qnil.

Definition at line 806 of file struct.c.

Referenced by rb_struct_initialize().

## ◆ 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] | self | An instance of a subclass of rb_cStruct.

Returns
  The list of the names of the fields.

Definition at line 82 of file struct.c.

Referenced by rb_struct_members().

## ◆ rb_struct_new()

VALUE rb_struct_new | ( | VALUE | klass,
|  |  | ... )

Creates an instance of the given struct.

Parameters

  [in] | klass | The 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 880 of file struct.c.

Referenced by rb_struct_new().

## ◆ 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] | klass | A subclass of rb_cStruct.

Returns
  The list of the names of the fields of `klass`.

Definition at line 68 of file struct.c.

Referenced by rb_struct_members(), and rb_struct_s_members().