(0989400a925cd201defdca9eb28eb87200b30785)

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

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_data_define()

VALUE rb_data_define	(	VALUE	super,
			...
	)

Defines an anonymous data class.

Parameters

[in]	super	Superclass 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_eArgError Duplicated 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]	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 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] klass A 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]	name	Name of the class.
[in]	...	Arbitrary number of `const char*`, terminated by NULL. 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.; 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]	space	Namespace that the defining class shall reside.
[in]	name	Name of the class.
[in]	...	Arbitrary number of `const char*`, terminated by NULL. 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.; 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]	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 NULL. 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 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]	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 NULL. 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.; 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]	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 232 of file struct.c.

◆ 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 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] self An 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]	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 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] klass A 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().

(0989400a925cd201defdca9eb28eb87200b30785)

Functions

Detailed Description

Function Documentation

◆ rb_data_define()

◆ rb_struct_alloc()

◆ rb_struct_alloc_noinit()

◆ rb_struct_define()

◆ rb_struct_define_under()

◆ rb_struct_define_without_accessor()

◆ rb_struct_define_without_accessor_under()

◆ rb_struct_getmember()

◆ rb_struct_initialize()

◆ rb_struct_members()

◆ rb_struct_new()

◆ rb_struct_s_members()