diff options
Diffstat (limited to 'struct.c')
| -rw-r--r-- | struct.c | 2544 |
1 files changed, 1961 insertions, 583 deletions
@@ -3,888 +3,2222 @@ struct.c - $Author$ - $Date$ created at: Tue Mar 22 18:44:30 JST 1995 - Copyright (C) 1993-2003 Yukihiro Matsumoto + Copyright (C) 1993-2007 Yukihiro Matsumoto **********************************************************************/ -#include "ruby.h" +#include "id.h" +#include "internal.h" +#include "internal/class.h" +#include "internal/error.h" +#include "internal/hash.h" +#include "internal/object.h" +#include "internal/proc.h" +#include "internal/struct.h" +#include "internal/symbol.h" +#include "vm_core.h" +#include "builtin.h" + +/* only for struct[:field] access */ +enum { + AREF_HASH_UNIT = 5, + AREF_HASH_THRESHOLD = 10 +}; +/* Note: Data is a stricter version of the Struct: no attr writers & no + hash-alike/array-alike behavior. It shares most of the implementation + on the C level, but is unrelated on the Ruby level. */ VALUE rb_cStruct; +static VALUE rb_cData; +static ID id_members, id_back_members, id_keyword_init; -static VALUE struct_alloc _((VALUE)); +static VALUE struct_alloc(VALUE); -VALUE -rb_struct_iv_get(c, name) - VALUE c; - char *name; +static inline VALUE +struct_ivar_get(VALUE c, ID id) { - ID id; + VALUE orig = c; + VALUE ivar = rb_attr_get(c, id); + + if (!NIL_P(ivar)) + return ivar; - id = rb_intern(name); for (;;) { - if (rb_ivar_defined(c, id)) - return rb_ivar_get(c, id); - c = RCLASS(c)->super; - if (c == 0 || c == rb_cStruct) - return Qnil; + c = rb_class_superclass(c); + if (c == rb_cStruct || c == rb_cData || !RTEST(c)) + return Qnil; + RUBY_ASSERT(RB_TYPE_P(c, T_CLASS)); + ivar = rb_attr_get(c, id); + if (!NIL_P(ivar)) { + if (!OBJ_FROZEN(orig)) rb_ivar_set(orig, id, ivar); + return ivar; + } + } +} + +VALUE +rb_struct_s_keyword_init(VALUE klass) +{ + return struct_ivar_get(klass, id_keyword_init); +} + +VALUE +rb_struct_s_members(VALUE klass) +{ + VALUE members = struct_ivar_get(klass, id_members); + + if (NIL_P(members)) { + rb_raise(rb_eTypeError, "uninitialized struct"); } + if (!RB_TYPE_P(members, T_ARRAY)) { + rb_raise(rb_eTypeError, "corrupted struct"); + } + return members; +} + +VALUE +rb_struct_members(VALUE s) +{ + VALUE members = rb_struct_s_members(rb_obj_class(s)); + + if (RSTRUCT_LEN_RAW(s) != RARRAY_LEN(members)) { + rb_raise(rb_eTypeError, "struct size differs (%ld required %ld given)", + RARRAY_LEN(members), RSTRUCT_LEN_RAW(s)); + } + return members; +} + +static long +struct_member_pos_ideal(VALUE name, long mask) +{ + /* (id & (mask/2)) * 2 */ + return (SYM2ID(name) >> (ID_SCOPE_SHIFT - 1)) & mask; +} + +static long +struct_member_pos_probe(long prev, long mask) +{ + /* (((prev/2) * AREF_HASH_UNIT + 1) & (mask/2)) * 2 */ + return (prev * AREF_HASH_UNIT + 2) & mask; } static VALUE -rb_struct_s_members(obj) - VALUE obj; +struct_set_members(VALUE klass, VALUE /* frozen hidden array */ members) { - VALUE member, ary; - VALUE *p, *pend; + VALUE back; + const long members_length = RARRAY_LEN(members); - member = rb_struct_iv_get(obj, "__member__"); - if (NIL_P(member)) { - rb_bug("uninitialized struct"); + if (members_length <= AREF_HASH_THRESHOLD) { + back = members; } - ary = rb_ary_new2(RARRAY(member)->len); - p = RARRAY(member)->ptr; pend = p + RARRAY(member)->len; - while (p < pend) { - rb_ary_push(ary, rb_str_new2(rb_id2name(SYM2ID(*p)))); - p++; + else { + long i, j, mask = 64; + VALUE name; + + while (mask < members_length * AREF_HASH_UNIT) mask *= 2; + + back = rb_ary_hidden_new(mask + 1); + rb_ary_store(back, mask, INT2FIX(members_length)); + mask -= 2; /* mask = (2**k-1)*2 */ + + for (i=0; i < members_length; i++) { + name = RARRAY_AREF(members, i); + + j = struct_member_pos_ideal(name, mask); + + for (;;) { + if (!RTEST(RARRAY_AREF(back, j))) { + rb_ary_store(back, j, name); + rb_ary_store(back, j + 1, INT2FIX(i)); + break; + } + j = struct_member_pos_probe(j, mask); + } + } + OBJ_FREEZE(back); } + rb_ivar_set(klass, id_members, members); + rb_ivar_set(klass, id_back_members, back); - return ary; + return members; +} + +static inline int +struct_member_pos(VALUE s, VALUE name) +{ + VALUE back = struct_ivar_get(rb_obj_class(s), id_back_members); + long j, mask; + + if (UNLIKELY(NIL_P(back))) { + rb_raise(rb_eTypeError, "uninitialized struct"); + } + if (UNLIKELY(!RB_TYPE_P(back, T_ARRAY))) { + rb_raise(rb_eTypeError, "corrupted struct"); + } + + mask = RARRAY_LEN(back); + + if (mask <= AREF_HASH_THRESHOLD) { + if (UNLIKELY(RSTRUCT_LEN_RAW(s) != mask)) { + rb_raise(rb_eTypeError, + "struct size differs (%ld required %ld given)", + mask, RSTRUCT_LEN_RAW(s)); + } + for (j = 0; j < mask; j++) { + if (RARRAY_AREF(back, j) == name) + return (int)j; + } + return -1; + } + + if (UNLIKELY(RSTRUCT_LEN_RAW(s) != FIX2INT(RARRAY_AREF(back, mask-1)))) { + rb_raise(rb_eTypeError, "struct size differs (%d required %ld given)", + FIX2INT(RARRAY_AREF(back, mask-1)), RSTRUCT_LEN_RAW(s)); + } + + mask -= 3; + j = struct_member_pos_ideal(name, mask); + + for (;;) { + VALUE e = RARRAY_AREF(back, j); + if (e == name) + return FIX2INT(RARRAY_AREF(back, j + 1)); + if (!RTEST(e)) { + return -1; + } + j = struct_member_pos_probe(j, mask); + } +} + +/* + * call-seq: + * StructClass::members -> array_of_symbols + * + * Returns the member names of the Struct descendant as an array: + * + * Customer = Struct.new(:name, :address, :zip) + * Customer.members # => [:name, :address, :zip] + * + */ + +static VALUE +rb_struct_s_members_m(VALUE klass) +{ + VALUE members = rb_struct_s_members(klass); + + return rb_ary_dup(members); } /* * call-seq: - * struct.members => array - * - * Returns an array of strings representing the names of the instance - * variables. - * + * members -> array_of_symbols + * + * Returns the member names from +self+ as an array: + * * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.members #=> ["name", "address", "zip"] + * Customer.new.members # => [:name, :address, :zip] + * + * Related: #to_a. */ static VALUE -rb_struct_members(obj) - VALUE obj; +rb_struct_members_m(VALUE obj) { - return rb_struct_s_members(rb_obj_class(obj)); + return rb_struct_s_members_m(rb_obj_class(obj)); } VALUE -rb_struct_getmember(obj, id) - VALUE obj; - ID id; +rb_struct_getmember(VALUE obj, ID id) { - VALUE member, slot; - long i; + VALUE slot = ID2SYM(id); + int i = struct_member_pos(obj, slot); + if (i != -1) { + return RSTRUCT_GET_RAW(obj, i); + } + rb_name_err_raise("'%1$s' is not a struct member", obj, ID2SYM(id)); - member = rb_struct_iv_get(rb_obj_class(obj), "__member__"); - if (NIL_P(member)) { - rb_bug("uninitialized struct"); - } - slot = ID2SYM(id); - for (i=0; i<RARRAY(member)->len; i++) { - if (RARRAY(member)->ptr[i] == slot) { - return RSTRUCT(obj)->ptr[i]; - } - } - rb_name_error(id, "%s is not struct member", rb_id2name(id)); - return Qnil; /* not reached */ -} - -static VALUE -rb_struct_ref(obj) - VALUE obj; -{ - return rb_struct_getmember(obj, rb_frame_last_func()); -} - -static VALUE rb_struct_ref0(obj) VALUE obj; {return RSTRUCT(obj)->ptr[0];} -static VALUE rb_struct_ref1(obj) VALUE obj; {return RSTRUCT(obj)->ptr[1];} -static VALUE rb_struct_ref2(obj) VALUE obj; {return RSTRUCT(obj)->ptr[2];} -static VALUE rb_struct_ref3(obj) VALUE obj; {return RSTRUCT(obj)->ptr[3];} -static VALUE rb_struct_ref4(obj) VALUE obj; {return RSTRUCT(obj)->ptr[4];} -static VALUE rb_struct_ref5(obj) VALUE obj; {return RSTRUCT(obj)->ptr[5];} -static VALUE rb_struct_ref6(obj) VALUE obj; {return RSTRUCT(obj)->ptr[6];} -static VALUE rb_struct_ref7(obj) VALUE obj; {return RSTRUCT(obj)->ptr[7];} -static VALUE rb_struct_ref8(obj) VALUE obj; {return RSTRUCT(obj)->ptr[8];} -static VALUE rb_struct_ref9(obj) VALUE obj; {return RSTRUCT(obj)->ptr[9];} - -static VALUE (*ref_func[10])() = { - rb_struct_ref0, - rb_struct_ref1, - rb_struct_ref2, - rb_struct_ref3, - rb_struct_ref4, - rb_struct_ref5, - rb_struct_ref6, - rb_struct_ref7, - rb_struct_ref8, - rb_struct_ref9, -}; + UNREACHABLE_RETURN(Qnil); +} static void -rb_struct_modify(s) - VALUE s; +rb_struct_modify(VALUE s) { - if (OBJ_FROZEN(s)) rb_error_frozen("Struct"); - if (!OBJ_TAINTED(s) && rb_safe_level() >= 4) - rb_raise(rb_eSecurityError, "Insecure: can't modify Struct"); + rb_check_frozen(s); } static VALUE -rb_struct_set(obj, val) - VALUE obj, val; +anonymous_struct(VALUE klass) { - VALUE member, slot; - long i; + VALUE nstr; - member = rb_struct_iv_get(rb_obj_class(obj), "__member__"); - if (NIL_P(member)) { - rb_bug("uninitialized struct"); + nstr = rb_class_new(klass); + rb_make_metaclass(nstr, RBASIC(klass)->klass); + rb_class_inherited(klass, nstr); + return nstr; +} + +static VALUE +new_struct(VALUE name, VALUE super) +{ + /* old style: should we warn? */ + ID id; + name = rb_str_to_str(name); + if (!rb_is_const_name(name)) { + rb_name_err_raise("identifier %1$s needs to be constant", + super, name); } - rb_struct_modify(obj); - for (i=0; i<RARRAY(member)->len; i++) { - slot = RARRAY(member)->ptr[i]; - if (rb_id_attrset(SYM2ID(slot)) == rb_frame_last_func()) { - return RSTRUCT(obj)->ptr[i] = val; - } + id = rb_to_id(name); + if (rb_const_defined_at(super, id)) { + rb_warn("redefining constant %"PRIsVALUE"::%"PRIsVALUE, super, name); + rb_mod_remove_const(super, ID2SYM(id)); } - rb_name_error(rb_frame_last_func(), "`%s' is not a struct member", - rb_id2name(rb_frame_last_func())); - return Qnil; /* not reached */ + return rb_define_class_id_under_no_pin(super, id, super); +} + +NORETURN(static void invalid_struct_pos(VALUE s, VALUE idx)); + +static void +define_aref_method(VALUE nstr, VALUE name, VALUE off) +{ + rb_add_method_optimized(nstr, SYM2ID(name), OPTIMIZED_METHOD_TYPE_STRUCT_AREF, FIX2UINT(off), METHOD_VISI_PUBLIC); +} + +static void +define_aset_method(VALUE nstr, VALUE name, VALUE off) +{ + rb_add_method_optimized(nstr, SYM2ID(name), OPTIMIZED_METHOD_TYPE_STRUCT_ASET, FIX2UINT(off), METHOD_VISI_PUBLIC); } static VALUE -make_struct(name, member, klass) - VALUE name, member, klass; +rb_struct_s_inspect(VALUE klass) { - VALUE nstr; - ID id; - long i; + VALUE inspect = rb_class_name(klass); + if (RTEST(rb_struct_s_keyword_init(klass))) { + rb_str_cat_cstr(inspect, "(keyword_init: true)"); + } + return inspect; +} - if (NIL_P(name)) { - nstr = rb_class_new(klass); - rb_make_metaclass(nstr, RBASIC(klass)->klass); - rb_class_inherited(klass, nstr); +static VALUE +rb_data_s_new(int argc, const VALUE *argv, VALUE klass) +{ + if (rb_keyword_given_p()) { + if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) { + rb_error_arity(argc, 0, 0); + } + return rb_class_new_instance_pass_kw(argc, argv, klass); } else { - char *cname = StringValuePtr(name); - id = rb_intern(cname); - if (!rb_is_const_id(id)) { - rb_name_error(id, "identifier %s needs to be constant", cname); - } - nstr = rb_define_class_under(klass, cname, klass); + VALUE members = struct_ivar_get(klass, id_members); + int num_members = RARRAY_LENINT(members); + + rb_check_arity(argc, 0, num_members); + VALUE arg_hash = rb_hash_new_with_size(argc); + for (long i=0; i<argc; i++) { + VALUE k = rb_ary_entry(members, i), v = argv[i]; + rb_hash_aset(arg_hash, k, v); + } + return rb_class_new_instance_kw(1, &arg_hash, klass, RB_PASS_KEYWORDS); } - rb_iv_set(nstr, "__size__", LONG2NUM(RARRAY(member)->len)); - rb_iv_set(nstr, "__member__", member); +} + +#if 0 /* for RDoc */ + +/* + * call-seq: + * StructClass::keyword_init? -> true or falsy value + * + * Returns +true+ if the class was initialized with <tt>keyword_init: true</tt>. + * Otherwise returns +nil+ or +false+. + * + * Examples: + * Foo = Struct.new(:a) + * Foo.keyword_init? # => nil + * Bar = Struct.new(:a, keyword_init: true) + * Bar.keyword_init? # => true + * Baz = Struct.new(:a, keyword_init: false) + * Baz.keyword_init? # => false + */ +static VALUE +rb_struct_s_keyword_init_p(VALUE obj) +{ +} +#endif + +#define rb_struct_s_keyword_init_p rb_struct_s_keyword_init + +static VALUE +setup_struct(VALUE nstr, VALUE members) +{ + long i, len; + + members = struct_set_members(nstr, members); rb_define_alloc_func(nstr, struct_alloc); - rb_define_singleton_method(nstr, "new", rb_class_new_instance, -1); - rb_define_singleton_method(nstr, "[]", rb_class_new_instance, -1); - rb_define_singleton_method(nstr, "members", rb_struct_s_members, 0); - for (i=0; i< RARRAY(member)->len; i++) { - ID id = SYM2ID(RARRAY(member)->ptr[i]); - if (i<10) { - rb_define_method_id(nstr, id, ref_func[i], 0); - } - else { - rb_define_method_id(nstr, id, rb_struct_ref, 0); - } - rb_define_method_id(nstr, rb_id_attrset(id), rb_struct_set, 1); + rb_define_singleton_method(nstr, "new", rb_class_new_instance_pass_kw, -1); + rb_define_singleton_method(nstr, "[]", rb_class_new_instance_pass_kw, -1); + rb_define_singleton_method(nstr, "members", rb_struct_s_members_m, 0); + rb_define_singleton_method(nstr, "inspect", rb_struct_s_inspect, 0); + rb_define_singleton_method(nstr, "keyword_init?", rb_struct_s_keyword_init_p, 0); + + len = RARRAY_LEN(members); + for (i=0; i< len; i++) { + VALUE sym = RARRAY_AREF(members, i); + ID id = SYM2ID(sym); + VALUE off = LONG2NUM(i); + + define_aref_method(nstr, sym, off); + define_aset_method(nstr, ID2SYM(rb_id_attrset(id)), off); } return nstr; } -#ifdef HAVE_STDARG_PROTOTYPES -#include <stdarg.h> -#define va_init_list(a,b) va_start(a,b) -#else -#include <varargs.h> -#define va_init_list(a,b) va_start(a) -#endif +static VALUE +setup_data(VALUE subclass, VALUE members) +{ + long i, len; + + members = struct_set_members(subclass, members); + + rb_define_alloc_func(subclass, struct_alloc); + VALUE sclass = rb_singleton_class(subclass); + rb_undef_method(sclass, "define"); + rb_define_method(sclass, "new", rb_data_s_new, -1); + rb_define_method(sclass, "[]", rb_data_s_new, -1); + rb_define_method(sclass, "members", rb_struct_s_members_m, 0); + rb_define_method(sclass, "inspect", rb_struct_s_inspect, 0); // FIXME: just a separate method?.. + + len = RARRAY_LEN(members); + for (i=0; i< len; i++) { + VALUE sym = RARRAY_AREF(members, i); + VALUE off = LONG2NUM(i); + + define_aref_method(subclass, sym, off); + } + + return subclass; +} + +VALUE +rb_struct_alloc_noinit(VALUE klass) +{ + return struct_alloc(klass); +} + +static VALUE +struct_make_members_list(va_list ar) +{ + char *mem; + VALUE ary, list = rb_ident_hash_new(); + RBASIC_CLEAR_CLASS(list); + while ((mem = va_arg(ar, char*)) != 0) { + VALUE sym = rb_sym_intern_ascii_cstr(mem); + if (RTEST(rb_hash_has_key(list, sym))) { + rb_raise(rb_eArgError, "duplicate member: %s", mem); + } + rb_hash_aset(list, sym, Qtrue); + } + ary = rb_hash_keys(list); + RBASIC_CLEAR_CLASS(ary); + OBJ_FREEZE(ary); + return ary; +} + +static VALUE +struct_define_without_accessor(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, VALUE members) +{ + VALUE klass; + + if (class_name) { + if (outer) { + klass = rb_define_class_under(outer, class_name, super); + } + else { + klass = rb_define_class(class_name, super); + } + } + else { + klass = anonymous_struct(super); + } + + struct_set_members(klass, members); + + if (alloc) { + rb_define_alloc_func(klass, alloc); + } + else { + rb_define_alloc_func(klass, struct_alloc); + } + + return klass; +} + +VALUE +rb_struct_define_without_accessor_under(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, ...) +{ + va_list ar; + VALUE members; + + va_start(ar, alloc); + members = struct_make_members_list(ar); + va_end(ar); + + return struct_define_without_accessor(outer, class_name, super, alloc, members); +} + +VALUE +rb_struct_define_without_accessor(const char *class_name, VALUE super, rb_alloc_func_t alloc, ...) +{ + va_list ar; + VALUE members; + + va_start(ar, alloc); + members = struct_make_members_list(ar); + va_end(ar); + + return struct_define_without_accessor(0, class_name, super, alloc, members); +} VALUE -#ifdef HAVE_STDARG_PROTOTYPES rb_struct_define(const char *name, ...) -#else -rb_struct_define(name, va_alist) - const char *name; - va_dcl -#endif { va_list ar; - VALUE nm, ary; - char *mem; + VALUE st, ary; - if (!name) nm = Qnil; - else nm = rb_str_new2(name); - ary = rb_ary_new(); + va_start(ar, name); + ary = struct_make_members_list(ar); + va_end(ar); - va_init_list(ar, name); - while (mem = va_arg(ar, char*)) { - ID slot = rb_intern(mem); - rb_ary_push(ary, ID2SYM(slot)); + if (!name) { + st = anonymous_struct(rb_cStruct); + } + else { + st = new_struct(rb_str_new2(name), rb_cStruct); + rb_vm_register_global_object(st); } + return setup_struct(st, ary); +} + +VALUE +rb_struct_define_under(VALUE outer, const char *name, ...) +{ + va_list ar; + VALUE ary; + + va_start(ar, name); + ary = struct_make_members_list(ar); va_end(ar); - return make_struct(nm, ary, rb_cStruct); + return setup_struct(rb_define_class_id_under(outer, rb_intern(name), rb_cStruct), ary); } /* * call-seq: - * Struct.new( [aString] [, aSym]+> ) => StructClass - * StructClass.new(arg, ...) => obj - * StructClass[arg, ...] => obj - * - * Creates a new class, named by <i>aString</i>, containing accessor - * methods for the given symbols. If the name <i>aString</i> is - * omitted, an anonymous structure class will be created. Otherwise, - * the name of this struct will appear as a constant in class - * <code>Struct</code>, so it must be unique for all - * <code>Struct</code>s in the system and should start with a capital - * letter. Assigning a structure class to a constant effectively gives - * the class the name of the constant. - * - * <code>Struct::new</code> returns a new <code>Class</code> object, - * which can then be used to create specific instances of the new - * structure. The number of actual parameters must be - * less than or equal to the number of attributes defined for this - * class; unset parameters default to \nil{}. Passing too many - * parameters will raise an \E{ArgumentError}. - * - * The remaining methods listed in this section (class and instance) - * are defined for this generated class. - * - * # Create a structure with a name in Struct - * Struct.new("Customer", :name, :address) #=> Struct::Customer - * Struct::Customer.new("Dave", "123 Main") #=> #<Struct::Customer name="Dave", address="123 Main"> - * - * # Create a structure named by its constant - * Customer = Struct.new(:name, :address) #=> Customer - * Customer.new("Dave", "123 Main") #=> #<Customer name="Dave", address="123 Main"> - */ - -static VALUE -rb_struct_s_def(argc, argv, klass) - int argc; - VALUE *argv; - VALUE klass; + * Struct.new(*member_names, keyword_init: nil){|Struct_subclass| ... } -> Struct_subclass + * Struct.new(class_name, *member_names, keyword_init: nil){|Struct_subclass| ... } -> Struct_subclass + * Struct_subclass.new(*member_names) -> Struct_subclass_instance + * Struct_subclass.new(**member_names) -> Struct_subclass_instance + * + * <tt>Struct.new</tt> returns a new subclass of +Struct+. The new subclass: + * + * - May be anonymous, or may have the name given by +class_name+. + * - May have members as given by +member_names+. + * - May have initialization via ordinary arguments, or via keyword arguments + * + * The new subclass has its own method <tt>::new</tt>; thus: + * + * Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo + * f = Foo.new(0, 1) # => #<struct Struct::Foo foo=0, bar=1> + * + * <b>Class Name</b> + * + * With string argument +class_name+, + * returns a new subclass of +Struct+ named <tt>Struct::<em>class_name</em></tt>: + * + * Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo + * Foo.name # => "Struct::Foo" + * Foo.superclass # => Struct + * + * Without string argument +class_name+, + * returns a new anonymous subclass of +Struct+: + * + * Struct.new(:foo, :bar).name # => nil + * + * <b>Block</b> + * + * With a block given, the created subclass is yielded to the block: + * + * Customer = Struct.new('Customer', :name, :address) do |new_class| + * p "The new subclass is #{new_class}" + * def greeting + * "Hello #{name} at #{address}" + * end + * end # => Struct::Customer + * dave = Customer.new('Dave', '123 Main') + * dave # => #<struct Struct::Customer name="Dave", address="123 Main"> + * dave.greeting # => "Hello Dave at 123 Main" + * + * Output, from <tt>Struct.new</tt>: + * + * "The new subclass is Struct::Customer" + * + * <b>Member Names</b> + * + * Symbol arguments +member_names+ + * determines the members of the new subclass: + * + * Struct.new(:foo, :bar).members # => [:foo, :bar] + * Struct.new('Foo', :foo, :bar).members # => [:foo, :bar] + * + * The new subclass has instance methods corresponding to +member_names+: + * + * Foo = Struct.new('Foo', :foo, :bar) + * Foo.instance_methods(false) # => [:foo, :bar, :foo=, :bar=] + * f = Foo.new # => #<struct Struct::Foo foo=nil, bar=nil> + * f.foo # => nil + * f.foo = 0 # => 0 + * f.bar # => nil + * f.bar = 1 # => 1 + * f # => #<struct Struct::Foo foo=0, bar=1> + * + * <b>Singleton Methods</b> + * + * A subclass returned by Struct.new has these singleton methods: + * + * - Method <tt>::new </tt> creates an instance of the subclass: + * + * Foo.new # => #<struct Struct::Foo foo=nil, bar=nil> + * Foo.new(0) # => #<struct Struct::Foo foo=0, bar=nil> + * Foo.new(0, 1) # => #<struct Struct::Foo foo=0, bar=1> + * Foo.new(0, 1, 2) # Raises ArgumentError: struct size differs + * + * # Initialization with keyword arguments: + * Foo.new(foo: 0) # => #<struct Struct::Foo foo=0, bar=nil> + * Foo.new(foo: 0, bar: 1) # => #<struct Struct::Foo foo=0, bar=1> + * Foo.new(foo: 0, bar: 1, baz: 2) + * # Raises ArgumentError: unknown keywords: baz + * + * - Method <tt>:inspect</tt> returns a string representation of the subclass: + * + * Foo.inspect + * # => "Struct::Foo" + * + * - Method <tt>::members</tt> returns an array of the member names: + * + * Foo.members # => [:foo, :bar] + * + * <b>Keyword Argument</b> + * + * By default, the arguments for initializing an instance of the new subclass + * can be both positional and keyword arguments. + * + * Optional keyword argument <tt>keyword_init:</tt> allows to force only one + * type of arguments to be accepted: + * + * KeywordsOnly = Struct.new(:foo, :bar, keyword_init: true) + * KeywordsOnly.new(bar: 1, foo: 0) + * # => #<struct KeywordsOnly foo=0, bar=1> + * KeywordsOnly.new(0, 1) + * # Raises ArgumentError: wrong number of arguments + * + * PositionalOnly = Struct.new(:foo, :bar, keyword_init: false) + * PositionalOnly.new(0, 1) + * # => #<struct PositionalOnly foo=0, bar=1> + * PositionalOnly.new(bar: 1, foo: 0) + * # => #<struct PositionalOnly foo={:foo=>1, :bar=>2}, bar=nil> + * # Note that no error is raised, but arguments treated as one hash value + * + * # Same as not providing keyword_init: + * Any = Struct.new(:foo, :bar, keyword_init: nil) + * Any.new(foo: 1, bar: 2) + * # => #<struct Any foo=1, bar=2> + * Any.new(1, 2) + * # => #<struct Any foo=1, bar=2> + */ + +static VALUE +rb_struct_s_def(int argc, VALUE *argv, VALUE klass) { - VALUE name, rest; + VALUE name = Qnil, rest, keyword_init = Qnil; long i; VALUE st; - ID id; + VALUE opt; + + argc = rb_scan_args(argc, argv, "0*:", NULL, &opt); + if (argc >= 1 && !SYMBOL_P(argv[0])) { + name = argv[0]; + --argc; + ++argv; + } - rb_scan_args(argc, argv, "1*", &name, &rest); - for (i=0; i<RARRAY(rest)->len; i++) { - id = rb_to_id(RARRAY(rest)->ptr[i]); - RARRAY(rest)->ptr[i] = ID2SYM(id); + if (!NIL_P(opt)) { + static ID keyword_ids[1]; + + if (!keyword_ids[0]) { + keyword_ids[0] = rb_intern("keyword_init"); + } + rb_get_kwargs(opt, keyword_ids, 0, 1, &keyword_init); + if (UNDEF_P(keyword_init)) { + keyword_init = Qnil; + } + else if (RTEST(keyword_init)) { + keyword_init = Qtrue; + } } - if (!NIL_P(name)) { - VALUE tmp = rb_check_string_type(name); - if (NIL_P(tmp)) { - id = rb_to_id(name); - rb_ary_unshift(rest, ID2SYM(id)); - name = Qnil; - } + rest = rb_ident_hash_new(); + RBASIC_CLEAR_CLASS(rest); + for (i=0; i<argc; i++) { + VALUE mem = rb_to_symbol(argv[i]); + if (rb_is_attrset_sym(mem)) { + rb_raise(rb_eArgError, "invalid struct member: %"PRIsVALUE, mem); + } + if (RTEST(rb_hash_has_key(rest, mem))) { + rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem); + } + rb_hash_aset(rest, mem, Qtrue); + } + rest = rb_hash_keys(rest); + RBASIC_CLEAR_CLASS(rest); + OBJ_FREEZE(rest); + if (NIL_P(name)) { + st = anonymous_struct(klass); } - st = make_struct(name, rest, klass); + else { + st = new_struct(name, klass); + } + setup_struct(st, rest); + rb_ivar_set(st, id_keyword_init, keyword_init); if (rb_block_given_p()) { - rb_mod_module_eval(0, 0, st); + rb_mod_module_eval(0, 0, st); } return st; } +static long +num_members(VALUE klass) +{ + VALUE members; + members = struct_ivar_get(klass, id_members); + if (!RB_TYPE_P(members, T_ARRAY)) { + rb_raise(rb_eTypeError, "broken members"); + } + return RARRAY_LEN(members); +} + /* */ +struct struct_hash_set_arg { + VALUE self; + VALUE unknown_keywords; +}; + +static int rb_struct_pos(VALUE s, VALUE *name); + +static int +struct_hash_set_i(VALUE key, VALUE val, VALUE arg) +{ + struct struct_hash_set_arg *args = (struct struct_hash_set_arg *)arg; + int i = rb_struct_pos(args->self, &key); + if (i < 0) { + if (NIL_P(args->unknown_keywords)) { + args->unknown_keywords = rb_ary_new(); + } + rb_ary_push(args->unknown_keywords, key); + } + else { + rb_struct_modify(args->self); + RSTRUCT_SET_RAW(args->self, i, val); + } + return ST_CONTINUE; +} + static VALUE -rb_struct_initialize(self, values) - VALUE self, values; +rb_struct_initialize_m(int argc, const VALUE *argv, VALUE self) { VALUE klass = rb_obj_class(self); - VALUE size; - long n; - rb_struct_modify(self); - size = rb_struct_iv_get(klass, "__size__"); - n = FIX2LONG(size); - if (n < RARRAY(values)->len) { - rb_raise(rb_eArgError, "struct size differs"); + long n = num_members(klass); + if (argc == 0) { + rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), n); + return Qnil; + } + + bool keyword_init = false; + switch (rb_struct_s_keyword_init(klass)) { + default: + if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) { + rb_error_arity(argc, 0, 0); + } + keyword_init = true; + break; + case Qfalse: + break; + case Qnil: + if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) { + break; + } + keyword_init = rb_keyword_given_p(); + break; } - MEMCPY(RSTRUCT(self)->ptr, RARRAY(values)->ptr, VALUE, RARRAY(values)->len); - if (n > RARRAY(values)->len) { - rb_mem_clear(RSTRUCT(self)->ptr+RARRAY(values)->len, - n-RARRAY(values)->len); + if (keyword_init) { + struct struct_hash_set_arg arg; + rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), n); + arg.self = self; + arg.unknown_keywords = Qnil; + rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg); + if (arg.unknown_keywords != Qnil) { + rb_raise(rb_eArgError, "unknown keywords: %s", + RSTRING_PTR(rb_ary_join(arg.unknown_keywords, rb_str_new2(", ")))); + } + } + else { + if (n < argc) { + rb_raise(rb_eArgError, "struct size differs"); + } + for (long i=0; i<argc; i++) { + RSTRUCT_SET_RAW(self, i, argv[i]); + } + if (n > argc) { + rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self)+argc, n-argc); + } } return Qnil; } +VALUE +rb_struct_initialize(VALUE self, VALUE values) +{ + rb_struct_initialize_m(RARRAY_LENINT(values), RARRAY_CONST_PTR(values), self); + if (rb_obj_is_kind_of(self, rb_cData)) OBJ_FREEZE(self); + RB_GC_GUARD(values); + return Qnil; +} + +static VALUE * +struct_heap_alloc(VALUE st, size_t len) +{ + return ALLOC_N(VALUE, len); +} + static VALUE -struct_alloc(klass) - VALUE klass; +struct_alloc(VALUE klass) { - VALUE size; - long n; - NEWOBJ(st, struct RStruct); - OBJSETUP(st, klass, T_STRUCT); + long n = num_members(klass); + size_t embedded_size = offsetof(struct RStruct, as.ary) + (sizeof(VALUE) * n); + if (RCLASS_MAX_IV_COUNT(klass) > 0) { + embedded_size += sizeof(VALUE); + } - size = rb_struct_iv_get(klass, "__size__"); - n = FIX2LONG(size); + VALUE flags = T_STRUCT | (RGENGC_WB_PROTECTED_STRUCT ? FL_WB_PROTECTED : 0); + + if (n > 0 && rb_gc_size_allocatable_p(embedded_size)) { + flags |= n << RSTRUCT_EMBED_LEN_SHIFT; + if (RCLASS_MAX_IV_COUNT(klass) == 0) { + // We set the flag before calling `NEWOBJ_OF` in case a NEWOBJ tracepoint does + // attempt to write fields. We'll remove it later if no fields was written to. + flags |= RSTRUCT_GEN_FIELDS; + } + + NEWOBJ_OF(st, struct RStruct, klass, flags, embedded_size, 0); + if (RCLASS_MAX_IV_COUNT(klass) == 0) { + if (!rb_shape_obj_has_fields((VALUE)st) + && embedded_size < rb_gc_obj_slot_size((VALUE)st)) { + FL_UNSET_RAW((VALUE)st, RSTRUCT_GEN_FIELDS); + RSTRUCT_SET_FIELDS_OBJ((VALUE)st, 0); + } + } + else { + RSTRUCT_SET_FIELDS_OBJ((VALUE)st, 0); + } + + rb_mem_clear((VALUE *)st->as.ary, n); + + return (VALUE)st; + } + else { + NEWOBJ_OF(st, struct RStruct, klass, flags, sizeof(struct RStruct), 0); - st->ptr = ALLOC_N(VALUE, n); - rb_mem_clear(st->ptr, n); - st->len = n; + st->as.heap.ptr = NULL; + st->as.heap.fields_obj = 0; + st->as.heap.len = 0; - return (VALUE)st; + st->as.heap.ptr = struct_heap_alloc((VALUE)st, n); + rb_mem_clear((VALUE *)st->as.heap.ptr, n); + st->as.heap.len = n; + + return (VALUE)st; + } } VALUE -rb_struct_alloc(klass, values) - VALUE klass, values; +rb_struct_alloc(VALUE klass, VALUE values) { - return rb_class_new_instance(RARRAY(values)->len, RARRAY(values)->ptr, klass); + return rb_class_new_instance(RARRAY_LENINT(values), RARRAY_CONST_PTR(values), klass); } VALUE -#ifdef HAVE_STDARG_PROTOTYPES rb_struct_new(VALUE klass, ...) -#else -rb_struct_new(klass, va_alist) - VALUE klass; - va_dcl -#endif { - VALUE sz, *mem; - long size, i; + VALUE tmpargs[16], *mem = tmpargs; + int size, i; va_list args; - sz = rb_struct_iv_get(klass, "__size__"); - size = FIX2LONG(sz); - mem = ALLOCA_N(VALUE, size); - va_init_list(args, klass); + size = rb_long2int(num_members(klass)); + if (size > numberof(tmpargs)) { + tmpargs[0] = rb_ary_hidden_new(size); + mem = RARRAY_PTR(tmpargs[0]); + } + va_start(args, klass); for (i=0; i<size; i++) { - mem[i] = va_arg(args, VALUE); + mem[i] = va_arg(args, VALUE); } va_end(args); return rb_class_new_instance(size, mem, klass); } +static VALUE +struct_enum_size(VALUE s, VALUE args, VALUE eobj) +{ + return rb_struct_size(s); +} + /* * call-seq: - * struct.each {|obj| block } => struct - * - * Calls <i>block</i> once for each instance variable, passing the - * value as a parameter. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.each {|x| puts(x) } - * - * <em>produces:</em> - * - * Joe Smith - * 123 Maple, Anytown NC - * 12345 + * each {|value| ... } -> self + * each -> enumerator + * + * Calls the given block with the value of each member; returns +self+: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.each {|value| p value } + * + * Output: + * + * "Joe Smith" + * "123 Maple, Anytown NC" + * 12345 + * + * Returns an Enumerator if no block is given. + * + * Related: #each_pair. */ static VALUE -rb_struct_each(s) - VALUE s; +rb_struct_each(VALUE s) { long i; - for (i=0; i<RSTRUCT(s)->len; i++) { - rb_yield(RSTRUCT(s)->ptr[i]); + RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size); + for (i=0; i<RSTRUCT_LEN_RAW(s); i++) { + rb_yield(RSTRUCT_GET_RAW(s, i)); } return s; } /* * call-seq: - * struct.each_pair {|sym, obj| block } => struct - * - * Calls <i>block</i> once for each instance variable, passing the name - * (as a symbol) and the value as parameters. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.each_pair {|name, value| puts("#{name} => #{value}") } - * - * <em>produces:</em> - * - * name => Joe Smith - * address => 123 Maple, Anytown NC - * zip => 12345 + * each_pair {|(name, value)| ... } -> self + * each_pair -> enumerator + * + * Calls the given block with each member name/value pair; returns +self+: + * + * Customer = Struct.new(:name, :address, :zip) # => Customer + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.each_pair {|(name, value)| p "#{name} => #{value}" } + * + * Output: + * + * "name => Joe Smith" + * "address => 123 Maple, Anytown NC" + * "zip => 12345" + * + * Returns an Enumerator if no block is given. + * + * Related: #each. + * */ static VALUE -rb_struct_each_pair(s) - VALUE s; +rb_struct_each_pair(VALUE s) { - VALUE member; + VALUE members; long i; - member = rb_struct_iv_get(rb_obj_class(s), "__member__"); - if (NIL_P(member)) { - rb_bug("non-initialized struct"); + RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size); + members = rb_struct_members(s); + if (rb_block_pair_yield_optimizable()) { + for (i=0; i<RSTRUCT_LEN_RAW(s); i++) { + VALUE key = rb_ary_entry(members, i); + VALUE value = RSTRUCT_GET_RAW(s, i); + rb_yield_values(2, key, value); + } } - for (i=0; i<RSTRUCT(s)->len; i++) { - rb_yield_values(2, RARRAY(member)->ptr[i], RSTRUCT(s)->ptr[i]); + else { + for (i=0; i<RSTRUCT_LEN_RAW(s); i++) { + VALUE key = rb_ary_entry(members, i); + VALUE value = RSTRUCT_GET_RAW(s, i); + rb_yield(rb_assoc_new(key, value)); + } } return s; } static VALUE -inspect_struct(s) - VALUE s; +inspect_struct(VALUE s, VALUE prefix, int recur) { - char *cname = rb_class2name(rb_obj_class(s)); - VALUE str, member; - long i; + VALUE cname = rb_class_path(rb_obj_class(s)); + VALUE members; + VALUE str = prefix; + long i, len; + char first = RSTRING_PTR(cname)[0]; - member = rb_struct_iv_get(rb_obj_class(s), "__member__"); - if (NIL_P(member)) { - rb_bug("non-initialized struct"); + if (recur || first != '#') { + rb_str_cat2(str, " "); + rb_str_append(str, cname); + } + if (recur) { + return rb_str_cat2(str, ":...>"); } - str = rb_str_buf_new2("#<struct "); - rb_str_cat2(str, cname); - rb_str_cat2(str, " "); - for (i=0; i<RSTRUCT(s)->len; i++) { - VALUE str2, slot; - char *p; + members = rb_struct_members(s); + len = RSTRUCT_LEN_RAW(s); - if (i > 0) { - rb_str_cat2(str, ", "); - } - slot = RARRAY(member)->ptr[i]; - p = rb_id2name(SYM2ID(slot)); - rb_str_cat2(str, p); - rb_str_cat2(str, "="); - str2 = rb_inspect(RSTRUCT(s)->ptr[i]); - rb_str_append(str, str2); + for (i=0; i<len; i++) { + VALUE slot; + ID id; + + if (i > 0) { + rb_str_cat2(str, ", "); + } + else { + rb_str_cat2(str, " "); + } + slot = RARRAY_AREF(members, i); + id = SYM2ID(slot); + if (rb_is_local_id(id) || rb_is_const_id(id)) { + rb_str_append(str, rb_id2str(id)); + } + else { + rb_str_append(str, rb_inspect(slot)); + } + rb_str_cat2(str, "="); + rb_str_append(str, rb_inspect(RSTRUCT_GET_RAW(s, i))); } rb_str_cat2(str, ">"); - OBJ_INFECT(str, s); return str; } /* - * call-seq: - * struct.to_s => string - * struct.inspect => string + * call-seq: + * inspect -> string + * + * Returns a string representation of +self+: + * + * Customer = Struct.new(:name, :address, :zip) # => Customer + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.inspect # => "#<struct Customer name=\"Joe Smith\", address=\"123 Maple, Anytown NC\", zip=12345>" * - * Describe the contents of this struct in a string. */ static VALUE -rb_struct_inspect(s) - VALUE s; +rb_struct_inspect(VALUE s) { - if (rb_inspecting_p(s)) { - char *cname = rb_class2name(rb_obj_class(s)); - VALUE str = rb_str_new(0, strlen(cname) + 15); - - sprintf(RSTRING(str)->ptr, "#<struct %s:...>", cname); - RSTRING(str)->len = strlen(RSTRING(str)->ptr); - return str; - } - return rb_protect_inspect(inspect_struct, s, 0); + return rb_exec_recursive(inspect_struct, s, rb_str_new2("#<struct")); } /* * call-seq: - * struct.to_a => array - * struct.values => array - * - * Returns the values for this instance as an array. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.to_a[1] #=> "123 Maple, Anytown NC" + * to_a -> array + * + * Returns the values in +self+ as an array: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.to_a # => ["Joe Smith", "123 Maple, Anytown NC", 12345] + * + * Related: #members. */ static VALUE -rb_struct_to_a(s) - VALUE s; +rb_struct_to_a(VALUE s) { - return rb_ary_new4(RSTRUCT(s)->len, RSTRUCT(s)->ptr); + return rb_ary_new4(RSTRUCT_LEN_RAW(s), RSTRUCT_CONST_PTR(s)); } -/* :nodoc: */ +/* + * call-seq: + * to_h -> hash + * to_h {|name, value| ... } -> hash + * + * Returns a hash containing the name and value for each member: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * h = joe.to_h + * h # => {:name=>"Joe Smith", :address=>"123 Maple, Anytown NC", :zip=>12345} + * + * If a block is given, it is called with each name/value pair; + * the block should return a 2-element array whose elements will become + * a key/value pair in the returned hash: + * + * h = joe.to_h{|name, value| [name.upcase, value.to_s.upcase]} + * h # => {:NAME=>"JOE SMITH", :ADDRESS=>"123 MAPLE, ANYTOWN NC", :ZIP=>"12345"} + * + * Raises ArgumentError if the block returns an inappropriate value. + * + */ + static VALUE -rb_struct_init_copy(copy, s) - VALUE copy, s; +rb_struct_to_h(VALUE s) { - if (copy == s) return copy; - rb_check_frozen(copy); - if (!rb_obj_is_instance_of(s, rb_obj_class(copy))) { - rb_raise(rb_eTypeError, "wrong argument class"); + VALUE h = rb_hash_new_with_size(RSTRUCT_LEN_RAW(s)); + VALUE members = rb_struct_members(s); + long i; + int block_given = rb_block_given_p(); + + for (i=0; i<RSTRUCT_LEN_RAW(s); i++) { + VALUE k = rb_ary_entry(members, i), v = RSTRUCT_GET_RAW(s, i); + if (block_given) + rb_hash_set_pair(h, rb_yield_values(2, k, v)); + else + rb_hash_aset(h, k, v); } - RSTRUCT(copy)->ptr = ALLOC_N(VALUE, RSTRUCT(s)->len); - RSTRUCT(copy)->len = RSTRUCT(s)->len; - MEMCPY(RSTRUCT(copy)->ptr, RSTRUCT(s)->ptr, VALUE, RSTRUCT(copy)->len); - - return copy; + return h; } +/* + * call-seq: + * deconstruct_keys(array_of_names) -> hash + * + * Returns a hash of the name/value pairs for the given member names. + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * h = joe.deconstruct_keys([:zip, :address]) + * h # => {:zip=>12345, :address=>"123 Maple, Anytown NC"} + * + * Returns all names and values if +array_of_names+ is +nil+: + * + * h = joe.deconstruct_keys(nil) + * h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345} + * + */ static VALUE -rb_struct_aref_id(s, id) - VALUE s; - ID id; +rb_struct_deconstruct_keys(VALUE s, VALUE keys) { - VALUE member; - long i, len; + VALUE h; + long i; - member = rb_struct_iv_get(rb_obj_class(s), "__member__"); - if (NIL_P(member)) { - rb_bug("non-initialized struct"); + if (NIL_P(keys)) { + return rb_struct_to_h(s); } + if (UNLIKELY(!RB_TYPE_P(keys, T_ARRAY))) { + rb_raise(rb_eTypeError, + "wrong argument type %"PRIsVALUE" (expected Array or nil)", + rb_obj_class(keys)); - len = RARRAY(member)->len; - for (i=0; i<len; i++) { - if (SYM2ID(RARRAY(member)->ptr[i]) == id) { - return RSTRUCT(s)->ptr[i]; - } } - rb_name_error(id, "no member '%s' in struct", rb_id2name(id)); - return Qnil; /* not reached */ + if (RSTRUCT_LEN_RAW(s) < RARRAY_LEN(keys)) { + return rb_hash_new_with_size(0); + } + h = rb_hash_new_with_size(RARRAY_LEN(keys)); + for (i=0; i<RARRAY_LEN(keys); i++) { + VALUE key = RARRAY_AREF(keys, i); + int i = rb_struct_pos(s, &key); + if (i < 0) { + return h; + } + rb_hash_aset(h, key, RSTRUCT_GET_RAW(s, i)); + } + return h; } -/* - * call-seq: - * struct[symbol] => anObject - * struct[fixnum] => anObject - * - * Attribute Reference---Returns the value of the instance variable - * named by <i>symbol</i>, or indexed (0..length-1) by - * <i>fixnum</i>. Will raise <code>NameError</code> if the named - * variable does not exist, or <code>IndexError</code> if the index is - * out of range. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * - * joe["name"] #=> "Joe Smith" - * joe[:name] #=> "Joe Smith" - * joe[0] #=> "Joe Smith" - */ - +/* :nodoc: */ VALUE -rb_struct_aref(s, idx) - VALUE s, idx; +rb_struct_init_copy(VALUE copy, VALUE s) { - long i; + long i, len; + + if (!OBJ_INIT_COPY(copy, s)) return copy; + if (RSTRUCT_LEN_RAW(copy) != RSTRUCT_LEN_RAW(s)) { + rb_raise(rb_eTypeError, "struct size mismatch"); + } - if (TYPE(idx) == T_STRING || TYPE(idx) == T_SYMBOL) { - return rb_struct_aref_id(s, rb_to_id(idx)); + for (i=0, len=RSTRUCT_LEN_RAW(copy); i<len; i++) { + RSTRUCT_SET_RAW(copy, i, RSTRUCT_GET_RAW(s, i)); } - i = NUM2LONG(idx); - if (i < 0) i = RSTRUCT(s)->len + i; - if (i < 0) - rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)", - i, RSTRUCT(s)->len); - if (RSTRUCT(s)->len <= i) - rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)", - i, RSTRUCT(s)->len); - return RSTRUCT(s)->ptr[i]; + return copy; } -static VALUE -rb_struct_aset_id(s, id, val) - VALUE s, val; - ID id; +static int +rb_struct_pos(VALUE s, VALUE *name) { - VALUE member; - long i, len; + long i; + VALUE idx = *name; - member = rb_struct_iv_get(rb_obj_class(s), "__member__"); - if (NIL_P(member)) { - rb_bug("non-initialized struct"); + if (SYMBOL_P(idx)) { + return struct_member_pos(s, idx); } + else if (RB_TYPE_P(idx, T_STRING)) { + idx = rb_check_symbol(name); + if (NIL_P(idx)) return -1; + return struct_member_pos(s, idx); + } + else { + long len; + i = NUM2LONG(idx); + len = RSTRUCT_LEN_RAW(s); + if (i < 0) { + if (i + len < 0) { + *name = LONG2FIX(i); + return -1; + } + i += len; + } + else if (len <= i) { + *name = LONG2FIX(i); + return -1; + } + return (int)i; + } +} - rb_struct_modify(s); - len = RARRAY(member)->len; - for (i=0; i<len; i++) { - if (SYM2ID(RARRAY(member)->ptr[i]) == id) { - RSTRUCT(s)->ptr[i] = val; - return val; - } +static void +invalid_struct_pos(VALUE s, VALUE idx) +{ + if (FIXNUM_P(idx)) { + long i = FIX2INT(idx), len = RSTRUCT_LEN_RAW(s); + if (i < 0) { + rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)", + i, len); + } + else { + rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)", + i, len); + } + } + else { + rb_name_err_raise("no member '%1$s' in struct", s, idx); } - rb_name_error(id, "no member '%s' in struct", rb_id2name(id)); } /* * call-seq: - * struct[symbol] = obj => obj - * struct[fixnum] = obj => obj - * - * Attribute Assignment---Assigns to the instance variable named by - * <i>symbol</i> or <i>fixnum</i> the value <i>obj</i> and - * returns it. Will raise a <code>NameError</code> if the named - * variable does not exist, or an <code>IndexError</code> if the index - * is out of range. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * - * joe["name"] = "Luke" - * joe[:zip] = "90210" - * - * joe.name #=> "Luke" - * joe.zip #=> "90210" + * struct[name] -> object + * struct[n] -> object + * + * Returns a value from +self+. + * + * With symbol or string argument +name+ given, returns the value for the named member: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[:zip] # => 12345 + * + * Raises NameError if +name+ is not the name of a member. + * + * With integer argument +n+ given, returns <tt>self.values[n]</tt> + * if +n+ is in range; + * see Array@Array+Indexes: + * + * joe[2] # => 12345 + * joe[-2] # => "123 Maple, Anytown NC" + * + * Raises IndexError if +n+ is out of range. + * */ VALUE -rb_struct_aset(s, idx, val) - VALUE s, idx, val; +rb_struct_aref(VALUE s, VALUE idx) { - long i; + int i = rb_struct_pos(s, &idx); + if (i < 0) invalid_struct_pos(s, idx); + return RSTRUCT_GET_RAW(s, i); +} - if (TYPE(idx) == T_STRING || TYPE(idx) == T_SYMBOL) { - return rb_struct_aset_id(s, rb_to_id(idx), val); - } +/* + * call-seq: + * struct[name] = value -> value + * struct[n] = value -> value + * + * Assigns a value to a member. + * + * With symbol or string argument +name+ given, assigns the given +value+ + * to the named member; returns +value+: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[:zip] = 54321 # => 54321 + * joe # => #<struct Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=54321> + * + * Raises NameError if +name+ is not the name of a member. + * + * With integer argument +n+ given, assigns the given +value+ + * to the +n+-th member if +n+ is in range; + * see Array@Array+Indexes: + * + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[2] = 54321 # => 54321 + * joe[-3] = 'Joseph Smith' # => "Joseph Smith" + * joe # => #<struct Customer name="Joseph Smith", address="123 Maple, Anytown NC", zip=54321> + * + * Raises IndexError if +n+ is out of range. + * + */ - i = NUM2LONG(idx); - if (i < 0) i = RSTRUCT(s)->len + i; - if (i < 0) { - rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)", - i, RSTRUCT(s)->len); - } - if (RSTRUCT(s)->len <= i) { - rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)", - i, RSTRUCT(s)->len); - } +VALUE +rb_struct_aset(VALUE s, VALUE idx, VALUE val) +{ + int i = rb_struct_pos(s, &idx); + if (i < 0) invalid_struct_pos(s, idx); rb_struct_modify(s); - return RSTRUCT(s)->ptr[i] = val; + RSTRUCT_SET_RAW(s, i, val); + return val; +} + +FUNC_MINIMIZED(VALUE rb_struct_lookup(VALUE s, VALUE idx)); +NOINLINE(static VALUE rb_struct_lookup_default(VALUE s, VALUE idx, VALUE notfound)); + +VALUE +rb_struct_lookup(VALUE s, VALUE idx) +{ + return rb_struct_lookup_default(s, idx, Qnil); } -static VALUE struct_entry _((VALUE, long)); static VALUE -struct_entry(s, n) - VALUE s; - long n; +rb_struct_lookup_default(VALUE s, VALUE idx, VALUE notfound) +{ + int i = rb_struct_pos(s, &idx); + if (i < 0) return notfound; + return RSTRUCT_GET_RAW(s, i); +} + +static VALUE +struct_entry(VALUE s, long n) { return rb_struct_aref(s, LONG2NUM(n)); } -/* - * call-seq: - * struct.values_at(selector,... ) => an_array +/* + * call-seq: + * values_at(*integers) -> array + * values_at(integer_range) -> array + * + * Returns an array of values from +self+. + * + * With integer arguments +integers+ given, + * returns an array containing each value given by one of +integers+: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.values_at(0, 2) # => ["Joe Smith", 12345] + * joe.values_at(2, 0) # => [12345, "Joe Smith"] + * joe.values_at(2, 1, 0) # => [12345, "123 Maple, Anytown NC", "Joe Smith"] + * joe.values_at(0, -3) # => ["Joe Smith", "Joe Smith"] + * + * Raises IndexError if any of +integers+ is out of range; + * see Array@Array+Indexes. + * + * With integer range argument +integer_range+ given, + * returns an array containing each value given by the elements of the range; + * fills with +nil+ values for range elements larger than the structure: + * + * joe.values_at(0..2) + * # => ["Joe Smith", "123 Maple, Anytown NC", 12345] + * joe.values_at(-3..-1) + * # => ["Joe Smith", "123 Maple, Anytown NC", 12345] + * joe.values_at(1..4) # => ["123 Maple, Anytown NC", 12345, nil, nil] + * + * Raises RangeError if any element of the range is negative and out of range; + * see Array@Array+Indexes. * - * Returns an array containing the elements in - * _self_ corresponding to the given selector(s). The selectors - * may be either integer indices or ranges. - * See also </code>.select<code>. - * - * a = %w{ a b c d e f } - * a.values_at(1, 3, 5) - * a.values_at(1, 3, 5, 7) - * a.values_at(-1, -3, -5, -7) - * a.values_at(1..3, 2...5) */ static VALUE -rb_struct_values_at(argc, argv, s) - int argc; - VALUE *argv; - VALUE s; +rb_struct_values_at(int argc, VALUE *argv, VALUE s) { - return rb_values_at(s, RSTRUCT(s)->len, argc, argv, struct_entry); + return rb_get_values_at(s, RSTRUCT_LEN_RAW(s), argc, argv, struct_entry); } /* * call-seq: - * struct.select(fixnum, ... ) => array - * struct.select {|i| block } => array - * - * The first form returns an array containing the elements in - * <i>struct</i> corresponding to the given indices. The second - * form invokes the block passing in successive elements from - * <i>struct</i>, returning an array containing those elements - * for which the block returns a true value (equivalent to - * <code>Enumerable#select</code>). - * - * Lots = Struct.new(:a, :b, :c, :d, :e, :f) - * l = Lots.new(11, 22, 33, 44, 55, 66) - * l.select(1, 3, 5) #=> [22, 44, 66] - * l.select(0, 2, 4) #=> [11, 33, 55] - * l.select(-1, -3, -5) #=> [66, 44, 22] - * l.select {|v| (v % 2).zero? } #=> [22, 44, 66] - */ - -static VALUE -rb_struct_select(argc, argv, s) - int argc; - VALUE *argv; - VALUE s; + * select {|value| ... } -> array + * select -> enumerator + * + * With a block given, returns an array of values from +self+ + * for which the block returns a truthy value: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * a = joe.select {|value| value.is_a?(String) } + * a # => ["Joe Smith", "123 Maple, Anytown NC"] + * a = joe.select {|value| value.is_a?(Integer) } + * a # => [12345] + * + * With no block given, returns an Enumerator. + */ + +static VALUE +rb_struct_select(int argc, VALUE *argv, VALUE s) { VALUE result; long i; - if (argc > 0) { - rb_raise(rb_eArgError, "wrong number arguments(%d for 0)", argc); - } + rb_check_arity(argc, 0, 0); + RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size); result = rb_ary_new(); - for (i = 0; i < RSTRUCT(s)->len; i++) { - if (RTEST(rb_yield(RSTRUCT(s)->ptr[i]))) { - rb_ary_push(result, RSTRUCT(s)->ptr[i]); - } + for (i = 0; i < RSTRUCT_LEN_RAW(s); i++) { + if (RTEST(rb_yield(RSTRUCT_GET_RAW(s, i)))) { + rb_ary_push(result, RSTRUCT_GET_RAW(s, i)); + } } return result; } +static VALUE +recursive_equal(VALUE s, VALUE s2, int recur) +{ + long i, len; + + if (recur) return Qtrue; /* Subtle! */ + len = RSTRUCT_LEN_RAW(s); + for (i=0; i<len; i++) { + if (!rb_equal(RSTRUCT_GET_RAW(s, i), RSTRUCT_GET_RAW(s2, i))) return Qfalse; + } + return Qtrue; +} + + /* * call-seq: - * struct == other_struct => true or false - * - * Equality---Returns <code>true</code> if <i>other_struct</i> is - * equal to this one: they must be of the same class as generated by - * <code>Struct::new</code>, and the values of all instance variables - * must be equal (according to <code>Object#==</code>). - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joejr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * jane = Customer.new("Jane Doe", "456 Elm, Anytown NC", 12345) - * joe == joejr #=> true - * joe == jane #=> false + * self == other -> true or false + * + * Returns whether both the following are true: + * + * - <tt>other.class == self.class</tt>. + * - For each member name +name+, <tt>other.name == self.name</tt>. + * + * Examples: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe_jr == joe # => true + * joe_jr[:name] = 'Joe Smith, Jr.' + * # => "Joe Smith, Jr." + * joe_jr == joe # => false */ static VALUE -rb_struct_equal(s, s2) - VALUE s, s2; +rb_struct_equal(VALUE s, VALUE s2) { - long i; - if (s == s2) return Qtrue; - if (TYPE(s2) != T_STRUCT) return Qfalse; + if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse; if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse; - if (RSTRUCT(s)->len != RSTRUCT(s2)->len) { - rb_bug("inconsistent struct"); /* should never happen */ + if (RSTRUCT_LEN_RAW(s) != RSTRUCT_LEN_RAW(s2)) { + rb_bug("inconsistent struct"); /* should never happen */ + } + + return rb_exec_recursive_paired(recursive_equal, s, s2, s2); +} + +/* + * call-seq: + * hash -> integer + * + * Returns the integer hash value for +self+. + * + * Two structs of the same class and with the same content + * will have the same hash code (and will compare using Struct#eql?): + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.hash == joe_jr.hash # => true + * joe_jr[:name] = 'Joe Smith, Jr.' + * joe.hash == joe_jr.hash # => false + * + * Related: Object#hash. + */ + +static VALUE +rb_struct_hash(VALUE s) +{ + long i, len; + st_index_t h; + VALUE n; + + h = rb_hash_start(rb_hash(rb_obj_class(s))); + len = RSTRUCT_LEN_RAW(s); + for (i = 0; i < len; i++) { + n = rb_hash(RSTRUCT_GET_RAW(s, i)); + h = rb_hash_uint(h, NUM2LONG(n)); } + h = rb_hash_end(h); + return ST2FIX(h); +} + +static VALUE +recursive_eql(VALUE s, VALUE s2, int recur) +{ + long i, len; - for (i=0; i<RSTRUCT(s)->len; i++) { - if (!rb_equal(RSTRUCT(s)->ptr[i], RSTRUCT(s2)->ptr[i])) return Qfalse; + if (recur) return Qtrue; /* Subtle! */ + len = RSTRUCT_LEN_RAW(s); + for (i=0; i<len; i++) { + if (!rb_eql(RSTRUCT_GET_RAW(s, i), RSTRUCT_GET_RAW(s2, i))) return Qfalse; } return Qtrue; } /* * call-seq: - * struct.hash => fixnum + * eql?(other) -> true or false * - * Return a hash value based on this struct's contents. + * Returns +true+ if and only if the following are true; otherwise returns +false+: + * + * - <tt>other.class == self.class</tt>. + * - For each member name +name+, <tt>other.name.eql?(self.name)</tt>. + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe_jr.eql?(joe) # => true + * joe_jr[:name] = 'Joe Smith, Jr.' + * joe_jr.eql?(joe) # => false + * + * Related: Object#==. */ static VALUE -rb_struct_hash(s) - VALUE s; +rb_struct_eql(VALUE s, VALUE s2) { - long i, h; - VALUE n; - - h = rb_hash(rb_obj_class(s)); - for (i = 0; i < RSTRUCT(s)->len; i++) { - h = (h << 1) | (h<0 ? 1 : 0); - n = rb_hash(RSTRUCT(s)->ptr[i]); - h ^= NUM2LONG(n); + if (s == s2) return Qtrue; + if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse; + if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse; + if (RSTRUCT_LEN_RAW(s) != RSTRUCT_LEN_RAW(s2)) { + rb_bug("inconsistent struct"); /* should never happen */ } - return LONG2FIX(h); + + return rb_exec_recursive_paired(recursive_eql, s, s2, s2); +} + +/* + * call-seq: + * size -> integer + * + * Returns the number of members. + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.size #=> 3 + * + */ + +VALUE +rb_struct_size(VALUE s) +{ + return LONG2FIX(RSTRUCT_LEN_RAW(s)); } /* - * code-seq: - * struct.eql?(other) => true or false + * call-seq: + * dig(name, *identifiers) -> object + * dig(n, *identifiers) -> object + * + * Finds and returns an object among nested objects. + * The nested objects may be instances of various classes. + * See {Dig Methods}[rdoc-ref:dig_methods.rdoc]. + * + * + * Given symbol or string argument +name+, + * returns the object that is specified by +name+ and +identifiers+: + * + * Foo = Struct.new(:a) + * f = Foo.new(Foo.new({b: [1, 2, 3]})) + * f.dig(:a) # => #<struct Foo a={:b=>[1, 2, 3]}> + * f.dig(:a, :a) # => {:b=>[1, 2, 3]} + * f.dig(:a, :a, :b) # => [1, 2, 3] + * f.dig(:a, :a, :b, 0) # => 1 + * f.dig(:b, 0) # => nil + * + * Given integer argument +n+, + * returns the object that is specified by +n+ and +identifiers+: + * + * f.dig(0) # => #<struct Foo a={:b=>[1, 2, 3]}> + * f.dig(0, 0) # => {:b=>[1, 2, 3]} + * f.dig(0, 0, :b) # => [1, 2, 3] + * f.dig(0, 0, :b, 0) # => 1 + * f.dig(:b, 0) # => nil * - * Two structures are equal if they are the same object, or if all their - * fields are equal (using <code>eql?</code>). */ static VALUE -rb_struct_eql(s, s2) - VALUE s, s2; +rb_struct_dig(int argc, VALUE *argv, VALUE self) { + rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); + self = rb_struct_lookup(self, *argv); + if (!--argc) return self; + ++argv; + return rb_obj_dig(argc, argv, self, Qnil); +} + +/* + * Document-class: Data + * + * Class \Data provides a convenient way to define simple classes + * for value-alike objects. + * + * The simplest example of usage: + * + * Measure = Data.define(:amount, :unit) + * + * # Positional arguments constructor is provided + * distance = Measure.new(100, 'km') + * #=> #<data Measure amount=100, unit="km"> + * + * # Keyword arguments constructor is provided + * weight = Measure.new(amount: 50, unit: 'kg') + * #=> #<data Measure amount=50, unit="kg"> + * + * # Alternative form to construct an object: + * speed = Measure[10, 'mPh'] + * #=> #<data Measure amount=10, unit="mPh"> + * + * # Works with keyword arguments, too: + * area = Measure[amount: 1.5, unit: 'm^2'] + * #=> #<data Measure amount=1.5, unit="m^2"> + * + * # Argument accessors are provided: + * distance.amount #=> 100 + * distance.unit #=> "km" + * + * Constructed object also has a reasonable definitions of #== + * operator, #to_h hash conversion, and #deconstruct / #deconstruct_keys + * to be used in pattern matching. + * + * ::define method accepts an optional block and evaluates it in + * the context of the newly defined class. That allows to define + * additional methods: + * + * Measure = Data.define(:amount, :unit) do + * def <=>(other) + * return unless other.is_a?(self.class) && other.unit == unit + * amount <=> other.amount + * end + * + * include Comparable + * end + * + * Measure[3, 'm'] < Measure[5, 'm'] #=> true + * Measure[3, 'm'] < Measure[5, 'kg'] + * # comparison of Measure with Measure failed (ArgumentError) + * + * Data provides no member writers, or enumerators: it is meant + * to be a storage for immutable atomic values. But note that + * if some of data members is of a mutable class, Data does no additional + * immutability enforcement: + * + * Event = Data.define(:time, :weekdays) + * event = Event.new('18:00', %w[Tue Wed Fri]) + * #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri"]> + * + * # There is no #time= or #weekdays= accessors, but changes are + * # still possible: + * event.weekdays << 'Sat' + * event + * #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri", "Sat"]> + * + * See also Struct, which is a similar concept, but has more + * container-alike API, allowing to change contents of the object + * and enumerate it. + */ + +/* + * call-seq: + * define(*symbols) -> class + * + * Defines a new \Data class. + * + * measure = Data.define(:amount, :unit) + * #=> #<Class:0x00007f70c6868498> + * measure.new(1, 'km') + * #=> #<data amount=1, unit="km"> + * + * # It you store the new class in the constant, it will + * # affect #inspect and will be more natural to use: + * Measure = Data.define(:amount, :unit) + * #=> Measure + * Measure.new(1, 'km') + * #=> #<data Measure amount=1, unit="km"> + * + * + * Note that member-less \Data is acceptable and might be a useful technique + * for defining several homogeneous data classes, like + * + * class HTTPFetcher + * Response = Data.define(:body) + * NotFound = Data.define + * # ... implementation + * end + * + * Now, different kinds of responses from +HTTPFetcher+ would have consistent + * representation: + * + * #<data HTTPFetcher::Response body="<html..."> + * #<data HTTPFetcher::NotFound> + * + * And are convenient to use in pattern matching: + * + * case fetcher.get(url) + * in HTTPFetcher::Response(body) + * # process body variable + * in HTTPFetcher::NotFound + * # handle not found case + * end + */ + +static VALUE +rb_data_s_def(int argc, VALUE *argv, VALUE klass) +{ + VALUE rest; long i; + VALUE data_class; + + rest = rb_ident_hash_new(); + RBASIC_CLEAR_CLASS(rest); + for (i=0; i<argc; i++) { + VALUE mem = rb_to_symbol(argv[i]); + if (rb_is_attrset_sym(mem)) { + rb_raise(rb_eArgError, "invalid data member: %"PRIsVALUE, mem); + } + if (RTEST(rb_hash_has_key(rest, mem))) { + rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem); + } + rb_hash_aset(rest, mem, Qtrue); + } + rest = rb_hash_keys(rest); + RBASIC_CLEAR_CLASS(rest); + OBJ_FREEZE(rest); + data_class = anonymous_struct(klass); + setup_data(data_class, rest); + if (rb_block_given_p()) { + rb_mod_module_eval(0, 0, data_class); + } - if (s == s2) return Qtrue; - if (TYPE(s2) != T_STRUCT) return Qfalse; - if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse; - if (RSTRUCT(s)->len != RSTRUCT(s2)->len) { - rb_bug("inconsistent struct"); /* should never happen */ + return data_class; +} + +VALUE +rb_data_define(VALUE super, ...) +{ + va_list ar; + VALUE ary; + va_start(ar, super); + ary = struct_make_members_list(ar); + va_end(ar); + if (!super) super = rb_cData; + VALUE klass = setup_data(anonymous_struct(super), ary); + rb_vm_register_global_object(klass); + return klass; +} + +/* + * call-seq: + * DataClass::members -> array_of_symbols + * + * Returns an array of member names of the data class: + * + * Measure = Data.define(:amount, :unit) + * Measure.members # => [:amount, :unit] + * + */ + +#define rb_data_s_members_m rb_struct_s_members_m + + +/* + * call-seq: + * new(*args) -> instance + * new(**kwargs) -> instance + * ::[](*args) -> instance + * ::[](**kwargs) -> instance + * + * Constructors for classes defined with ::define accept both positional and + * keyword arguments. + * + * Measure = Data.define(:amount, :unit) + * + * Measure.new(1, 'km') + * #=> #<data Measure amount=1, unit="km"> + * Measure.new(amount: 1, unit: 'km') + * #=> #<data Measure amount=1, unit="km"> + * + * # Alternative shorter initialization with [] + * Measure[1, 'km'] + * #=> #<data Measure amount=1, unit="km"> + * Measure[amount: 1, unit: 'km'] + * #=> #<data Measure amount=1, unit="km"> + * + * All arguments are mandatory (unlike Struct), and converted to keyword arguments: + * + * Measure.new(amount: 1) + * # in `initialize': missing keyword: :unit (ArgumentError) + * + * Measure.new(1) + * # in `initialize': missing keyword: :unit (ArgumentError) + * + * Note that <tt>Measure#initialize</tt> always receives keyword arguments, and that + * mandatory arguments are checked in +initialize+, not in +new+. This can be + * important for redefining initialize in order to convert arguments or provide + * defaults: + * + * Measure = Data.define(:amount, :unit) + * class Measure + * NONE = Data.define + * + * def initialize(amount:, unit: NONE.new) + * super(amount: Float(amount), unit:) + * end + * end + * + * Measure.new('10', 'km') # => #<data Measure amount=10.0, unit="km"> + * Measure.new(10_000) # => #<data Measure amount=10000.0, unit=#<data Measure::NONE>> + * + */ + +static VALUE +rb_data_initialize_m(int argc, const VALUE *argv, VALUE self) +{ + VALUE klass = rb_obj_class(self); + rb_struct_modify(self); + VALUE members = struct_ivar_get(klass, id_members); + size_t num_members = RARRAY_LEN(members); + + if (argc == 0) { + if (num_members > 0) { + rb_exc_raise(rb_keyword_error_new("missing", members)); + } + OBJ_FREEZE(self); + return Qnil; + } + if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) { + rb_error_arity(argc, 0, 0); } - for (i=0; i<RSTRUCT(s)->len; i++) { - if (!rb_eql(RSTRUCT(s)->ptr[i], RSTRUCT(s2)->ptr[i])) return Qfalse; + if (RHASH_SIZE(argv[0]) < num_members) { + VALUE missing = rb_ary_diff(members, rb_hash_keys(argv[0])); + rb_exc_raise(rb_keyword_error_new("missing", missing)); } - return Qtrue; + + struct struct_hash_set_arg arg; + rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), num_members); + arg.self = self; + arg.unknown_keywords = Qnil; + rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg); + // Freeze early before potentially raising, so that we don't leave an + // unfrozen copy on the heap, which could get exposed via ObjectSpace. + OBJ_FREEZE(self); + if (arg.unknown_keywords != Qnil) { + rb_exc_raise(rb_keyword_error_new("unknown", arg.unknown_keywords)); + } + return Qnil; +} + +/* :nodoc: */ +static VALUE +rb_data_init_copy(VALUE copy, VALUE s) +{ + copy = rb_struct_init_copy(copy, s); + RB_OBJ_FREEZE(copy); + return copy; } /* * call-seq: - * struct.length => fixnum - * struct.size => fixnum - * - * Returns the number of instance variables. - * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.length #=> 3 + * with(**kwargs) -> instance + * + * Returns a shallow copy of +self+ --- the instance variables of + * +self+ are copied, but not the objects they reference. + * + * If the method is supplied any keyword arguments, the copy will + * be created with the respective field values updated to use the + * supplied keyword argument values. Note that it is an error to + * supply a keyword that the Data class does not have as a member. + * + * Point = Data.define(:x, :y) + * + * origin = Point.new(x: 0, y: 0) + * + * up = origin.with(x: 1) + * right = origin.with(y: 1) + * up_and_right = up.with(y: 1) + * + * p origin # #<data Point x=0, y=0> + * p up # #<data Point x=1, y=0> + * p right # #<data Point x=0, y=1> + * p up_and_right # #<data Point x=1, y=1> + * + * out = origin.with(z: 1) # ArgumentError: unknown keyword: :z + * some_point = origin.with(1, 2) # ArgumentError: expected keyword arguments, got positional arguments + * + */ + +static VALUE +rb_data_with(int argc, const VALUE *argv, VALUE self) +{ + VALUE kwargs; + rb_scan_args(argc, argv, "0:", &kwargs); + if (NIL_P(kwargs)) { + return self; + } + + VALUE h = rb_struct_to_h(self); + rb_hash_update_by(h, kwargs, 0); + return rb_class_new_instance_kw(1, &h, rb_obj_class(self), TRUE); +} + +/* + * call-seq: + * inspect -> string + * to_s -> string + * + * Returns a string representation of +self+: + * + * Measure = Data.define(:amount, :unit) + * + * distance = Measure[10, 'km'] + * + * p distance # uses #inspect underneath + * #<data Measure amount=10, unit="km"> + * + * puts distance # uses #to_s underneath, same representation + * #<data Measure amount=10, unit="km"> + * */ static VALUE -rb_struct_size(s) - VALUE s; +rb_data_inspect(VALUE s) { - return LONG2FIX(RSTRUCT(s)->len); + return rb_exec_recursive(inspect_struct, s, rb_str_new2("#<data")); } /* - * A <code>Struct</code> is a convenient way to bundle a number of - * attributes together, using accessor methods, without having to write - * an explicit class. - * - * The <code>Struct</code> class is a generator of specific classes, - * each one of which is defined to hold a set of variables and their - * accessors. In these examples, we'll call the generated class - * ``<i>Customer</i>Class,'' and we'll show an example instance of that - * class as ``<i>Customer</i>Inst.'' - * - * In the descriptions that follow, the parameter <i>symbol</i> refers - * to a symbol, which is either a quoted string or a - * <code>Symbol</code> (such as <code>:name</code>). + * call-seq: + * self == other -> true or false + * + * Returns whether +other+ is the same class as +self+, and all members are + * equal. + * + * Examples: + * + * Measure = Data.define(:amount, :unit) + * + * Measure[1, 'km'] == Measure[1, 'km'] #=> true + * Measure[1, 'km'] == Measure[2, 'km'] #=> false + * Measure[1, 'km'] == Measure[1, 'm'] #=> false + * + * Measurement = Data.define(:amount, :unit) + * # Even though Measurement and Measure have the same "shape" + * # their instances are never equal + * Measure[1, 'km'] == Measurement[1, 'km'] #=> false + */ + +#define rb_data_equal rb_struct_equal + +/* + * call-seq: + * self.eql?(other) -> true or false + * + * Equality check that is used when two items of data are keys of a Hash. + * + * The subtle difference with #== is that members are also compared with their + * #eql? method, which might be important in some cases: + * + * Measure = Data.define(:amount, :unit) + * + * Measure[1, 'km'] == Measure[1.0, 'km'] #=> true, they are equal as values + * # ...but... + * Measure[1, 'km'].eql? Measure[1.0, 'km'] #=> false, they represent different hash keys + * + * See also Object#eql? for further explanations of the method usage. + */ + +#define rb_data_eql rb_struct_eql + +/* + * call-seq: + * hash -> integer + * + * Redefines Object#hash (used to distinguish objects as Hash keys) so that + * data objects of the same class with same content would have the same +hash+ + * value, and represented the same Hash key. + * + * Measure = Data.define(:amount, :unit) + * + * Measure[1, 'km'].hash == Measure[1, 'km'].hash #=> true + * Measure[1, 'km'].hash == Measure[10, 'km'].hash #=> false + * Measure[1, 'km'].hash == Measure[1, 'm'].hash #=> false + * Measure[1, 'km'].hash == Measure[1.0, 'km'].hash #=> false + * + * # Structurally similar data class, but shouldn't be considered + * # the same hash key + * Measurement = Data.define(:amount, :unit) + * + * Measure[1, 'km'].hash == Measurement[1, 'km'].hash #=> false + */ + +#define rb_data_hash rb_struct_hash + +/* + * call-seq: + * to_h -> hash + * to_h {|name, value| ... } -> hash + * + * Returns Hash representation of the data object. + * + * Measure = Data.define(:amount, :unit) + * distance = Measure[10, 'km'] + * + * distance.to_h + * #=> {:amount=>10, :unit=>"km"} + * + * Like Enumerable#to_h, if the block is provided, it is expected to + * produce key-value pairs to construct a hash: + * + * + * distance.to_h { |name, val| [name.to_s, val.to_s] } + * #=> {"amount"=>"10", "unit"=>"km"} + * + * Note that there is a useful symmetry between #to_h and #initialize: + * + * distance2 = Measure.new(**distance.to_h) + * #=> #<data Measure amount=10, unit="km"> + * distance2 == distance + * #=> true + */ + +#define rb_data_to_h rb_struct_to_h + +/* + * call-seq: + * members -> array_of_symbols + * + * Returns the member names from +self+ as an array: + * + * Measure = Data.define(:amount, :unit) + * distance = Measure[10, 'km'] + * + * distance.members #=> [:amount, :unit] + * + */ + +#define rb_data_members_m rb_struct_members_m + +/* + * call-seq: + * deconstruct -> array + * + * Returns the values in +self+ as an array, to use in pattern matching: + * + * Measure = Data.define(:amount, :unit) + * + * distance = Measure[10, 'km'] + * distance.deconstruct #=> [10, "km"] + * + * # usage + * case distance + * in n, 'km' # calls #deconstruct underneath + * puts "It is #{n} kilometers away" + * else + * puts "Don't know how to handle it" + * end + * # prints "It is 10 kilometers away" + * + * Or, with checking the class, too: + * + * case distance + * in Measure(n, 'km') + * puts "It is #{n} kilometers away" + * # ... + * end + */ + +#define rb_data_deconstruct rb_struct_to_a + +/* + * call-seq: + * deconstruct_keys(array_of_names_or_nil) -> hash + * + * Returns a hash of the name/value pairs, to use in pattern matching. + * + * Measure = Data.define(:amount, :unit) + * + * distance = Measure[10, 'km'] + * distance.deconstruct_keys(nil) #=> {:amount=>10, :unit=>"km"} + * distance.deconstruct_keys([:amount]) #=> {:amount=>10} + * + * # usage + * case distance + * in amount:, unit: 'km' # calls #deconstruct_keys underneath + * puts "It is #{amount} kilometers away" + * else + * puts "Don't know how to handle it" + * end + * # prints "It is 10 kilometers away" + * + * Or, with checking the class, too: + * + * case distance + * in Measure(amount:, unit: 'km') + * puts "It is #{amount} kilometers away" + * # ... + * end + */ + +#define rb_data_deconstruct_keys rb_struct_deconstruct_keys + +/* + * Document-class: Struct + * + * Class \Struct provides a convenient way to create a simple class + * that can store and fetch values. + * + * This example creates a subclass of +Struct+, <tt>Struct::Customer</tt>; + * the first argument, a string, is the name of the subclass; + * the other arguments, symbols, determine the _members_ of the new subclass. + * + * Customer = Struct.new('Customer', :name, :address, :zip) + * Customer.name # => "Struct::Customer" + * Customer.class # => Class + * Customer.superclass # => Struct + * + * Corresponding to each member are two methods, a writer and a reader, + * that store and fetch values: + * + * methods = Customer.instance_methods false + * methods # => [:zip, :address=, :zip=, :address, :name, :name=] + * + * An instance of the subclass may be created, + * and its members assigned values, via method <tt>::new</tt>: + * + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345> + * + * The member values may be managed thus: + * + * joe.name # => "Joe Smith" + * joe.name = 'Joseph Smith' + * joe.name # => "Joseph Smith" + * + * And thus; note that member name may be expressed as either a string or a symbol: + * + * joe[:name] # => "Joseph Smith" + * joe[:name] = 'Joseph Smith, Jr.' + * joe['name'] # => "Joseph Smith, Jr." + * + * See Struct::new. + * + * == What's Here + * + * First, what's elsewhere. Class \Struct: + * + * - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here]. + * - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here], + * which provides dozens of additional methods. + * + * See also Data, which is a somewhat similar, but stricter concept for defining immutable + * value objects. + * + * Here, class \Struct provides methods that are useful for: + * + * - {Creating a Struct Subclass}[rdoc-ref:Struct@Methods+for+Creating+a+Struct+Subclass] + * - {Querying}[rdoc-ref:Struct@Methods+for+Querying] + * - {Comparing}[rdoc-ref:Struct@Methods+for+Comparing] + * - {Fetching}[rdoc-ref:Struct@Methods+for+Fetching] + * - {Assigning}[rdoc-ref:Struct@Methods+for+Assigning] + * - {Iterating}[rdoc-ref:Struct@Methods+for+Iterating] + * - {Converting}[rdoc-ref:Struct@Methods+for+Converting] + * + * === Methods for Creating a Struct Subclass + * + * - ::new: Returns a new subclass of \Struct. + * + * === Methods for Querying + * + * - #hash: Returns the integer hash code. + * - #size (aliased as #length): Returns the number of members. + * + * === Methods for Comparing + * + * - #==: Returns whether a given object is equal to +self+, using <tt>==</tt> + * to compare member values. + * - #eql?: Returns whether a given object is equal to +self+, + * using <tt>eql?</tt> to compare member values. + * + * === Methods for Fetching + * + * - #[]: Returns the value associated with a given member name. + * - #to_a (aliased as #values, #deconstruct): Returns the member values in +self+ as an array. + * - #deconstruct_keys: Returns a hash of the name/value pairs + * for given member names. + * - #dig: Returns the object in nested objects that is specified + * by a given member name and additional arguments. + * - #members: Returns an array of the member names. + * - #select (aliased as #filter): Returns an array of member values from +self+, + * as selected by the given block. + * - #values_at: Returns an array containing values for given member names. + * + * === Methods for Assigning + * + * - #[]=: Assigns a given value to a given member name. + * + * === Methods for Iterating + * + * - #each: Calls a given block with each member name. + * - #each_pair: Calls a given block with each member name/value pair. + * + * === Methods for Converting + * + * - #inspect (aliased as #to_s): Returns a string representation of +self+. + * - #to_h: Returns a hash of the member name/value pairs in +self+. + * */ void -Init_Struct() +InitVM_Struct(void) { rb_cStruct = rb_define_class("Struct", rb_cObject); rb_include_module(rb_cStruct, rb_mEnumerable); rb_undef_alloc_func(rb_cStruct); rb_define_singleton_method(rb_cStruct, "new", rb_struct_s_def, -1); +#if 0 /* for RDoc */ + rb_define_singleton_method(rb_cStruct, "keyword_init?", rb_struct_s_keyword_init_p, 0); + rb_define_singleton_method(rb_cStruct, "members", rb_struct_s_members_m, 0); +#endif - rb_define_method(rb_cStruct, "initialize", rb_struct_initialize, -2); + rb_define_method(rb_cStruct, "initialize", rb_struct_initialize_m, -1); rb_define_method(rb_cStruct, "initialize_copy", rb_struct_init_copy, 1); rb_define_method(rb_cStruct, "==", rb_struct_equal, 1); rb_define_method(rb_cStruct, "eql?", rb_struct_eql, 1); rb_define_method(rb_cStruct, "hash", rb_struct_hash, 0); - rb_define_method(rb_cStruct, "to_s", rb_struct_inspect, 0); rb_define_method(rb_cStruct, "inspect", rb_struct_inspect, 0); + rb_define_alias(rb_cStruct, "to_s", "inspect"); rb_define_method(rb_cStruct, "to_a", rb_struct_to_a, 0); + rb_define_method(rb_cStruct, "to_h", rb_struct_to_h, 0); rb_define_method(rb_cStruct, "values", rb_struct_to_a, 0); rb_define_method(rb_cStruct, "size", rb_struct_size, 0); rb_define_method(rb_cStruct, "length", rb_struct_size, 0); @@ -894,7 +2228,51 @@ Init_Struct() rb_define_method(rb_cStruct, "[]", rb_struct_aref, 1); rb_define_method(rb_cStruct, "[]=", rb_struct_aset, 2); rb_define_method(rb_cStruct, "select", rb_struct_select, -1); + rb_define_method(rb_cStruct, "filter", rb_struct_select, -1); rb_define_method(rb_cStruct, "values_at", rb_struct_values_at, -1); - rb_define_method(rb_cStruct, "members", rb_struct_members, 0); + rb_define_method(rb_cStruct, "members", rb_struct_members_m, 0); + rb_define_method(rb_cStruct, "dig", rb_struct_dig, -1); + + rb_define_method(rb_cStruct, "deconstruct", rb_struct_to_a, 0); + rb_define_method(rb_cStruct, "deconstruct_keys", rb_struct_deconstruct_keys, 1); + + rb_cData = rb_define_class("Data", rb_cObject); + + rb_undef_method(CLASS_OF(rb_cData), "new"); + rb_undef_alloc_func(rb_cData); + rb_define_singleton_method(rb_cData, "define", rb_data_s_def, -1); + +#if 0 /* for RDoc */ + rb_define_singleton_method(rb_cData, "members", rb_data_s_members_m, 0); +#endif + + rb_define_method(rb_cData, "initialize", rb_data_initialize_m, -1); + rb_define_method(rb_cData, "initialize_copy", rb_data_init_copy, 1); + + rb_define_method(rb_cData, "==", rb_data_equal, 1); + rb_define_method(rb_cData, "eql?", rb_data_eql, 1); + rb_define_method(rb_cData, "hash", rb_data_hash, 0); + + rb_define_method(rb_cData, "inspect", rb_data_inspect, 0); + rb_define_alias(rb_cData, "to_s", "inspect"); + rb_define_method(rb_cData, "to_h", rb_data_to_h, 0); + + rb_define_method(rb_cData, "members", rb_data_members_m, 0); + + rb_define_method(rb_cData, "deconstruct", rb_data_deconstruct, 0); + rb_define_method(rb_cData, "deconstruct_keys", rb_data_deconstruct_keys, 1); + + rb_define_method(rb_cData, "with", rb_data_with, -1); +} + +#undef rb_intern +void +Init_Struct(void) +{ + id_members = rb_intern("__members__"); + id_back_members = rb_intern("__members_back__"); + id_keyword_init = rb_intern("__keyword_init__"); + + InitVM(Struct); } |