Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)
struct.c
1/**********************************************************************
2
3 struct.c -
4
5 $Author$
6 created at: Tue Mar 22 18:44:30 JST 1995
7
8 Copyright (C) 1993-2007 Yukihiro Matsumoto
9
10**********************************************************************/
11
12#include "id.h"
13#include "internal.h"
14#include "internal/class.h"
15#include "internal/error.h"
16#include "internal/hash.h"
17#include "internal/object.h"
18#include "internal/proc.h"
19#include "internal/struct.h"
20#include "internal/symbol.h"
21#include "transient_heap.h"
22#include "vm_core.h"
23#include "builtin.h"
24
25/* only for struct[:field] access */
26enum {
27 AREF_HASH_UNIT = 5,
28 AREF_HASH_THRESHOLD = 10
29};
30
31/* Note: Data is a stricter version of the Struct: no attr writers & no
32 hash-alike/array-alike behavior. It shares most of the implementation
33 on the C level, but is unrelated on the Ruby level. */
35static VALUE rb_cData;
36static ID id_members, id_back_members, id_keyword_init;
37
38static VALUE struct_alloc(VALUE);
39
40static inline VALUE
41struct_ivar_get(VALUE c, ID id)
42{
43 VALUE orig = c;
44 VALUE ivar = rb_attr_get(c, id);
45
46 if (!NIL_P(ivar))
47 return ivar;
48
49 for (;;) {
51 if (c == rb_cStruct || c == rb_cData || !RTEST(c))
52 return Qnil;
54 ivar = rb_attr_get(c, id);
55 if (!NIL_P(ivar)) {
56 return rb_ivar_set(orig, id, ivar);
57 }
58 }
59}
60
62rb_struct_s_keyword_init(VALUE klass)
63{
64 return struct_ivar_get(klass, id_keyword_init);
65}
66
69{
70 VALUE members = struct_ivar_get(klass, id_members);
71
72 if (NIL_P(members)) {
73 rb_raise(rb_eTypeError, "uninitialized struct");
74 }
75 if (!RB_TYPE_P(members, T_ARRAY)) {
76 rb_raise(rb_eTypeError, "corrupted struct");
77 }
78 return members;
79}
80
83{
85
86 if (RSTRUCT_LEN(s) != RARRAY_LEN(members)) {
87 rb_raise(rb_eTypeError, "struct size differs (%ld required %ld given)",
88 RARRAY_LEN(members), RSTRUCT_LEN(s));
89 }
90 return members;
91}
92
93static long
94struct_member_pos_ideal(VALUE name, long mask)
95{
96 /* (id & (mask/2)) * 2 */
97 return (SYM2ID(name) >> (ID_SCOPE_SHIFT - 1)) & mask;
98}
99
100static long
101struct_member_pos_probe(long prev, long mask)
102{
103 /* (((prev/2) * AREF_HASH_UNIT + 1) & (mask/2)) * 2 */
104 return (prev * AREF_HASH_UNIT + 2) & mask;
105}
106
107static VALUE
108struct_set_members(VALUE klass, VALUE /* frozen hidden array */ members)
109{
110 VALUE back;
111 const long members_length = RARRAY_LEN(members);
112
113 if (members_length <= AREF_HASH_THRESHOLD) {
114 back = members;
115 }
116 else {
117 long i, j, mask = 64;
118 VALUE name;
119
120 while (mask < members_length * AREF_HASH_UNIT) mask *= 2;
121
122 back = rb_ary_hidden_new(mask + 1);
123 rb_ary_store(back, mask, INT2FIX(members_length));
124 mask -= 2; /* mask = (2**k-1)*2 */
125
126 for (i=0; i < members_length; i++) {
127 name = RARRAY_AREF(members, i);
128
129 j = struct_member_pos_ideal(name, mask);
130
131 for (;;) {
132 if (!RTEST(RARRAY_AREF(back, j))) {
133 rb_ary_store(back, j, name);
134 rb_ary_store(back, j + 1, INT2FIX(i));
135 break;
136 }
137 j = struct_member_pos_probe(j, mask);
138 }
139 }
140 OBJ_FREEZE_RAW(back);
141 }
142 rb_ivar_set(klass, id_members, members);
143 rb_ivar_set(klass, id_back_members, back);
144
145 return members;
146}
147
148static inline int
149struct_member_pos(VALUE s, VALUE name)
150{
151 VALUE back = struct_ivar_get(rb_obj_class(s), id_back_members);
152 long j, mask;
153
154 if (UNLIKELY(NIL_P(back))) {
155 rb_raise(rb_eTypeError, "uninitialized struct");
156 }
157 if (UNLIKELY(!RB_TYPE_P(back, T_ARRAY))) {
158 rb_raise(rb_eTypeError, "corrupted struct");
159 }
160
161 mask = RARRAY_LEN(back);
162
163 if (mask <= AREF_HASH_THRESHOLD) {
164 if (UNLIKELY(RSTRUCT_LEN(s) != mask)) {
166 "struct size differs (%ld required %ld given)",
167 mask, RSTRUCT_LEN(s));
168 }
169 for (j = 0; j < mask; j++) {
170 if (RARRAY_AREF(back, j) == name)
171 return (int)j;
172 }
173 return -1;
174 }
175
176 if (UNLIKELY(RSTRUCT_LEN(s) != FIX2INT(RARRAY_AREF(back, mask-1)))) {
177 rb_raise(rb_eTypeError, "struct size differs (%d required %ld given)",
178 FIX2INT(RARRAY_AREF(back, mask-1)), RSTRUCT_LEN(s));
179 }
180
181 mask -= 3;
182 j = struct_member_pos_ideal(name, mask);
183
184 for (;;) {
185 VALUE e = RARRAY_AREF(back, j);
186 if (e == name)
187 return FIX2INT(RARRAY_AREF(back, j + 1));
188 if (!RTEST(e)) {
189 return -1;
190 }
191 j = struct_member_pos_probe(j, mask);
192 }
193}
194
195/*
196 * call-seq:
197 * StructClass::members -> array_of_symbols
198 *
199 * Returns the member names of the Struct descendant as an array:
200 *
201 * Customer = Struct.new(:name, :address, :zip)
202 * Customer.members # => [:name, :address, :zip]
203 *
204 */
205
206static VALUE
207rb_struct_s_members_m(VALUE klass)
208{
209 VALUE members = rb_struct_s_members(klass);
210
211 return rb_ary_dup(members);
212}
213
214/*
215 * call-seq:
216 * members -> array_of_symbols
217 *
218 * Returns the member names from +self+ as an array:
219 *
220 * Customer = Struct.new(:name, :address, :zip)
221 * Customer.new.members # => [:name, :address, :zip]
222 *
223 * Related: #to_a.
224 */
225
226static VALUE
227rb_struct_members_m(VALUE obj)
228{
229 return rb_struct_s_members_m(rb_obj_class(obj));
230}
231
232VALUE
234{
235 VALUE slot = ID2SYM(id);
236 int i = struct_member_pos(obj, slot);
237 if (i != -1) {
238 return RSTRUCT_GET(obj, i);
239 }
240 rb_name_err_raise("`%1$s' is not a struct member", obj, ID2SYM(id));
241
243}
244
245static void
246rb_struct_modify(VALUE s)
247{
249}
250
251static VALUE
252anonymous_struct(VALUE klass)
253{
254 VALUE nstr;
255
256 nstr = rb_class_new(klass);
257 rb_make_metaclass(nstr, RBASIC(klass)->klass);
258 rb_class_inherited(klass, nstr);
259 return nstr;
260}
261
262static VALUE
263new_struct(VALUE name, VALUE super)
264{
265 /* old style: should we warn? */
266 ID id;
267 name = rb_str_to_str(name);
268 if (!rb_is_const_name(name)) {
269 rb_name_err_raise("identifier %1$s needs to be constant",
270 super, name);
271 }
272 id = rb_to_id(name);
273 if (rb_const_defined_at(super, id)) {
274 rb_warn("redefining constant %"PRIsVALUE"::%"PRIsVALUE, super, name);
275 rb_mod_remove_const(super, ID2SYM(id));
276 }
277 return rb_define_class_id_under_no_pin(super, id, super);
278}
279
280NORETURN(static void invalid_struct_pos(VALUE s, VALUE idx));
281
282static void
283define_aref_method(VALUE nstr, VALUE name, VALUE off)
284{
285 rb_add_method_optimized(nstr, SYM2ID(name), OPTIMIZED_METHOD_TYPE_STRUCT_AREF, FIX2UINT(off), METHOD_VISI_PUBLIC);
286}
287
288static void
289define_aset_method(VALUE nstr, VALUE name, VALUE off)
290{
291 rb_add_method_optimized(nstr, SYM2ID(name), OPTIMIZED_METHOD_TYPE_STRUCT_ASET, FIX2UINT(off), METHOD_VISI_PUBLIC);
292}
293
294static VALUE
295rb_struct_s_inspect(VALUE klass)
296{
297 VALUE inspect = rb_class_name(klass);
298 if (RTEST(rb_struct_s_keyword_init(klass))) {
299 rb_str_cat_cstr(inspect, "(keyword_init: true)");
300 }
301 return inspect;
302}
303
304static VALUE
305rb_data_s_new(int argc, const VALUE *argv, VALUE klass)
306{
307 if (rb_keyword_given_p()) {
308 if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) {
309 rb_error_arity(argc, 0, 0);
310 }
311 return rb_class_new_instance_pass_kw(argc, argv, klass);
312 }
313 else {
314 VALUE members = struct_ivar_get(klass, id_members);
315 int num_members = RARRAY_LENINT(members);
316
317 rb_check_arity(argc, 0, num_members);
318 VALUE arg_hash = rb_hash_new_with_size(argc);
319 for (long i=0; i<argc; i++) {
320 VALUE k = rb_ary_entry(members, i), v = argv[i];
321 rb_hash_aset(arg_hash, k, v);
322 }
323 return rb_class_new_instance_kw(1, &arg_hash, klass, RB_PASS_KEYWORDS);
324 }
325}
326
327#if 0 /* for RDoc */
328
329/*
330 * call-seq:
331 * StructClass::keyword_init? -> true or falsy value
332 *
333 * Returns +true+ if the class was initialized with <tt>keyword_init: true</tt>.
334 * Otherwise returns +nil+ or +false+.
335 *
336 * Examples:
337 * Foo = Struct.new(:a)
338 * Foo.keyword_init? # => nil
339 * Bar = Struct.new(:a, keyword_init: true)
340 * Bar.keyword_init? # => true
341 * Baz = Struct.new(:a, keyword_init: false)
342 * Baz.keyword_init? # => false
343 */
344static VALUE
345rb_struct_s_keyword_init_p(VALUE obj)
346{
347}
348#endif
349
350#define rb_struct_s_keyword_init_p rb_struct_s_keyword_init
351
352static VALUE
353setup_struct(VALUE nstr, VALUE members)
354{
355 long i, len;
356
357 members = struct_set_members(nstr, members);
358
359 rb_define_alloc_func(nstr, struct_alloc);
362 rb_define_singleton_method(nstr, "members", rb_struct_s_members_m, 0);
363 rb_define_singleton_method(nstr, "inspect", rb_struct_s_inspect, 0);
364 rb_define_singleton_method(nstr, "keyword_init?", rb_struct_s_keyword_init_p, 0);
365
366 len = RARRAY_LEN(members);
367 for (i=0; i< len; i++) {
368 VALUE sym = RARRAY_AREF(members, i);
369 ID id = SYM2ID(sym);
370 VALUE off = LONG2NUM(i);
371
372 define_aref_method(nstr, sym, off);
373 define_aset_method(nstr, ID2SYM(rb_id_attrset(id)), off);
374 }
375
376 return nstr;
377}
378
379static VALUE
380setup_data(VALUE subclass, VALUE members)
381{
382 long i, len;
383
384 members = struct_set_members(subclass, members);
385
386 rb_define_alloc_func(subclass, struct_alloc);
387 VALUE sclass = rb_singleton_class(subclass);
388 rb_undef_method(sclass, "define");
389 rb_define_method(sclass, "new", rb_data_s_new, -1);
390 rb_define_method(sclass, "[]", rb_data_s_new, -1);
391 rb_define_method(sclass, "members", rb_struct_s_members_m, 0);
392 rb_define_method(sclass, "inspect", rb_struct_s_inspect, 0); // FIXME: just a separate method?..
393
394 len = RARRAY_LEN(members);
395 for (i=0; i< len; i++) {
396 VALUE sym = RARRAY_AREF(members, i);
397 VALUE off = LONG2NUM(i);
398
399 define_aref_method(subclass, sym, off);
400 }
401
402 return subclass;
403}
404
405VALUE
407{
408 return struct_alloc(klass);
409}
410
411static VALUE
412struct_make_members_list(va_list ar)
413{
414 char *mem;
415 VALUE ary, list = rb_ident_hash_new();
416 st_table *tbl = RHASH_TBL_RAW(list);
417
418 RBASIC_CLEAR_CLASS(list);
419 OBJ_WB_UNPROTECT(list);
420 while ((mem = va_arg(ar, char*)) != 0) {
421 VALUE sym = rb_sym_intern_ascii_cstr(mem);
422 if (st_insert(tbl, sym, Qtrue)) {
423 rb_raise(rb_eArgError, "duplicate member: %s", mem);
424 }
425 }
426 ary = rb_hash_keys(list);
427 st_clear(tbl);
428 RBASIC_CLEAR_CLASS(ary);
429 OBJ_FREEZE_RAW(ary);
430 return ary;
431}
432
433static VALUE
434struct_define_without_accessor(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, VALUE members)
435{
436 VALUE klass;
437
438 if (class_name) {
439 if (outer) {
440 klass = rb_define_class_under(outer, class_name, super);
441 }
442 else {
443 klass = rb_define_class(class_name, super);
444 }
445 }
446 else {
447 klass = anonymous_struct(super);
448 }
449
450 struct_set_members(klass, members);
451
452 if (alloc) {
453 rb_define_alloc_func(klass, alloc);
454 }
455 else {
456 rb_define_alloc_func(klass, struct_alloc);
457 }
458
459 return klass;
460}
461
462VALUE
463rb_struct_define_without_accessor_under(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, ...)
464{
465 va_list ar;
466 VALUE members;
467
468 va_start(ar, alloc);
469 members = struct_make_members_list(ar);
470 va_end(ar);
471
472 return struct_define_without_accessor(outer, class_name, super, alloc, members);
473}
474
475VALUE
476rb_struct_define_without_accessor(const char *class_name, VALUE super, rb_alloc_func_t alloc, ...)
477{
478 va_list ar;
479 VALUE members;
480
481 va_start(ar, alloc);
482 members = struct_make_members_list(ar);
483 va_end(ar);
484
485 return struct_define_without_accessor(0, class_name, super, alloc, members);
486}
487
488VALUE
489rb_struct_define(const char *name, ...)
490{
491 va_list ar;
492 VALUE st, ary;
493
494 va_start(ar, name);
495 ary = struct_make_members_list(ar);
496 va_end(ar);
497
498 if (!name) {
499 st = anonymous_struct(rb_cStruct);
500 }
501 else {
502 st = new_struct(rb_str_new2(name), rb_cStruct);
503 rb_vm_add_root_module(st);
504 }
505 return setup_struct(st, ary);
506}
507
508VALUE
509rb_struct_define_under(VALUE outer, const char *name, ...)
510{
511 va_list ar;
512 VALUE ary;
513
514 va_start(ar, name);
515 ary = struct_make_members_list(ar);
516 va_end(ar);
517
518 return setup_struct(rb_define_class_id_under(outer, rb_intern(name), rb_cStruct), ary);
519}
520
521/*
522 * call-seq:
523 * Struct.new(*member_names, keyword_init: false){|Struct_subclass| ... } -> Struct_subclass
524 * Struct.new(class_name, *member_names, keyword_init: false){|Struct_subclass| ... } -> Struct_subclass
525 * Struct_subclass.new(*member_names) -> Struct_subclass_instance
526 * Struct_subclass.new(**member_names) -> Struct_subclass_instance
527 *
528 * <tt>Struct.new</tt> returns a new subclass of +Struct+. The new subclass:
529 *
530 * - May be anonymous, or may have the name given by +class_name+.
531 * - May have members as given by +member_names+.
532 * - May have initialization via ordinary arguments, or via keyword arguments
533 *
534 * The new subclass has its own method <tt>::new</tt>; thus:
535 *
536 * Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
537 * f = Foo.new(0, 1) # => #<struct Struct::Foo foo=0, bar=1>
538 *
539 * <b>\Class Name</b>
540 *
541 * With string argument +class_name+,
542 * returns a new subclass of +Struct+ named <tt>Struct::<em>class_name</em></tt>:
543 *
544 * Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
545 * Foo.name # => "Struct::Foo"
546 * Foo.superclass # => Struct
547 *
548 * Without string argument +class_name+,
549 * returns a new anonymous subclass of +Struct+:
550 *
551 * Struct.new(:foo, :bar).name # => nil
552 *
553 * <b>Block</b>
554 *
555 * With a block given, the created subclass is yielded to the block:
556 *
557 * Customer = Struct.new('Customer', :name, :address) do |new_class|
558 * p "The new subclass is #{new_class}"
559 * def greeting
560 * "Hello #{name} at #{address}"
561 * end
562 * end # => Struct::Customer
563 * dave = Customer.new('Dave', '123 Main')
564 * dave # => #<struct Struct::Customer name="Dave", address="123 Main">
565 * dave.greeting # => "Hello Dave at 123 Main"
566 *
567 * Output, from <tt>Struct.new</tt>:
568 *
569 * "The new subclass is Struct::Customer"
570 *
571 * <b>Member Names</b>
572 *
573 * \Symbol arguments +member_names+
574 * determines the members of the new subclass:
575 *
576 * Struct.new(:foo, :bar).members # => [:foo, :bar]
577 * Struct.new('Foo', :foo, :bar).members # => [:foo, :bar]
578 *
579 * The new subclass has instance methods corresponding to +member_names+:
580 *
581 * Foo = Struct.new('Foo', :foo, :bar)
582 * Foo.instance_methods(false) # => [:foo, :bar, :foo=, :bar=]
583 * f = Foo.new # => #<struct Struct::Foo foo=nil, bar=nil>
584 * f.foo # => nil
585 * f.foo = 0 # => 0
586 * f.bar # => nil
587 * f.bar = 1 # => 1
588 * f # => #<struct Struct::Foo foo=0, bar=1>
589 *
590 * <b>Singleton Methods</b>
591 *
592 * A subclass returned by Struct.new has these singleton methods:
593 *
594 * - \Method <tt>::new </tt> creates an instance of the subclass:
595 *
596 * Foo.new # => #<struct Struct::Foo foo=nil, bar=nil>
597 * Foo.new(0) # => #<struct Struct::Foo foo=0, bar=nil>
598 * Foo.new(0, 1) # => #<struct Struct::Foo foo=0, bar=1>
599 * Foo.new(0, 1, 2) # Raises ArgumentError: struct size differs
600 *
601 * # Initialization with keyword arguments:
602 * Foo.new(foo: 0) # => #<struct Struct::Foo foo=0, bar=nil>
603 * Foo.new(foo: 0, bar: 1) # => #<struct Struct::Foo foo=0, bar=1>
604 * Foo.new(foo: 0, bar: 1, baz: 2)
605 * # Raises ArgumentError: unknown keywords: baz
606 *
607 * \Method <tt>::[]</tt> is an alias for method <tt>::new</tt>.
608 *
609 * - \Method <tt>:inspect</tt> returns a string representation of the subclass:
610 *
611 * Foo.inspect
612 * # => "Struct::Foo"
613 *
614 * - \Method <tt>::members</tt> returns an array of the member names:
615 *
616 * Foo.members # => [:foo, :bar]
617 *
618 * <b>Keyword Argument</b>
619 *
620 * By default, the arguments for initializing an instance of the new subclass
621 * can be both positional and keyword arguments.
622 *
623 * Optional keyword argument <tt>keyword_init:</tt> allows to force only one
624 * type of arguments to be accepted:
625 *
626 * KeywordsOnly = Struct.new(:foo, :bar, keyword_init: true)
627 * KeywordsOnly.new(bar: 1, foo: 0)
628 * # => #<struct KeywordsOnly foo=0, bar=1>
629 * KeywordsOnly.new(0, 1)
630 * # Raises ArgumentError: wrong number of arguments
631 *
632 * PositionalOnly = Struct.new(:foo, :bar, keyword_init: false)
633 * PositionalOnly.new(0, 1)
634 * # => #<struct PositionalOnly foo=0, bar=1>
635 * PositionalOnly.new(bar: 1, foo: 0)
636 * # => #<struct PositionalOnly foo={:foo=>1, :bar=>2}, bar=nil>
637 * # Note that no error is raised, but arguments treated as one hash value
638 *
639 * # Same as not providing keyword_init:
640 * Any = Struct.new(:foo, :bar, keyword_init: nil)
641 * Any.new(foo: 1, bar: 2)
642 * # => #<struct Any foo=1, bar=2>
643 * Any.new(1, 2)
644 * # => #<struct Any foo=1, bar=2>
645 */
646
647static VALUE
648rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
649{
650 VALUE name, rest, keyword_init = Qnil;
651 long i;
652 VALUE st;
653 st_table *tbl;
654 VALUE opt;
655
656 argc = rb_scan_args(argc, argv, "1*:", NULL, NULL, &opt);
657 name = argv[0];
658 if (SYMBOL_P(name)) {
659 name = Qnil;
660 }
661 else {
662 --argc;
663 ++argv;
664 }
665
666 if (!NIL_P(opt)) {
667 static ID keyword_ids[1];
668
669 if (!keyword_ids[0]) {
670 keyword_ids[0] = rb_intern("keyword_init");
671 }
672 rb_get_kwargs(opt, keyword_ids, 0, 1, &keyword_init);
673 if (UNDEF_P(keyword_init)) {
674 keyword_init = Qnil;
675 }
676 else if (RTEST(keyword_init)) {
677 keyword_init = Qtrue;
678 }
679 }
680
681 rest = rb_ident_hash_new();
682 RBASIC_CLEAR_CLASS(rest);
683 OBJ_WB_UNPROTECT(rest);
684 tbl = RHASH_TBL_RAW(rest);
685 for (i=0; i<argc; i++) {
686 VALUE mem = rb_to_symbol(argv[i]);
687 if (rb_is_attrset_sym(mem)) {
688 rb_raise(rb_eArgError, "invalid struct member: %"PRIsVALUE, mem);
689 }
690 if (st_insert(tbl, mem, Qtrue)) {
691 rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem);
692 }
693 }
694 rest = rb_hash_keys(rest);
695 st_clear(tbl);
696 RBASIC_CLEAR_CLASS(rest);
697 OBJ_FREEZE_RAW(rest);
698 if (NIL_P(name)) {
699 st = anonymous_struct(klass);
700 }
701 else {
702 st = new_struct(name, klass);
703 }
704 setup_struct(st, rest);
705 rb_ivar_set(st, id_keyword_init, keyword_init);
706 if (rb_block_given_p()) {
707 rb_mod_module_eval(0, 0, st);
708 }
709
710 return st;
711}
712
713static long
714num_members(VALUE klass)
715{
716 VALUE members;
717 members = struct_ivar_get(klass, id_members);
718 if (!RB_TYPE_P(members, T_ARRAY)) {
719 rb_raise(rb_eTypeError, "broken members");
720 }
721 return RARRAY_LEN(members);
722}
723
724/*
725 */
726
728 VALUE self;
729 VALUE unknown_keywords;
730};
731
732static int rb_struct_pos(VALUE s, VALUE *name);
733
734static int
735struct_hash_set_i(VALUE key, VALUE val, VALUE arg)
736{
737 struct struct_hash_set_arg *args = (struct struct_hash_set_arg *)arg;
738 int i = rb_struct_pos(args->self, &key);
739 if (i < 0) {
740 if (NIL_P(args->unknown_keywords)) {
741 args->unknown_keywords = rb_ary_new();
742 }
743 rb_ary_push(args->unknown_keywords, key);
744 }
745 else {
746 rb_struct_modify(args->self);
747 RSTRUCT_SET(args->self, i, val);
748 }
749 return ST_CONTINUE;
750}
751
752static VALUE
753rb_struct_initialize_m(int argc, const VALUE *argv, VALUE self)
754{
755 VALUE klass = rb_obj_class(self);
756 rb_struct_modify(self);
757 long n = num_members(klass);
758 if (argc == 0) {
759 rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), n);
760 return Qnil;
761 }
762
763 bool keyword_init = false;
764 switch (rb_struct_s_keyword_init(klass)) {
765 default:
766 if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) {
767 rb_error_arity(argc, 0, 0);
768 }
769 keyword_init = true;
770 break;
771 case Qfalse:
772 break;
773 case Qnil:
774 if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) {
775 break;
776 }
777 keyword_init = rb_keyword_given_p();
778 break;
779 }
780 if (keyword_init) {
781 struct struct_hash_set_arg arg;
782 rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), n);
783 arg.self = self;
784 arg.unknown_keywords = Qnil;
785 rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg);
786 if (arg.unknown_keywords != Qnil) {
787 rb_raise(rb_eArgError, "unknown keywords: %s",
788 RSTRING_PTR(rb_ary_join(arg.unknown_keywords, rb_str_new2(", "))));
789 }
790 }
791 else {
792 if (n < argc) {
793 rb_raise(rb_eArgError, "struct size differs");
794 }
795 for (long i=0; i<argc; i++) {
796 RSTRUCT_SET(self, i, argv[i]);
797 }
798 if (n > argc) {
799 rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self)+argc, n-argc);
800 }
801 }
802 return Qnil;
803}
804
805VALUE
807{
808 rb_struct_initialize_m(RARRAY_LENINT(values), RARRAY_CONST_PTR(values), self);
809 if (rb_obj_is_kind_of(self, rb_cData)) OBJ_FREEZE_RAW(self);
810 RB_GC_GUARD(values);
811 return Qnil;
812}
813
814static VALUE *
815struct_heap_alloc(VALUE st, size_t len)
816{
817 VALUE *ptr = rb_transient_heap_alloc((VALUE)st, sizeof(VALUE) * len);
818
819 if (ptr) {
820 RSTRUCT_TRANSIENT_SET(st);
821 return ptr;
822 }
823 else {
824 RSTRUCT_TRANSIENT_UNSET(st);
825 return ALLOC_N(VALUE, len);
826 }
827}
828
829#if USE_TRANSIENT_HEAP
830void
831rb_struct_transient_heap_evacuate(VALUE obj, int promote)
832{
833 if (RSTRUCT_TRANSIENT_P(obj)) {
834 const VALUE *old_ptr = rb_struct_const_heap_ptr(obj);
835 VALUE *new_ptr;
836 long len = RSTRUCT_LEN(obj);
837
838 if (promote) {
839 new_ptr = ALLOC_N(VALUE, len);
840 FL_UNSET_RAW(obj, RSTRUCT_TRANSIENT_FLAG);
841 }
842 else {
843 new_ptr = struct_heap_alloc(obj, len);
844 }
845 MEMCPY(new_ptr, old_ptr, VALUE, len);
846 RSTRUCT(obj)->as.heap.ptr = new_ptr;
847 }
848}
849#endif
850
851static VALUE
852struct_alloc(VALUE klass)
853{
854 long n;
856
857 n = num_members(klass);
858
859 if (0 < n && n <= RSTRUCT_EMBED_LEN_MAX) {
860 RBASIC(st)->flags &= ~RSTRUCT_EMBED_LEN_MASK;
861 RBASIC(st)->flags |= n << RSTRUCT_EMBED_LEN_SHIFT;
862 rb_mem_clear((VALUE *)st->as.ary, n);
863 }
864 else {
865 st->as.heap.ptr = struct_heap_alloc((VALUE)st, n);
866 rb_mem_clear((VALUE *)st->as.heap.ptr, n);
867 st->as.heap.len = n;
868 }
869
870 return (VALUE)st;
871}
872
873VALUE
875{
876 return rb_class_new_instance(RARRAY_LENINT(values), RARRAY_CONST_PTR(values), klass);
877}
878
879VALUE
881{
882 VALUE tmpargs[16], *mem = tmpargs;
883 int size, i;
884 va_list args;
885
886 size = rb_long2int(num_members(klass));
887 if (size > numberof(tmpargs)) {
888 tmpargs[0] = rb_ary_hidden_new(size);
889 mem = RARRAY_PTR(tmpargs[0]);
890 }
891 va_start(args, klass);
892 for (i=0; i<size; i++) {
893 mem[i] = va_arg(args, VALUE);
894 }
895 va_end(args);
896
897 return rb_class_new_instance(size, mem, klass);
898}
899
900static VALUE
901struct_enum_size(VALUE s, VALUE args, VALUE eobj)
902{
903 return rb_struct_size(s);
904}
905
906/*
907 * call-seq:
908 * each {|value| ... } -> self
909 * each -> enumerator
910 *
911 * Calls the given block with the value of each member; returns +self+:
912 *
913 * Customer = Struct.new(:name, :address, :zip)
914 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
915 * joe.each {|value| p value }
916 *
917 * Output:
918 *
919 * "Joe Smith"
920 * "123 Maple, Anytown NC"
921 * 12345
922 *
923 * Returns an Enumerator if no block is given.
924 *
925 * Related: #each_pair.
926 */
927
928static VALUE
929rb_struct_each(VALUE s)
930{
931 long i;
932
933 RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
934 for (i=0; i<RSTRUCT_LEN(s); i++) {
935 rb_yield(RSTRUCT_GET(s, i));
936 }
937 return s;
938}
939
940/*
941 * call-seq:
942 * each_pair {|(name, value)| ... } -> self
943 * each_pair -> enumerator
944 *
945 * Calls the given block with each member name/value pair; returns +self+:
946 *
947 * Customer = Struct.new(:name, :address, :zip) # => Customer
948 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
949 * joe.each_pair {|(name, value)| p "#{name} => #{value}" }
950 *
951 * Output:
952 *
953 * "name => Joe Smith"
954 * "address => 123 Maple, Anytown NC"
955 * "zip => 12345"
956 *
957 * Returns an Enumerator if no block is given.
958 *
959 * Related: #each.
960 *
961 */
962
963static VALUE
964rb_struct_each_pair(VALUE s)
965{
966 VALUE members;
967 long i;
968
969 RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
970 members = rb_struct_members(s);
971 if (rb_block_pair_yield_optimizable()) {
972 for (i=0; i<RSTRUCT_LEN(s); i++) {
973 VALUE key = rb_ary_entry(members, i);
974 VALUE value = RSTRUCT_GET(s, i);
975 rb_yield_values(2, key, value);
976 }
977 }
978 else {
979 for (i=0; i<RSTRUCT_LEN(s); i++) {
980 VALUE key = rb_ary_entry(members, i);
981 VALUE value = RSTRUCT_GET(s, i);
982 rb_yield(rb_assoc_new(key, value));
983 }
984 }
985 return s;
986}
987
988static VALUE
989inspect_struct(VALUE s, VALUE prefix, int recur)
990{
991 VALUE cname = rb_class_path(rb_obj_class(s));
992 VALUE members;
993 VALUE str = prefix;
994 long i, len;
995 char first = RSTRING_PTR(cname)[0];
996
997 if (recur || first != '#') {
998 rb_str_append(str, cname);
999 }
1000 if (recur) {
1001 return rb_str_cat2(str, ":...>");
1002 }
1003
1004 members = rb_struct_members(s);
1005 len = RSTRUCT_LEN(s);
1006
1007 for (i=0; i<len; i++) {
1008 VALUE slot;
1009 ID id;
1010
1011 if (i > 0) {
1012 rb_str_cat2(str, ", ");
1013 }
1014 else if (first != '#') {
1015 rb_str_cat2(str, " ");
1016 }
1017 slot = RARRAY_AREF(members, i);
1018 id = SYM2ID(slot);
1019 if (rb_is_local_id(id) || rb_is_const_id(id)) {
1020 rb_str_append(str, rb_id2str(id));
1021 }
1022 else {
1023 rb_str_append(str, rb_inspect(slot));
1024 }
1025 rb_str_cat2(str, "=");
1026 rb_str_append(str, rb_inspect(RSTRUCT_GET(s, i)));
1027 }
1028 rb_str_cat2(str, ">");
1029
1030 return str;
1031}
1032
1033/*
1034 * call-seq:
1035 * inspect -> string
1036 *
1037 * Returns a string representation of +self+:
1038 *
1039 * Customer = Struct.new(:name, :address, :zip) # => Customer
1040 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1041 * joe.inspect # => "#<struct Customer name=\"Joe Smith\", address=\"123 Maple, Anytown NC\", zip=12345>"
1042 *
1043 * Struct#to_s is an alias for Struct#inspect.
1044 *
1045 */
1046
1047static VALUE
1048rb_struct_inspect(VALUE s)
1049{
1050 return rb_exec_recursive(inspect_struct, s, rb_str_new2("#<struct "));
1051}
1052
1053/*
1054 * call-seq:
1055 * to_a -> array
1056 *
1057 * Returns the values in +self+ as an array:
1058 *
1059 * Customer = Struct.new(:name, :address, :zip)
1060 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1061 * joe.to_a # => ["Joe Smith", "123 Maple, Anytown NC", 12345]
1062 *
1063 * Struct#values and Struct#deconstruct are aliases for Struct#to_a.
1064 *
1065 * Related: #members.
1066 */
1067
1068static VALUE
1069rb_struct_to_a(VALUE s)
1070{
1071 return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
1072}
1073
1074/*
1075 * call-seq:
1076 * to_h -> hash
1077 * to_h {|name, value| ... } -> hash
1078 *
1079 * Returns a hash containing the name and value for each member:
1080 *
1081 * Customer = Struct.new(:name, :address, :zip)
1082 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1083 * h = joe.to_h
1084 * h # => {:name=>"Joe Smith", :address=>"123 Maple, Anytown NC", :zip=>12345}
1085 *
1086 * If a block is given, it is called with each name/value pair;
1087 * the block should return a 2-element array whose elements will become
1088 * a key/value pair in the returned hash:
1089 *
1090 * h = joe.to_h{|name, value| [name.upcase, value.to_s.upcase]}
1091 * h # => {:NAME=>"JOE SMITH", :ADDRESS=>"123 MAPLE, ANYTOWN NC", :ZIP=>"12345"}
1092 *
1093 * Raises ArgumentError if the block returns an inappropriate value.
1094 *
1095 */
1096
1097static VALUE
1098rb_struct_to_h(VALUE s)
1099{
1100 VALUE h = rb_hash_new_with_size(RSTRUCT_LEN(s));
1101 VALUE members = rb_struct_members(s);
1102 long i;
1103 int block_given = rb_block_given_p();
1104
1105 for (i=0; i<RSTRUCT_LEN(s); i++) {
1106 VALUE k = rb_ary_entry(members, i), v = RSTRUCT_GET(s, i);
1107 if (block_given)
1108 rb_hash_set_pair(h, rb_yield_values(2, k, v));
1109 else
1110 rb_hash_aset(h, k, v);
1111 }
1112 return h;
1113}
1114
1115/*
1116 * call-seq:
1117 * deconstruct_keys(array_of_names) -> hash
1118 *
1119 * Returns a hash of the name/value pairs for the given member names.
1120 *
1121 * Customer = Struct.new(:name, :address, :zip)
1122 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1123 * h = joe.deconstruct_keys([:zip, :address])
1124 * h # => {:zip=>12345, :address=>"123 Maple, Anytown NC"}
1125 *
1126 * Returns all names and values if +array_of_names+ is +nil+:
1127 *
1128 * h = joe.deconstruct_keys(nil)
1129 * h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
1130 *
1131 */
1132static VALUE
1133rb_struct_deconstruct_keys(VALUE s, VALUE keys)
1134{
1135 VALUE h;
1136 long i;
1137
1138 if (NIL_P(keys)) {
1139 return rb_struct_to_h(s);
1140 }
1141 if (UNLIKELY(!RB_TYPE_P(keys, T_ARRAY))) {
1143 "wrong argument type %"PRIsVALUE" (expected Array or nil)",
1144 rb_obj_class(keys));
1145
1146 }
1147 if (RSTRUCT_LEN(s) < RARRAY_LEN(keys)) {
1148 return rb_hash_new_with_size(0);
1149 }
1150 h = rb_hash_new_with_size(RARRAY_LEN(keys));
1151 for (i=0; i<RARRAY_LEN(keys); i++) {
1152 VALUE key = RARRAY_AREF(keys, i);
1153 int i = rb_struct_pos(s, &key);
1154 if (i < 0) {
1155 return h;
1156 }
1157 rb_hash_aset(h, key, RSTRUCT_GET(s, i));
1158 }
1159 return h;
1160}
1161
1162/* :nodoc: */
1163VALUE
1164rb_struct_init_copy(VALUE copy, VALUE s)
1165{
1166 long i, len;
1167
1168 if (!OBJ_INIT_COPY(copy, s)) return copy;
1169 if (RSTRUCT_LEN(copy) != RSTRUCT_LEN(s)) {
1170 rb_raise(rb_eTypeError, "struct size mismatch");
1171 }
1172
1173 for (i=0, len=RSTRUCT_LEN(copy); i<len; i++) {
1174 RSTRUCT_SET(copy, i, RSTRUCT_GET(s, i));
1175 }
1176
1177 return copy;
1178}
1179
1180static int
1181rb_struct_pos(VALUE s, VALUE *name)
1182{
1183 long i;
1184 VALUE idx = *name;
1185
1186 if (SYMBOL_P(idx)) {
1187 return struct_member_pos(s, idx);
1188 }
1189 else if (RB_TYPE_P(idx, T_STRING)) {
1190 idx = rb_check_symbol(name);
1191 if (NIL_P(idx)) return -1;
1192 return struct_member_pos(s, idx);
1193 }
1194 else {
1195 long len;
1196 i = NUM2LONG(idx);
1197 len = RSTRUCT_LEN(s);
1198 if (i < 0) {
1199 if (i + len < 0) {
1200 *name = LONG2FIX(i);
1201 return -1;
1202 }
1203 i += len;
1204 }
1205 else if (len <= i) {
1206 *name = LONG2FIX(i);
1207 return -1;
1208 }
1209 return (int)i;
1210 }
1211}
1212
1213static void
1214invalid_struct_pos(VALUE s, VALUE idx)
1215{
1216 if (FIXNUM_P(idx)) {
1217 long i = FIX2INT(idx), len = RSTRUCT_LEN(s);
1218 if (i < 0) {
1219 rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)",
1220 i, len);
1221 }
1222 else {
1223 rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)",
1224 i, len);
1225 }
1226 }
1227 else {
1228 rb_name_err_raise("no member '%1$s' in struct", s, idx);
1229 }
1230}
1231
1232/*
1233 * call-seq:
1234 * struct[name] -> object
1235 * struct[n] -> object
1236 *
1237 * Returns a value from +self+.
1238 *
1239 * With symbol or string argument +name+ given, returns the value for the named member:
1240 *
1241 * Customer = Struct.new(:name, :address, :zip)
1242 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1243 * joe[:zip] # => 12345
1244 *
1245 * Raises NameError if +name+ is not the name of a member.
1246 *
1247 * With integer argument +n+ given, returns <tt>self.values[n]</tt>
1248 * if +n+ is in range;
1249 * see Array@Array+Indexes:
1250 *
1251 * joe[2] # => 12345
1252 * joe[-2] # => "123 Maple, Anytown NC"
1253 *
1254 * Raises IndexError if +n+ is out of range.
1255 *
1256 */
1257
1258VALUE
1260{
1261 int i = rb_struct_pos(s, &idx);
1262 if (i < 0) invalid_struct_pos(s, idx);
1263 return RSTRUCT_GET(s, i);
1264}
1265
1266/*
1267 * call-seq:
1268 * struct[name] = value -> value
1269 * struct[n] = value -> value
1270 *
1271 * Assigns a value to a member.
1272 *
1273 * With symbol or string argument +name+ given, assigns the given +value+
1274 * to the named member; returns +value+:
1275 *
1276 * Customer = Struct.new(:name, :address, :zip)
1277 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1278 * joe[:zip] = 54321 # => 54321
1279 * joe # => #<struct Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=54321>
1280 *
1281 * Raises NameError if +name+ is not the name of a member.
1282 *
1283 * With integer argument +n+ given, assigns the given +value+
1284 * to the +n+-th member if +n+ is in range;
1285 * see Array@Array+Indexes:
1286 *
1287 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1288 * joe[2] = 54321 # => 54321
1289 * joe[-3] = 'Joseph Smith' # => "Joseph Smith"
1290 * joe # => #<struct Customer name="Joseph Smith", address="123 Maple, Anytown NC", zip=54321>
1291 *
1292 * Raises IndexError if +n+ is out of range.
1293 *
1294 */
1295
1296VALUE
1298{
1299 int i = rb_struct_pos(s, &idx);
1300 if (i < 0) invalid_struct_pos(s, idx);
1301 rb_struct_modify(s);
1302 RSTRUCT_SET(s, i, val);
1303 return val;
1304}
1305
1306FUNC_MINIMIZED(VALUE rb_struct_lookup(VALUE s, VALUE idx));
1307NOINLINE(static VALUE rb_struct_lookup_default(VALUE s, VALUE idx, VALUE notfound));
1308
1309VALUE
1310rb_struct_lookup(VALUE s, VALUE idx)
1311{
1312 return rb_struct_lookup_default(s, idx, Qnil);
1313}
1314
1315static VALUE
1316rb_struct_lookup_default(VALUE s, VALUE idx, VALUE notfound)
1317{
1318 int i = rb_struct_pos(s, &idx);
1319 if (i < 0) return notfound;
1320 return RSTRUCT_GET(s, i);
1321}
1322
1323static VALUE
1324struct_entry(VALUE s, long n)
1325{
1326 return rb_struct_aref(s, LONG2NUM(n));
1327}
1328
1329/*
1330 * call-seq:
1331 * values_at(*integers) -> array
1332 * values_at(integer_range) -> array
1333 *
1334 * Returns an array of values from +self+.
1335 *
1336 * With integer arguments +integers+ given,
1337 * returns an array containing each value given by one of +integers+:
1338 *
1339 * Customer = Struct.new(:name, :address, :zip)
1340 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1341 * joe.values_at(0, 2) # => ["Joe Smith", 12345]
1342 * joe.values_at(2, 0) # => [12345, "Joe Smith"]
1343 * joe.values_at(2, 1, 0) # => [12345, "123 Maple, Anytown NC", "Joe Smith"]
1344 * joe.values_at(0, -3) # => ["Joe Smith", "Joe Smith"]
1345 *
1346 * Raises IndexError if any of +integers+ is out of range;
1347 * see Array@Array+Indexes.
1348 *
1349 * With integer range argument +integer_range+ given,
1350 * returns an array containing each value given by the elements of the range;
1351 * fills with +nil+ values for range elements larger than the structure:
1352 *
1353 * joe.values_at(0..2)
1354 * # => ["Joe Smith", "123 Maple, Anytown NC", 12345]
1355 * joe.values_at(-3..-1)
1356 * # => ["Joe Smith", "123 Maple, Anytown NC", 12345]
1357 * joe.values_at(1..4) # => ["123 Maple, Anytown NC", 12345, nil, nil]
1358 *
1359 * Raises RangeError if any element of the range is negative and out of range;
1360 * see Array@Array+Indexes.
1361 *
1362 */
1363
1364static VALUE
1365rb_struct_values_at(int argc, VALUE *argv, VALUE s)
1366{
1367 return rb_get_values_at(s, RSTRUCT_LEN(s), argc, argv, struct_entry);
1368}
1369
1370/*
1371 * call-seq:
1372 * select {|value| ... } -> array
1373 * select -> enumerator
1374 *
1375 * With a block given, returns an array of values from +self+
1376 * for which the block returns a truthy value:
1377 *
1378 * Customer = Struct.new(:name, :address, :zip)
1379 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1380 * a = joe.select {|value| value.is_a?(String) }
1381 * a # => ["Joe Smith", "123 Maple, Anytown NC"]
1382 * a = joe.select {|value| value.is_a?(Integer) }
1383 * a # => [12345]
1384 *
1385 * With no block given, returns an Enumerator.
1386 *
1387 * Struct#filter is an alias for Struct#select.
1388 */
1389
1390static VALUE
1391rb_struct_select(int argc, VALUE *argv, VALUE s)
1392{
1393 VALUE result;
1394 long i;
1395
1396 rb_check_arity(argc, 0, 0);
1397 RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
1398 result = rb_ary_new();
1399 for (i = 0; i < RSTRUCT_LEN(s); i++) {
1400 if (RTEST(rb_yield(RSTRUCT_GET(s, i)))) {
1401 rb_ary_push(result, RSTRUCT_GET(s, i));
1402 }
1403 }
1404
1405 return result;
1406}
1407
1408static VALUE
1409recursive_equal(VALUE s, VALUE s2, int recur)
1410{
1411 long i, len;
1412
1413 if (recur) return Qtrue; /* Subtle! */
1414 len = RSTRUCT_LEN(s);
1415 for (i=0; i<len; i++) {
1416 if (!rb_equal(RSTRUCT_GET(s, i), RSTRUCT_GET(s2, i))) return Qfalse;
1417 }
1418 return Qtrue;
1419}
1420
1421
1422/*
1423 * call-seq:
1424 * self == other -> true or false
1425 *
1426 * Returns +true+ if and only if the following are true; otherwise returns +false+:
1427 *
1428 * - <tt>other.class == self.class</tt>.
1429 * - For each member name +name+, <tt>other.name == self.name</tt>.
1430 *
1431 * Examples:
1432 *
1433 * Customer = Struct.new(:name, :address, :zip)
1434 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1435 * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1436 * joe_jr == joe # => true
1437 * joe_jr[:name] = 'Joe Smith, Jr.'
1438 * # => "Joe Smith, Jr."
1439 * joe_jr == joe # => false
1440 */
1441
1442static VALUE
1443rb_struct_equal(VALUE s, VALUE s2)
1444{
1445 if (s == s2) return Qtrue;
1446 if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse;
1447 if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse;
1448 if (RSTRUCT_LEN(s) != RSTRUCT_LEN(s2)) {
1449 rb_bug("inconsistent struct"); /* should never happen */
1450 }
1451
1452 return rb_exec_recursive_paired(recursive_equal, s, s2, s2);
1453}
1454
1455/*
1456 * call-seq:
1457 * hash -> integer
1458 *
1459 * Returns the integer hash value for +self+.
1460 *
1461 * Two structs of the same class and with the same content
1462 * will have the same hash code (and will compare using Struct#eql?):
1463 *
1464 * Customer = Struct.new(:name, :address, :zip)
1465 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1466 * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1467 * joe.hash == joe_jr.hash # => true
1468 * joe_jr[:name] = 'Joe Smith, Jr.'
1469 * joe.hash == joe_jr.hash # => false
1470 *
1471 * Related: Object#hash.
1472 */
1473
1474static VALUE
1475rb_struct_hash(VALUE s)
1476{
1477 long i, len;
1478 st_index_t h;
1479 VALUE n;
1480
1481 h = rb_hash_start(rb_hash(rb_obj_class(s)));
1482 len = RSTRUCT_LEN(s);
1483 for (i = 0; i < len; i++) {
1484 n = rb_hash(RSTRUCT_GET(s, i));
1485 h = rb_hash_uint(h, NUM2LONG(n));
1486 }
1487 h = rb_hash_end(h);
1488 return ST2FIX(h);
1489}
1490
1491static VALUE
1492recursive_eql(VALUE s, VALUE s2, int recur)
1493{
1494 long i, len;
1495
1496 if (recur) return Qtrue; /* Subtle! */
1497 len = RSTRUCT_LEN(s);
1498 for (i=0; i<len; i++) {
1499 if (!rb_eql(RSTRUCT_GET(s, i), RSTRUCT_GET(s2, i))) return Qfalse;
1500 }
1501 return Qtrue;
1502}
1503
1504/*
1505 * call-seq:
1506 * eql?(other) -> true or false
1507 *
1508 * Returns +true+ if and only if the following are true; otherwise returns +false+:
1509 *
1510 * - <tt>other.class == self.class</tt>.
1511 * - For each member name +name+, <tt>other.name.eql?(self.name)</tt>.
1512 *
1513 * Customer = Struct.new(:name, :address, :zip)
1514 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1515 * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1516 * joe_jr.eql?(joe) # => true
1517 * joe_jr[:name] = 'Joe Smith, Jr.'
1518 * joe_jr.eql?(joe) # => false
1519 *
1520 * Related: Object#==.
1521 */
1522
1523static VALUE
1524rb_struct_eql(VALUE s, VALUE s2)
1525{
1526 if (s == s2) return Qtrue;
1527 if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse;
1528 if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse;
1529 if (RSTRUCT_LEN(s) != RSTRUCT_LEN(s2)) {
1530 rb_bug("inconsistent struct"); /* should never happen */
1531 }
1532
1533 return rb_exec_recursive_paired(recursive_eql, s, s2, s2);
1534}
1535
1536/*
1537 * call-seq:
1538 * size -> integer
1539 *
1540 * Returns the number of members.
1541 *
1542 * Customer = Struct.new(:name, :address, :zip)
1543 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
1544 * joe.size #=> 3
1545 *
1546 * Struct#length is an alias for Struct#size.
1547 */
1548
1549VALUE
1551{
1552 return LONG2FIX(RSTRUCT_LEN(s));
1553}
1554
1555/*
1556 * call-seq:
1557 * dig(name, *identifiers) -> object
1558 * dig(n, *identifiers) -> object
1559 *
1560 * Finds and returns an object among nested objects.
1561 * The nested objects may be instances of various classes.
1562 * See {Dig Methods}[rdoc-ref:dig_methods.rdoc].
1563 *
1564 *
1565 * Given symbol or string argument +name+,
1566 * returns the object that is specified by +name+ and +identifiers+:
1567 *
1568 * Foo = Struct.new(:a)
1569 * f = Foo.new(Foo.new({b: [1, 2, 3]}))
1570 * f.dig(:a) # => #<struct Foo a={:b=>[1, 2, 3]}>
1571 * f.dig(:a, :a) # => {:b=>[1, 2, 3]}
1572 * f.dig(:a, :a, :b) # => [1, 2, 3]
1573 * f.dig(:a, :a, :b, 0) # => 1
1574 * f.dig(:b, 0) # => nil
1575 *
1576 * Given integer argument +n+,
1577 * returns the object that is specified by +n+ and +identifiers+:
1578 *
1579 * f.dig(0) # => #<struct Foo a={:b=>[1, 2, 3]}>
1580 * f.dig(0, 0) # => {:b=>[1, 2, 3]}
1581 * f.dig(0, 0, :b) # => [1, 2, 3]
1582 * f.dig(0, 0, :b, 0) # => 1
1583 * f.dig(:b, 0) # => nil
1584 *
1585 */
1586
1587static VALUE
1588rb_struct_dig(int argc, VALUE *argv, VALUE self)
1589{
1591 self = rb_struct_lookup(self, *argv);
1592 if (!--argc) return self;
1593 ++argv;
1594 return rb_obj_dig(argc, argv, self, Qnil);
1595}
1596
1597/*
1598 * Document-class: Data
1599 *
1600 * \Class \Data provides a convenient way to define simple classes
1601 * for value-alike objects.
1602 *
1603 * The simplest example of usage:
1604 *
1605 * Measure = Data.define(:amount, :unit)
1606 *
1607 * # Positional arguments constructor is provided
1608 * distance = Measure.new(100, 'km')
1609 * #=> #<data Measure amount=100, unit="km">
1610 *
1611 * # Keyword arguments constructor is provided
1612 * weight = Measure.new(amount: 50, unit: 'kg')
1613 * #=> #<data Measure amount=50, unit="kg">
1614 *
1615 * # Alternative form to construct an object:
1616 * speed = Measure[10, 'mPh']
1617 * #=> #<data Measure amount=10, unit="mPh">
1618 *
1619 * # Works with keyword arguments, too:
1620 * area = Measure[amount: 1.5, unit: 'm^2']
1621 * #=> #<data Measure amount=1.5, unit="m^2">
1622 *
1623 * # Argument accessors are provided:
1624 * distance.amount #=> 100
1625 * distance.unit #=> "km"
1626 *
1627 * Constructed object also has a reasonable definitions of #==
1628 * operator, #to_h hash conversion, and #deconstruct/#deconstruct_keys
1629 * to be used in pattern matching.
1630 *
1631 * ::define method accepts an optional block and evaluates it in
1632 * the context of the newly defined class. That allows to define
1633 * additional methods:
1634 *
1635 * Measure = Data.define(:amount, :unit) do
1636 * def <=>(other)
1637 * return unless other.is_a?(self.class) && other.unit == unit
1638 * amount <=> other.amount
1639 * end
1640 *
1641 * include Comparable
1642 * end
1643 *
1644 * Measure[3, 'm'] < Measure[5, 'm'] #=> true
1645 * Measure[3, 'm'] < Measure[5, 'kg']
1646 * # comparison of Measure with Measure failed (ArgumentError)
1647 *
1648 * Data provides no member writers, or enumerators: it is meant
1649 * to be a storage for immutable atomic values. But note that
1650 * if some of data members is of a mutable class, Data does no additional
1651 * immutability enforcement:
1652 *
1653 * Event = Data.define(:time, :weekdays)
1654 * event = Event.new('18:00', %w[Tue Wed Fri])
1655 * #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri"]>
1656 *
1657 * # There is no #time= or #weekdays= accessors, but changes are
1658 * # still possible:
1659 * event.weekdays << 'Sat'
1660 * event
1661 * #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri", "Sat"]>
1662 *
1663 * See also Struct, which is a similar concept, but has more
1664 * container-alike API, allowing to change contents of the object
1665 * and enumerate it.
1666 */
1667
1668/*
1669 * call-seq:
1670 * define(*symbols) -> class
1671 *
1672 * Defines a new \Data class.
1673 *
1674 * measure = Data.define(:amount, :unit)
1675 * #=> #<Class:0x00007f70c6868498>
1676 * measure.new(1, 'km')
1677 * #=> #<data amount=1, unit="km">
1678 *
1679 * # It you store the new class in the constant, it will
1680 * # affect #inspect and will be more natural to use:
1681 * Measure = Data.define(:amount, :unit)
1682 * #=> Measure
1683 * Measure.new(1, 'km')
1684 * #=> #<data Measure amount=1, unit="km">
1685 *
1686 *
1687 * Note that member-less \Data is acceptable and might be a useful technique
1688 * for defining several homogenous data classes, like
1689 *
1690 * class HTTPFetcher
1691 * Response = Data.define(:body)
1692 * NotFound = Data.define
1693 * # ... implementation
1694 * end
1695 *
1696 * Now, different kinds of responses from +HTTPFetcher+ would have consistent
1697 * representation:
1698 *
1699 * #<data HTTPFetcher::Response body="<html...">
1700 * #<data HTTPFetcher::NotFound>
1701 *
1702 * And are convenient to use in pattern matching:
1703 *
1704 * case fetcher.get(url)
1705 * in HTTPFetcher::Response(body)
1706 * # process body variable
1707 * in HTTPFetcher::NotFound
1708 * # handle not found case
1709 * end
1710 */
1711
1712static VALUE
1713rb_data_s_def(int argc, VALUE *argv, VALUE klass)
1714{
1715 VALUE rest;
1716 long i;
1717 VALUE data_class;
1718 st_table *tbl;
1719
1720 rest = rb_ident_hash_new();
1721 RBASIC_CLEAR_CLASS(rest);
1722 OBJ_WB_UNPROTECT(rest);
1723 tbl = RHASH_TBL_RAW(rest);
1724 for (i=0; i<argc; i++) {
1725 VALUE mem = rb_to_symbol(argv[i]);
1726 if (rb_is_attrset_sym(mem)) {
1727 rb_raise(rb_eArgError, "invalid data member: %"PRIsVALUE, mem);
1728 }
1729 if (st_insert(tbl, mem, Qtrue)) {
1730 rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem);
1731 }
1732 }
1733 rest = rb_hash_keys(rest);
1734 st_clear(tbl);
1735 RBASIC_CLEAR_CLASS(rest);
1736 OBJ_FREEZE_RAW(rest);
1737 data_class = anonymous_struct(klass);
1738 setup_data(data_class, rest);
1739 if (rb_block_given_p()) {
1740 rb_mod_module_eval(0, 0, data_class);
1741 }
1742
1743 return data_class;
1744}
1745
1746/*
1747 * call-seq:
1748 * DataClass::members -> array_of_symbols
1749 *
1750 * Returns an array of member names of the data class:
1751 *
1752 * Measure = Data.define(:amount, :unit)
1753 * Measure.members # => [:amount, :unit]
1754 *
1755 */
1756
1757#define rb_data_s_members_m rb_struct_s_members_m
1758
1759
1760/*
1761 * call-seq:
1762 * new(*args) -> instance
1763 * new(**kwargs) -> instance
1764 * ::[](*args) -> instance
1765 * ::[](**kwargs) -> instance
1766 *
1767 * Constructors for classes defined with ::define accept both positional and
1768 * keyword arguments.
1769 *
1770 * Measure = Data.define(:amount, :unit)
1771 *
1772 * Measure.new(1, 'km')
1773 * #=> #<data Measure amount=1, unit="km">
1774 * Measure.new(amount: 1, unit: 'km')
1775 * #=> #<data Measure amount=1, unit="km">
1776 *
1777 * # Alternative shorter intialization with []
1778 * Measure[1, 'km']
1779 * #=> #<data Measure amount=1, unit="km">
1780 * Measure[amount: 1, unit: 'km']
1781 * #=> #<data Measure amount=1, unit="km">
1782 *
1783 * All arguments are mandatory (unlike Struct), and converted to keyword arguments:
1784 *
1785 * Measure.new(amount: 1)
1786 * # in `initialize': missing keyword: :unit (ArgumentError)
1787 *
1788 * Measure.new(1)
1789 * # in `initialize': missing keyword: :unit (ArgumentError)
1790 *
1791 * Note that <tt>Measure#initialize</tt> always receives keyword arguments, and that
1792 * mandatory arguments are checked in +initialize+, not in +new+. This can be
1793 * important for redefining initialize in order to convert arguments or provide
1794 * defaults:
1795 *
1796 * Measure = Data.define(:amount, :unit) do
1797 * NONE = Data.define
1798 *
1799 * def initialize(amount:, unit: NONE.new)
1800 * super(amount: Float(amount), unit:)
1801 * end
1802 * end
1803 *
1804 * Measure.new('10', 'km') # => #<data Measure amount=10.0, unit="km">
1805 * Measure.new(10_000) # => #<data Measure amount=10000.0, unit=#<data NONE>>
1806 *
1807 */
1808
1809static VALUE
1810rb_data_initialize_m(int argc, const VALUE *argv, VALUE self)
1811{
1812 VALUE klass = rb_obj_class(self);
1813 rb_struct_modify(self);
1814 VALUE members = struct_ivar_get(klass, id_members);
1815 size_t num_members = RARRAY_LEN(members);
1816
1817 if (argc == 0) {
1818 if (num_members > 0) {
1819 rb_exc_raise(rb_keyword_error_new("missing", members));
1820 }
1821 return Qnil;
1822 }
1823 if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) {
1824 rb_error_arity(argc, 0, 0);
1825 }
1826
1827 if (RHASH_SIZE(argv[0]) < num_members) {
1828 VALUE missing = rb_ary_diff(members, rb_hash_keys(argv[0]));
1829 rb_exc_raise(rb_keyword_error_new("missing", missing));
1830 }
1831
1832 struct struct_hash_set_arg arg;
1833 rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), num_members);
1834 arg.self = self;
1835 arg.unknown_keywords = Qnil;
1836 rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg);
1837 if (arg.unknown_keywords != Qnil) {
1838 rb_exc_raise(rb_keyword_error_new("unknown", arg.unknown_keywords));
1839 }
1840 OBJ_FREEZE_RAW(self);
1841 return Qnil;
1842}
1843
1844/* :nodoc: */
1845static VALUE
1846rb_data_init_copy(VALUE copy, VALUE s)
1847{
1848 copy = rb_struct_init_copy(copy, s);
1849 RB_OBJ_FREEZE_RAW(copy);
1850 return copy;
1851}
1852
1853/*
1854 * call-seq:
1855 * with(**kwargs) -> instance
1856 *
1857 * Returns a shallow copy of +self+ --- the instance variables of
1858 * +self+ are copied, but not the objects they reference.
1859 *
1860 * If the method is supplied any keyword arguments, the copy will
1861 * be created with the respective field values updated to use the
1862 * supplied keyword argument values. Note that it is an error to
1863 * supply a keyword that the Data class does not have as a member.
1864 *
1865 * Point = Data.define(:x, :y)
1866 *
1867 * origin = Point.new(x: 0, y: 0)
1868 *
1869 * up = origin.with(x: 1)
1870 * right = origin.with(y: 1)
1871 * up_and_right = up.with(y: 1)
1872 *
1873 * p origin # #<data Point x=0, y=0>
1874 * p up # #<data Point x=1, y=0>
1875 * p right # #<data Point x=0, y=1>
1876 * p up_and_right # #<data Point x=1, y=1>
1877 *
1878 * out = origin.with(z: 1) # ArgumentError: unknown keyword: :z
1879 * some_point = origin.with(1, 2) # ArgumentError: expected keyword arguments, got positional arguments
1880 *
1881 */
1882
1883static VALUE
1884rb_data_with(int argc, const VALUE *argv, VALUE self)
1885{
1886 VALUE kwargs;
1887 rb_scan_args(argc, argv, "0:", &kwargs);
1888 if (NIL_P(kwargs)) {
1889 return self;
1890 }
1891
1892 VALUE copy = rb_obj_alloc(rb_obj_class(self));
1893 rb_struct_init_copy(copy, self);
1894
1895 struct struct_hash_set_arg arg;
1896 arg.self = copy;
1897 arg.unknown_keywords = Qnil;
1898 rb_hash_foreach(kwargs, struct_hash_set_i, (VALUE)&arg);
1899 // Freeze early before potentially raising, so that we don't leave an
1900 // unfrozen copy on the heap, which could get exposed via ObjectSpace.
1901 RB_OBJ_FREEZE_RAW(copy);
1902
1903 if (arg.unknown_keywords != Qnil) {
1904 rb_exc_raise(rb_keyword_error_new("unknown", arg.unknown_keywords));
1905 }
1906
1907 return copy;
1908}
1909
1910/*
1911 * call-seq:
1912 * inspect -> string
1913 * to_s -> string
1914 *
1915 * Returns a string representation of +self+:
1916 *
1917 * Measure = Data.define(:amount, :unit)
1918 *
1919 * distance = Measure[10, 'km']
1920 *
1921 * p distance # uses #inspect underneath
1922 * #<data Measure amount=10, unit="km">
1923 *
1924 * puts distance # uses #to_s underneath, same representation
1925 * #<data Measure amount=10, unit="km">
1926 *
1927 */
1928
1929static VALUE
1930rb_data_inspect(VALUE s)
1931{
1932 return rb_exec_recursive(inspect_struct, s, rb_str_new2("#<data "));
1933}
1934
1935/*
1936 * call-seq:
1937 * self == other -> true or false
1938 *
1939 * Returns +true+ if +other+ is the same class as +self+, and all members are
1940 * equal.
1941 *
1942 * Examples:
1943 *
1944 * Measure = Data.define(:amount, :unit)
1945 *
1946 * Measure[1, 'km'] == Measure[1, 'km'] #=> true
1947 * Measure[1, 'km'] == Measure[2, 'km'] #=> false
1948 * Measure[1, 'km'] == Measure[1, 'm'] #=> false
1949 *
1950 * Measurement = Data.define(:amount, :unit)
1951 * # Even though Measurement and Measure have the same "shape"
1952 * # their instances are never equal
1953 * Measure[1, 'km'] == Measurement[1, 'km'] #=> false
1954 */
1955
1956#define rb_data_equal rb_struct_equal
1957
1958/*
1959 * call-seq:
1960 * self.eql?(other) -> true or false
1961 *
1962 * Equality check that is used when two items of data are keys of a Hash.
1963 *
1964 * The subtle difference with #== is that members are also compared with their
1965 * #eql? method, which might be important in some cases:
1966 *
1967 * Measure = Data.define(:amount, :unit)
1968 *
1969 * Measure[1, 'km'] == Measure[1.0, 'km'] #=> true, they are equal as values
1970 * # ...but...
1971 * Measure[1, 'km'].eql? Measure[1.0, 'km'] #=> false, they represent different hash keys
1972 *
1973 * See also Object#eql? for further explanations of the method usage.
1974 */
1975
1976#define rb_data_eql rb_struct_eql
1977
1978/*
1979 * call-seq:
1980 * hash -> integer
1981 *
1982 * Redefines Object#hash (used to distinguish objects as Hash keys) so that
1983 * data objects of the same class with same content would have the same +hash+
1984 * value, and represented the same Hash key.
1985 *
1986 * Measure = Data.define(:amount, :unit)
1987 *
1988 * Measure[1, 'km'].hash == Measure[1, 'km'].hash #=> true
1989 * Measure[1, 'km'].hash == Measure[10, 'km'].hash #=> false
1990 * Measure[1, 'km'].hash == Measure[1, 'm'].hash #=> false
1991 * Measure[1, 'km'].hash == Measure[1.0, 'km'].hash #=> false
1992 *
1993 * # Structurally similar data class, but shouldn't be considered
1994 * # the same hash key
1995 * Measurement = Data.define(:amount, :unit)
1996 *
1997 * Measure[1, 'km'].hash == Measurement[1, 'km'].hash #=> false
1998 */
1999
2000#define rb_data_hash rb_struct_hash
2001
2002/*
2003 * call-seq:
2004 * to_h -> hash
2005 * to_h {|name, value| ... } -> hash
2006 *
2007 * Returns Hash representation of the data object.
2008 *
2009 * Measure = Data.define(:amount, :unit)
2010 * distance = Measure[10, 'km']
2011 *
2012 * distance.to_h
2013 * #=> {:amount=>10, :unit=>"km"}
2014 *
2015 * Like Enumerable#to_h, if the block is provided, it is expected to
2016 * produce key-value pairs to construct a hash:
2017 *
2018 *
2019 * distance.to_h { |name, val| [name.to_s, val.to_s] }
2020 * #=> {"amount"=>"10", "unit"=>"km"}
2021 *
2022 * Note that there is a useful symmetry between #to_h and #initialize:
2023 *
2024 * distance2 = Measure.new(**distance.to_h)
2025 * #=> #<data Measure amount=10, unit="km">
2026 * distance2 == distance
2027 * #=> true
2028 */
2029
2030#define rb_data_to_h rb_struct_to_h
2031
2032/*
2033 * call-seq:
2034 * members -> array_of_symbols
2035 *
2036 * Returns the member names from +self+ as an array:
2037 *
2038 * Measure = Data.define(:amount, :unit)
2039 * distance = Measure[10, 'km']
2040 *
2041 * distance.members #=> [:amount, :unit]
2042 *
2043 */
2044
2045#define rb_data_members_m rb_struct_members_m
2046
2047/*
2048 * call-seq:
2049 * deconstruct -> array
2050 *
2051 * Returns the values in +self+ as an array, to use in pattern matching:
2052 *
2053 * Measure = Data.define(:amount, :unit)
2054 *
2055 * distance = Measure[10, 'km']
2056 * distance.deconstruct #=> [10, "km"]
2057 *
2058 * # usage
2059 * case distance
2060 * in n, 'km' # calls #deconstruct underneath
2061 * puts "It is #{n} kilometers away"
2062 * else
2063 * puts "Don't know how to handle it"
2064 * end
2065 * # prints "It is 10 kilometers away"
2066 *
2067 * Or, with checking the class, too:
2068 *
2069 * case distance
2070 * in Measure(n, 'km')
2071 * puts "It is #{n} kilometers away"
2072 * # ...
2073 * end
2074 */
2075
2076#define rb_data_deconstruct rb_struct_to_a
2077
2078/*
2079 * call-seq:
2080 * deconstruct_keys(array_of_names_or_nil) -> hash
2081 *
2082 * Returns a hash of the name/value pairs, to use in pattern matching.
2083 *
2084 * Measure = Data.define(:amount, :unit)
2085 *
2086 * distance = Measure[10, 'km']
2087 * distance.deconstruct_keys(nil) #=> {:amount=>10, :unit=>"km"}
2088 * distance.deconstruct_keys([:amount]) #=> {:amount=>10}
2089 *
2090 * # usage
2091 * case distance
2092 * in amount:, unit: 'km' # calls #deconstruct_keys underneath
2093 * puts "It is #{amount} kilometers away"
2094 * else
2095 * puts "Don't know how to handle it"
2096 * end
2097 * # prints "It is 10 kilometers away"
2098 *
2099 * Or, with checking the class, too:
2100 *
2101 * case distance
2102 * in Measure(amount:, unit: 'km')
2103 * puts "It is #{amount} kilometers away"
2104 * # ...
2105 * end
2106 */
2107
2108#define rb_data_deconstruct_keys rb_struct_deconstruct_keys
2109
2110/*
2111 * Document-class: Struct
2112 *
2113 * \Class \Struct provides a convenient way to create a simple class
2114 * that can store and fetch values.
2115 *
2116 * This example creates a subclass of +Struct+, <tt>Struct::Customer</tt>;
2117 * the first argument, a string, is the name of the subclass;
2118 * the other arguments, symbols, determine the _members_ of the new subclass.
2119 *
2120 * Customer = Struct.new('Customer', :name, :address, :zip)
2121 * Customer.name # => "Struct::Customer"
2122 * Customer.class # => Class
2123 * Customer.superclass # => Struct
2124 *
2125 * Corresponding to each member are two methods, a writer and a reader,
2126 * that store and fetch values:
2127 *
2128 * methods = Customer.instance_methods false
2129 * methods # => [:zip, :address=, :zip=, :address, :name, :name=]
2130 *
2131 * An instance of the subclass may be created,
2132 * and its members assigned values, via method <tt>::new</tt>:
2133 *
2134 * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
2135 * joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345>
2136 *
2137 * The member values may be managed thus:
2138 *
2139 * joe.name # => "Joe Smith"
2140 * joe.name = 'Joseph Smith'
2141 * joe.name # => "Joseph Smith"
2142 *
2143 * And thus; note that member name may be expressed as either a string or a symbol:
2144 *
2145 * joe[:name] # => "Joseph Smith"
2146 * joe[:name] = 'Joseph Smith, Jr.'
2147 * joe['name'] # => "Joseph Smith, Jr."
2148 *
2149 * See Struct::new.
2150 *
2151 * == What's Here
2152 *
2153 * First, what's elsewhere. \Class \Struct:
2154 *
2155 * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
2156 * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here],
2157 * which provides dozens of additional methods.
2158 *
2159 * See also Data, which is a somewhat similar, but stricter concept for defining immutable
2160 * value objects.
2161 *
2162 * Here, class \Struct provides methods that are useful for:
2163 *
2164 * - {Creating a Struct Subclass}[rdoc-ref:Struct@Methods+for+Creating+a+Struct+Subclass]
2165 * - {Querying}[rdoc-ref:Struct@Methods+for+Querying]
2166 * - {Comparing}[rdoc-ref:Struct@Methods+for+Comparing]
2167 * - {Fetching}[rdoc-ref:Struct@Methods+for+Fetching]
2168 * - {Assigning}[rdoc-ref:Struct@Methods+for+Assigning]
2169 * - {Iterating}[rdoc-ref:Struct@Methods+for+Iterating]
2170 * - {Converting}[rdoc-ref:Struct@Methods+for+Converting]
2171 *
2172 * === Methods for Creating a Struct Subclass
2173 *
2174 * - ::new: Returns a new subclass of \Struct.
2175 *
2176 * === Methods for Querying
2177 *
2178 * - #hash: Returns the integer hash code.
2179 * - #length, #size: Returns the number of members.
2180 *
2181 * === Methods for Comparing
2182 *
2183 * - #==: Returns whether a given object is equal to +self+, using <tt>==</tt>
2184 * to compare member values.
2185 * - #eql?: Returns whether a given object is equal to +self+,
2186 * using <tt>eql?</tt> to compare member values.
2187 *
2188 * === Methods for Fetching
2189 *
2190 * - #[]: Returns the value associated with a given member name.
2191 * - #to_a, #values, #deconstruct: Returns the member values in +self+ as an array.
2192 * - #deconstruct_keys: Returns a hash of the name/value pairs
2193 * for given member names.
2194 * - #dig: Returns the object in nested objects that is specified
2195 * by a given member name and additional arguments.
2196 * - #members: Returns an array of the member names.
2197 * - #select, #filter: Returns an array of member values from +self+,
2198 * as selected by the given block.
2199 * - #values_at: Returns an array containing values for given member names.
2200 *
2201 * === Methods for Assigning
2202 *
2203 * - #[]=: Assigns a given value to a given member name.
2204 *
2205 * === Methods for Iterating
2206 *
2207 * - #each: Calls a given block with each member name.
2208 * - #each_pair: Calls a given block with each member name/value pair.
2209 *
2210 * === Methods for Converting
2211 *
2212 * - #inspect, #to_s: Returns a string representation of +self+.
2213 * - #to_h: Returns a hash of the member name/value pairs in +self+.
2214 *
2215 */
2216void
2217InitVM_Struct(void)
2218{
2219 rb_cStruct = rb_define_class("Struct", rb_cObject);
2221
2223 rb_define_singleton_method(rb_cStruct, "new", rb_struct_s_def, -1);
2224#if 0 /* for RDoc */
2225 rb_define_singleton_method(rb_cStruct, "keyword_init?", rb_struct_s_keyword_init_p, 0);
2226 rb_define_singleton_method(rb_cStruct, "members", rb_struct_s_members_m, 0);
2227#endif
2228
2229 rb_define_method(rb_cStruct, "initialize", rb_struct_initialize_m, -1);
2230 rb_define_method(rb_cStruct, "initialize_copy", rb_struct_init_copy, 1);
2231
2232 rb_define_method(rb_cStruct, "==", rb_struct_equal, 1);
2233 rb_define_method(rb_cStruct, "eql?", rb_struct_eql, 1);
2234 rb_define_method(rb_cStruct, "hash", rb_struct_hash, 0);
2235
2236 rb_define_method(rb_cStruct, "inspect", rb_struct_inspect, 0);
2237 rb_define_alias(rb_cStruct, "to_s", "inspect");
2238 rb_define_method(rb_cStruct, "to_a", rb_struct_to_a, 0);
2239 rb_define_method(rb_cStruct, "to_h", rb_struct_to_h, 0);
2240 rb_define_method(rb_cStruct, "values", rb_struct_to_a, 0);
2241 rb_define_method(rb_cStruct, "size", rb_struct_size, 0);
2242 rb_define_method(rb_cStruct, "length", rb_struct_size, 0);
2243
2244 rb_define_method(rb_cStruct, "each", rb_struct_each, 0);
2245 rb_define_method(rb_cStruct, "each_pair", rb_struct_each_pair, 0);
2246 rb_define_method(rb_cStruct, "[]", rb_struct_aref, 1);
2247 rb_define_method(rb_cStruct, "[]=", rb_struct_aset, 2);
2248 rb_define_method(rb_cStruct, "select", rb_struct_select, -1);
2249 rb_define_method(rb_cStruct, "filter", rb_struct_select, -1);
2250 rb_define_method(rb_cStruct, "values_at", rb_struct_values_at, -1);
2251
2252 rb_define_method(rb_cStruct, "members", rb_struct_members_m, 0);
2253 rb_define_method(rb_cStruct, "dig", rb_struct_dig, -1);
2254
2255 rb_define_method(rb_cStruct, "deconstruct", rb_struct_to_a, 0);
2256 rb_define_method(rb_cStruct, "deconstruct_keys", rb_struct_deconstruct_keys, 1);
2257
2258 rb_cData = rb_define_class("Data", rb_cObject);
2259
2260 rb_undef_method(CLASS_OF(rb_cData), "new");
2261 rb_undef_alloc_func(rb_cData);
2262 rb_define_singleton_method(rb_cData, "define", rb_data_s_def, -1);
2263
2264#if 0 /* for RDoc */
2265 rb_define_singleton_method(rb_cData, "members", rb_data_s_members_m, 0);
2266#endif
2267
2268 rb_define_method(rb_cData, "initialize", rb_data_initialize_m, -1);
2269 rb_define_method(rb_cData, "initialize_copy", rb_data_init_copy, 1);
2270
2271 rb_define_method(rb_cData, "==", rb_data_equal, 1);
2272 rb_define_method(rb_cData, "eql?", rb_data_eql, 1);
2273 rb_define_method(rb_cData, "hash", rb_data_hash, 0);
2274
2275 rb_define_method(rb_cData, "inspect", rb_data_inspect, 0);
2276 rb_define_alias(rb_cData, "to_s", "inspect");
2277 rb_define_method(rb_cData, "to_h", rb_data_to_h, 0);
2278
2279 rb_define_method(rb_cData, "members", rb_data_members_m, 0);
2280
2281 rb_define_method(rb_cData, "deconstruct", rb_data_deconstruct, 0);
2282 rb_define_method(rb_cData, "deconstruct_keys", rb_data_deconstruct_keys, 1);
2283
2284 rb_define_method(rb_cData, "with", rb_data_with, -1);
2285}
2286
2287#undef rb_intern
2288void
2289Init_Struct(void)
2290{
2291 id_members = rb_intern("__members__");
2292 id_back_members = rb_intern("__members_back__");
2293 id_keyword_init = rb_intern("__keyword_init__");
2294
2295 InitVM(Struct);
2296}
#define RUBY_ASSERT(expr)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:177
#define rb_define_method(klass, mid, func, arity)
Defines klass#mid.
#define rb_define_singleton_method(klass, mid, func, arity)
Defines klass.mid.
static void RB_OBJ_FREEZE_RAW(VALUE obj)
This is an implenentation detail of RB_OBJ_FREEZE().
Definition fl_type.h:939
void rb_include_module(VALUE klass, VALUE module)
Includes a module to a class.
Definition class.c:1130
VALUE rb_define_class(const char *name, VALUE super)
Defines a top-level class.
Definition class.c:923
VALUE rb_class_new(VALUE super)
Creates a new, anonymous class.
Definition class.c:325
VALUE rb_singleton_class(VALUE obj)
Finds or creates the singleton class of the passed object.
Definition class.c:2241
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
Defines a class under the namespace of outer.
Definition class.c:955
VALUE rb_define_class_id_under(VALUE outer, ID id, VALUE super)
Identical to rb_define_class_under(), except it takes the name in ID instead of C's string.
Definition class.c:994
VALUE rb_class_inherited(VALUE super, VALUE klass)
Calls Class#inherited.
Definition class.c:914
void rb_define_alias(VALUE klass, const char *name1, const char *name2)
Defines an alias of a method.
Definition class.c:2289
void rb_undef_method(VALUE klass, const char *name)
Defines an undef of a method.
Definition class.c:2113
int rb_scan_args(int argc, const VALUE *argv, const char *fmt,...)
Retrieves argument from argc and argv to given VALUE references according to the format string.
Definition class.c:2579
int rb_keyword_given_p(void)
Determines if the current method is given a keyword argument.
Definition eval.c:881
int rb_block_given_p(void)
Determines if the current method is given a block.
Definition eval.c:868
int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
Keyword argument deconstructor.
Definition class.c:2368
#define rb_str_new2
Old name of rb_str_new_cstr.
Definition string.h:1675
#define NEWOBJ_OF
Old name of RB_NEWOBJ_OF.
Definition newobj.h:61
#define FL_UNSET_RAW
Old name of RB_FL_UNSET_RAW.
Definition fl_type.h:142
#define OBJ_INIT_COPY(obj, orig)
Old name of RB_OBJ_INIT_COPY.
Definition object.h:41
#define T_STRING
Old name of RUBY_T_STRING.
Definition value_type.h:78
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
#define rb_str_cat2
Old name of rb_str_cat_cstr.
Definition string.h:1683
#define ID2SYM
Old name of RB_ID2SYM.
Definition symbol.h:44
#define T_STRUCT
Old name of RUBY_T_STRUCT.
Definition value_type.h:79
#define OBJ_FREEZE_RAW
Old name of RB_OBJ_FREEZE_RAW.
Definition fl_type.h:144
#define UNREACHABLE_RETURN
Old name of RBIMPL_UNREACHABLE_RETURN.
Definition assume.h:29
#define SYM2ID
Old name of RB_SYM2ID.
Definition symbol.h:45
#define FIX2UINT
Old name of RB_FIX2UINT.
Definition int.h:42
#define CLASS_OF
Old name of rb_class_of.
Definition globals.h:203
#define rb_ary_new4
Old name of rb_ary_new_from_values.
Definition array.h:653
#define LONG2FIX
Old name of RB_INT2FIX.
Definition long.h:49
#define FIX2INT
Old name of RB_FIX2INT.
Definition int.h:41
#define T_HASH
Old name of RUBY_T_HASH.
Definition value_type.h:65
#define ALLOC_N
Old name of RB_ALLOC_N.
Definition memory.h:393
#define LONG2NUM
Old name of RB_LONG2NUM.
Definition long.h:50
#define Qtrue
Old name of RUBY_Qtrue.
#define ST2FIX
Old name of RB_ST2FIX.
Definition st_data_t.h:33
#define Qnil
Old name of RUBY_Qnil.
#define Qfalse
Old name of RUBY_Qfalse.
#define T_ARRAY
Old name of RUBY_T_ARRAY.
Definition value_type.h:56
#define NIL_P
Old name of RB_NIL_P.
#define FL_WB_PROTECTED
Old name of RUBY_FL_WB_PROTECTED.
Definition fl_type.h:59
#define T_CLASS
Old name of RUBY_T_CLASS.
Definition value_type.h:58
#define NUM2LONG
Old name of RB_NUM2LONG.
Definition long.h:51
#define FIXNUM_P
Old name of RB_FIXNUM_P.
#define OBJ_WB_UNPROTECT
Old name of RB_OBJ_WB_UNPROTECT.
Definition rgengc.h:238
#define SYMBOL_P
Old name of RB_SYMBOL_P.
Definition value_type.h:88
void rb_raise(VALUE exc, const char *fmt,...)
Exception entry point.
Definition error.c:3150
void rb_exc_raise(VALUE mesg)
Raises an exception in the current thread.
Definition eval.c:688
void rb_bug(const char *fmt,...)
Interpreter panic switch.
Definition error.c:794
VALUE rb_eTypeError
TypeError exception.
Definition error.c:1091
void rb_warn(const char *fmt,...)
Identical to rb_warning(), except it reports always regardless of runtime -W flag.
Definition error.c:411
VALUE rb_eArgError
ArgumentError exception.
Definition error.c:1092
VALUE rb_eIndexError
IndexError exception.
Definition error.c:1093
VALUE rb_class_superclass(VALUE klass)
Queries the parent of the given class.
Definition object.c:1996
VALUE rb_obj_alloc(VALUE klass)
Allocates an instance of the given class.
Definition object.c:1940
VALUE rb_class_new_instance(int argc, const VALUE *argv, VALUE klass)
Allocates, then initialises an instance of the given class.
Definition object.c:1981
VALUE rb_class_new_instance_kw(int argc, const VALUE *argv, VALUE klass, int kw_splat)
Identical to rb_class_new_instance(), except you can specify how to handle the last element of the gi...
Definition object.c:1969
VALUE rb_mEnumerable
Enumerable module.
Definition enum.c:27
VALUE rb_cStruct
Struct class.
Definition struct.c:34
VALUE rb_class_new_instance_pass_kw(int argc, const VALUE *argv, VALUE klass)
Identical to rb_class_new_instance(), except it passes the passed keywords if any to the #initialize ...
Definition object.c:1958
int rb_eql(VALUE lhs, VALUE rhs)
Checks for equality of the passed objects, in terms of Object#eql?.
Definition object.c:136
VALUE rb_obj_class(VALUE obj)
Queries the class of an object.
Definition object.c:191
VALUE rb_inspect(VALUE obj)
Generates a human-readable textual representation of the given object.
Definition object.c:601
VALUE rb_equal(VALUE lhs, VALUE rhs)
This function is an optimised version of calling #==.
Definition object.c:123
VALUE rb_obj_is_kind_of(VALUE obj, VALUE klass)
Queries if the given object is an instance (of possibly descendants) of the given class.
Definition object.c:788
#define RETURN_SIZED_ENUMERATOR(obj, argc, argv, size_fn)
This roughly resembles return enum_for(__callee__) unless block_given?.
Definition enumerator.h:206
#define UNLIMITED_ARGUMENTS
This macro is used in conjunction with rb_check_arity().
Definition error.h:35
#define rb_check_frozen
Just another name of rb_check_frozen.
Definition error.h:264
static int rb_check_arity(int argc, int min, int max)
Ensures that the passed integer is in the passed range.
Definition error.h:280
int rb_is_const_id(ID id)
Classifies the given ID, then sees if it is a constant.
Definition symbol.c:1031
ID rb_id_attrset(ID id)
Calculates an ID of attribute writer.
Definition symbol.c:118
int rb_is_local_id(ID id)
Classifies the given ID, then sees if it is a local variable.
Definition symbol.c:1061
#define rb_hash_uint(h, i)
Just another name of st_hash_uint.
Definition string.h:942
#define rb_hash_end(h)
Just another name of st_hash_end.
Definition string.h:945
VALUE rb_str_append(VALUE dst, VALUE src)
Identical to rb_str_buf_append(), except it converts the right hand side before concatenating.
Definition string.c:3353
st_index_t rb_hash_start(st_index_t i)
Starts a series of hashing.
Definition random.c:1735
#define rb_str_cat_cstr(buf, str)
Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1656
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 nam...
Definition struct.c:463
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...
Definition struct.c:509
VALUE rb_struct_new(VALUE klass,...)
Creates an instance of the given struct.
Definition struct.c:880
VALUE rb_struct_initialize(VALUE self, VALUE values)
Mass-assigns a struct's fields.
Definition struct.c:806
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.
Definition struct.c:476
VALUE rb_struct_define(const char *name,...)
Defines a struct class.
Definition struct.c:489
VALUE rb_struct_alloc(VALUE klass, VALUE values)
Identical to rb_struct_new(), except it takes the field values as a Ruby array.
Definition struct.c:874
VALUE rb_struct_alloc_noinit(VALUE klass)
Allocates an instance of the given class.
Definition struct.c:406
VALUE rb_struct_s_members(VALUE klass)
Queries the list of the names of the fields of the given struct class.
Definition struct.c:68
VALUE rb_struct_members(VALUE self)
Queries the list of the names of the fields of the class of the given struct object.
Definition struct.c:82
VALUE rb_struct_getmember(VALUE self, ID key)
Identical to rb_struct_aref(), except it takes ID instead of VALUE.
Definition struct.c:233
VALUE rb_exec_recursive(VALUE(*f)(VALUE g, VALUE h, int r), VALUE g, VALUE h)
"Recursion" API entry point.
Definition thread.c:5237
VALUE rb_exec_recursive_paired(VALUE(*f)(VALUE g, VALUE h, int r), VALUE g, VALUE p, VALUE h)
Identical to rb_exec_recursive(), except it checks for the recursion on the ordered pair of { g,...
Definition thread.c:5248
VALUE rb_attr_get(VALUE obj, ID name)
Identical to rb_ivar_get()
Definition variable.c:1226
VALUE rb_ivar_set(VALUE obj, ID name, VALUE val)
Identical to rb_iv_set(), except it accepts the name as an ID instead of a C string.
Definition variable.c:1606
VALUE rb_mod_remove_const(VALUE space, VALUE name)
Resembles Module#remove_const.
Definition variable.c:2988
VALUE rb_class_name(VALUE obj)
Queries the name of the given object's class.
Definition variable.c:310
int rb_const_defined_at(VALUE space, ID name)
Identical to rb_const_defined(), except it doesn't look for parent classes.
Definition variable.c:3210
VALUE rb_class_path(VALUE mod)
Identical to rb_mod_name(), except it returns #<Class: ...> style inspection for anonymous modules.
Definition variable.c:188
VALUE(* rb_alloc_func_t)(VALUE klass)
This is the type of functions that ruby calls when trying to allocate an object.
Definition vm.h:216
void rb_undef_alloc_func(VALUE klass)
Deletes the allocator function of a class.
Definition vm_method.c:1142
VALUE rb_mod_module_eval(int argc, const VALUE *argv, VALUE mod)
Identical to rb_obj_instance_eval(), except it evaluates within the context of module.
Definition vm_eval.c:2151
void rb_define_alloc_func(VALUE klass, rb_alloc_func_t func)
Sets the allocator function of a class.
VALUE rb_check_symbol(volatile VALUE *namep)
Identical to rb_check_id(), except it returns an instance of rb_cSymbol instead.
Definition symbol.c:1140
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition symbol.c:796
VALUE rb_to_symbol(VALUE name)
Identical to rb_intern_str(), except it generates a dynamic symbol if necessary.
Definition string.c:11924
ID rb_to_id(VALUE str)
Identical to rb_intern(), except it takes an instance of rb_cString.
Definition string.c:11914
VALUE rb_yield_values(int n,...)
Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block.
Definition vm_eval.c:1369
VALUE rb_yield(VALUE val)
Yields the block.
Definition vm_eval.c:1357
#define rb_long2int
Just another name of rb_long2int_inline.
Definition long.h:62
#define MEMCPY(p1, p2, type, n)
Handy macro to call memcpy.
Definition memory.h:366
#define RB_GC_GUARD(v)
Prevents premature destruction of local objects.
Definition memory.h:161
void rb_hash_foreach(VALUE q, int_type *w, VALUE e)
Iteration over the given hash.
#define RARRAY_LEN
Just another name of rb_array_len.
Definition rarray.h:68
static int RARRAY_LENINT(VALUE ary)
Identical to rb_array_len(), except it differs for the return type.
Definition rarray.h:343
static VALUE * RARRAY_PTR(VALUE ary)
Wild use of a C pointer.
Definition rarray.h:546
#define RARRAY_AREF(a, i)
Definition rarray.h:583
#define RARRAY_CONST_PTR
Just another name of rb_array_const_ptr.
Definition rarray.h:69
#define RBASIC(obj)
Convenient casting macro.
Definition rbasic.h:40
#define RGENGC_WB_PROTECTED_STRUCT
This is a compile-time flag to enable/disable write barrier for struct RStruct.
Definition rgengc.h:96
#define RHASH_SIZE(h)
Queries the size of the hash.
Definition rhash.h:82
VALUE rb_str_to_str(VALUE obj)
Identical to rb_check_string_type(), except it raises exceptions in case of conversion failures.
Definition string.c:1609
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition rstring.h:498
VALUE rb_struct_aset(VALUE st, VALUE k, VALUE v)
Resembles Struct#[]=.
Definition struct.c:1297
VALUE rb_struct_size(VALUE st)
Returns the number of struct members.
Definition struct.c:1550
VALUE rb_struct_aref(VALUE st, VALUE k)
Resembles Struct#[].
Definition struct.c:1259
#define InitVM(ext)
This macro is for internal use.
Definition ruby.h:230
#define RB_PASS_KEYWORDS
Pass keywords, final argument should be a hash of keywords.
Definition scan_args.h:72
#define RTEST
This is an old name of RB_TEST.
Definition st.h:79
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
static bool RB_TYPE_P(VALUE obj, enum ruby_value_type t)
Queries if the given object is of given type.
Definition value_type.h:375