diff options
| -rw-r--r-- | include/ruby/internal/attr/deprecated.h | 8 | ||||
| -rw-r--r-- | include/ruby/internal/intern/object.h | 563 | ||||
| -rw-r--r-- | object.c | 228 |
3 files changed, 541 insertions, 258 deletions
diff --git a/include/ruby/internal/attr/deprecated.h b/include/ruby/internal/attr/deprecated.h index 6c27e36785..e1bbdbd15a 100644 --- a/include/ruby/internal/attr/deprecated.h +++ b/include/ruby/internal/attr/deprecated.h @@ -64,4 +64,12 @@ # define RBIMPL_ATTR_DEPRECATED(msg) /* void */ #endif +/** This is when a function is used internally (for backwards compatibility + * etc.), but extension libraries must consider it deprecated. */ +#if defined(RUBY_EXPORT) +# define RBIMPL_ATTR_DEPRECATED_EXT(msg) /* void */ +#else +# define RBIMPL_ATTR_DEPRECATED_EXT(msg) RBIMPL_ATTR_DEPRECATED(msg) +#endif + #endif /* RBIMPL_ATTR_DEPRECATED_H */ diff --git a/include/ruby/internal/intern/object.h b/include/ruby/internal/intern/object.h index 9736172085..6bb4ccb2fe 100644 --- a/include/ruby/internal/intern/object.h +++ b/include/ruby/internal/intern/object.h @@ -20,70 +20,549 @@ * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cObject. */ +#include "ruby/internal/attr/const.h" +#include "ruby/internal/attr/deprecated.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * This macro is (used but) mysterious. Why on earth do we need this? + * + * - `obj != orig` check is done anyways inside of rb_obj_init_copy(). + * - rb_obj_init_copy() returns something. No need are there to add `, 1`. + */ #define RB_OBJ_INIT_COPY(obj, orig) \ ((obj) != (orig) && (rb_obj_init_copy((obj), (orig)), 1)) +/** @old{RB_OBJ_INIT_COPY} */ #define OBJ_INIT_COPY(obj, orig) RB_OBJ_INIT_COPY(obj, orig) -VALUE rb_class_new_instance_pass_kw(int, const VALUE *, VALUE); -VALUE rb_class_new_instance(int, const VALUE*, VALUE); -VALUE rb_class_new_instance_kw(int, const VALUE*, VALUE, int); - /* object.c */ -int rb_eql(VALUE, VALUE); -VALUE rb_any_to_s(VALUE); -VALUE rb_inspect(VALUE); -VALUE rb_obj_is_instance_of(VALUE, VALUE); -VALUE rb_obj_is_kind_of(VALUE, VALUE); -VALUE rb_obj_alloc(VALUE); -VALUE rb_obj_clone(VALUE); -VALUE rb_obj_dup(VALUE); -VALUE rb_obj_init_copy(VALUE,VALUE); -VALUE rb_obj_taint(VALUE); + +/** + * Identical to rb_class_new_instance(), except it passes the passed keywords + * if any to the `#initialize` method. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arbitrary number of method arguments. + * @param[in] klass An instance of ::rb_cClass. + * @exception rb_eTypeError `klass`'s allocator is undefined. + * @exception rb_eException Any exceptions can happen inside. + * @return An allocated new instance of `klass`. + * @note This is _the_ implementation of `Object.new`. + */ +VALUE rb_class_new_instance_pass_kw(int argc, const VALUE *argv, VALUE klass); + +/** + * Allocates, then initialises an instance of the given class. It first calls + * the passed class' allocator to obtain an uninitialised object, then calls + * its initialiser with the remaining arguments. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to `#initialize`. + * @param[in] klass An instance of ::rb_cClass. + * @exception rb_eTypeError `klass`'s allocator is undefined. + * @exception rb_eException Any exceptions can happen inside. + * @return An allocated new instance of `klass`. + */ +VALUE rb_class_new_instance(int argc, const VALUE *argv, VALUE klass); + +/** + * Identical to rb_class_new_instance(), except you can specify how to handle + * the last element of the given array. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arbitrary number of method arguments. + * @param[in] klass An instance of ::rb_cClass. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * @exception rb_eTypeError `klass`'s allocator is undefined. + * @exception rb_eException Any exceptions can happen inside. + * @return An allocated new instance of `klass`. + */ +VALUE rb_class_new_instance_kw(int argc, const VALUE *argv, VALUE klass, int kw_splat); + +/** + * Checks for equality of the passed objects, in terms of `Object#eql?`. + * + * @param[in] lhs Comparison left hand side. + * @param[in] rhs Comparison right hand side. + * @retval RUBY_Qtrue They are equal. + * @retval RUBY_Qfalse Otherwise. + * @note This function actually calls `lhs.eql?(rhs)` so you cannot + * implement your class' `#eql?` method using it. + */ +int rb_eql(VALUE lhs, VALUE rhs); + +/** + * Generates a textual representation of the given object. + * + * @param[in] obj Arbitrary ruby object. + * @return An instance of ::rb_cString that represents `obj`. + * @note This is the default implementation of `Object#to_s` that each + * subclasses want to override. + */ +VALUE rb_any_to_s(VALUE obj); + +/** + * Generates a human-readable textual representation of the given object. This + * is largely similar to Ruby level `Object#inspect` but not the same; it + * additionally escapes the inspection result so that the string be compatible + * with that of default internal (or default external, if absent). + * + * @param[in] obj Arbitrary ruby object. + * @return An instance of ::rb_cString that represents `obj`. + */ +VALUE rb_inspect(VALUE obj); + +/** + * Queries if the given object is a direct instance of the given class. + * + * @param[in] obj Arbitrary ruby object. + * @param[in] klass An instance of ::rb_cModule. + * @exception rb_eTypeError `klass` is neither module nor class. + * @retval RUBY_Qtrue `obj` is an instance of `klass`. + * @retval RUBY_Qfalse Otherwise. + */ +VALUE rb_obj_is_instance_of(VALUE obj, VALUE klass); + +/** + * Queries if the given object is an instance (of possibly descendants) of the + * given class. + * + * @param[in] obj Arbitrary ruby object. + * @param[in] klass An instance of ::rb_cModule. + * @exception rb_eTypeError `klass` is neither module nor class. + * @retval RUBY_Qtrue `obj` is a `klass`. + * @retval RUBY_Qfalse Otherwise. + */ +VALUE rb_obj_is_kind_of(VALUE obj, VALUE klass); + +/** + * Allocates an instance of the given class. + * + * @param[in] klass A class to instantiate. + * @exception rb_eTypeError `klass` is not a class. + * @return An allocated, not yet initialised instance of `klass`. + * @note It calls the allocator defined by rb_define_alloc_func(). You + * cannot use this function to define an allocator. Use + * rb_newobj_of(), #TypedData_Make_Struct or others, instead. + * @note Usually prefer rb_class_new_instance() to rb_obj_alloc() and + * rb_obj_call_init(). + * @see rb_class_new_instance() + * @see rb_obj_call_init() + * @see rb_define_alloc_func() + * @see rb_newobj_of() + * @see #TypedData_Make_Struct + */ +VALUE rb_obj_alloc(VALUE klass); + +/** + * Produces a shallow copy of the given object. Its list of instance variables + * are copied, but not the objects they reference. It also copies the frozen + * value state. + * + * @param[in] obj Arbitrary ruby object. + * @exception rb_eException `#initialize_copy` can raise anything. + * @return A "clone" of `obj`. + * + * @internal + * + * Unlike ruby-level `Object#clone`, there is no way to control the frozen-ness + * of the return value. + */ +VALUE rb_obj_clone(VALUE obj); + +/** + * Duplicates the given object. This does almost the same thing as + * rb_obj_clone() do. However it does not copy the singleton class (if any). + * It also doesn't copy frozen-ness. + * + * @param[in] obj Arbitrary ruby object. + * @exception rb_eException `#initialize_copy` can raise anything. + * @return A shallow copy of `obj`. + */ +VALUE rb_obj_dup(VALUE obj); + +/** + * Default implementation of `#initialize_copy`, `#initialize_dup` and + * `#initialize_clone`. It does almost nothing. Just raises exceptions for + * checks. + * + * @param[in] dst The destination object. + * @param[in] src The source object. + * @exception rb_eFrozenError `dst` is frozen. + * @exception rb_eTypeError `dst` and `src` have different classes. + * @return Always returns `dst`. + */ +VALUE rb_obj_init_copy(VALUE src, VALUE dst); + +RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Verbatim `obj`. + */ +VALUE rb_obj_taint(VALUE obj); RBIMPL_ATTR_PURE() -VALUE rb_obj_tainted(VALUE); -VALUE rb_obj_untaint(VALUE); -VALUE rb_obj_untrust(VALUE); +RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Always returns ::RUBY_Qfalse. + */ +VALUE rb_obj_tainted(VALUE obj); + +RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Verbatim `obj`. + */ +VALUE rb_obj_untaint(VALUE obj); + +RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Verbatim `obj`. + */ +VALUE rb_obj_untrust(VALUE obj); RBIMPL_ATTR_PURE() -VALUE rb_obj_untrusted(VALUE); -VALUE rb_obj_trust(VALUE); -VALUE rb_obj_freeze(VALUE); +RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Always returns ::RUBY_Qfalse. + */ +VALUE rb_obj_untrusted(VALUE obj); + +RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @return Verbatim `obj`. + */ +VALUE rb_obj_trust(VALUE obj); + +/** + * Just calls rb_obj_freeze_inline() inside. Does this make any sens to + * extension libraries? + * + * @param[out] obj Object to freeze. + * @return Verbatim `obj`. + */ +VALUE rb_obj_freeze(VALUE obj); RBIMPL_ATTR_PURE() -VALUE rb_obj_frozen_p(VALUE); +/** + * Just calls RB_OBJ_FROZEN() inside. Does this make any sens to extension + * libraries? + * + * @param[in] obj Object in question. + * @retval RUBY_Qtrue Yes it is. + * @retval RUBY_Qfalse No it isn't. + */ +VALUE rb_obj_frozen_p(VALUE obj); + +/* gc.c */ + +/** + * Finds or creates an integer primary key of the given object. In the old + * days this function was a purely arithmetic operation that maps the + * underlying memory address where the object resides into a Ruby's integer. + * Some time around 2.x this changed. It no longer relates its return values + * to C level pointers. This function assigns some random number to the given + * object if absent. The same number will be returned on all subsequent + * requests. No two active objects share a number. + * + * @param[in] obj Arbitrary ruby object. + * @return An instance of ::rb_cInteger which is an "identifier" of `obj`. + * + * @internal + * + * The "some random number" is in fact a monotonic-increasing process-global + * unique integer, much like an `INTEGER AUTO_INCREMENT PRIMARY KEY` column in + * a MySQL table. + */ +VALUE rb_obj_id(VALUE obj); -VALUE rb_obj_id(VALUE); -VALUE rb_memory_id(VALUE); -VALUE rb_obj_class(VALUE); +RBIMPL_ATTR_CONST() +/** + * Identical to rb_obj_id(), except it hesitates from allocating a new instance + * of ::rb_cInteger. rb_obj_id() could allocate ::RUBY_T_BIGNUM objects. That + * allocation might perhaps impact negatively. On such situations, this + * function instead returns one-shot temporary small integers that need no + * allocations at all. The values are guaranteed unique at the moment, but no + * future promise is made; could be reused. Use of this API should be very + * instant. It is a failure to store the returned integer to somewhere else. + * + * In short it is difficult to use. + * + * @param[in] obj Arbitrary ruby object. + * @return An instance of ::rb_cInteger unique at the moment. + * + * @internal + * + * This is roughly the old behaviour of rb_obj_id(). + */ +VALUE rb_memory_id(VALUE obj); + +/* object.c */ RBIMPL_ATTR_PURE() -VALUE rb_class_real(VALUE); +/** + * Finds a "real" class. As the name implies there are class objects that are + * surreal. This function takes a class, traverses its ancestry tree, and + * returns its nearest ancestor which is neither a module nor a singleton + * class. + * + * @param[in] klass An instance of ::rb_cClass. + * @retval RUBY_Qfalse No real class in `klass`' ancestry tree. + * @retval klass `klass` itself is a real class. + * @retval otherwise Nearest ancestor of `klass` who is real. + */ +VALUE rb_class_real(VALUE klass); + +RBIMPL_ATTR_PURE() +/** + * Determines if the given two modules are relatives. + * + * @param[in] scion Possible subclass. + * @param[in] ascendant Possible superclass. + * @exception rb_eTypeError `ascendant` is not a module. + * @retval RUBY_Qtrue `scion` inherits, or is equal to `ascendant`. + * @retval RUBY_Qfalse `ascendant` inherits `scion`. + * @retval RUBY_Qnil They are not relatives. + */ +VALUE rb_class_inherited_p(VALUE scion, VALUE ascendant); RBIMPL_ATTR_PURE() -VALUE rb_class_inherited_p(VALUE, VALUE); -VALUE rb_class_superclass(VALUE); -VALUE rb_class_get_superclass(VALUE); -VALUE rb_convert_type(VALUE,int,const char*,const char*); -VALUE rb_check_convert_type(VALUE,int,const char*,const char*); -VALUE rb_check_to_integer(VALUE, const char *); -VALUE rb_check_to_float(VALUE); -VALUE rb_to_int(VALUE); -VALUE rb_check_to_int(VALUE); -VALUE rb_Integer(VALUE); -VALUE rb_to_float(VALUE); -VALUE rb_Float(VALUE); -VALUE rb_String(VALUE); -VALUE rb_Array(VALUE); -VALUE rb_Hash(VALUE); -double rb_cstr_to_dbl(const char*, int); -double rb_str_to_dbl(VALUE, int); +/** + * Queries the parent of the given class. + * + * @param[in] klass A child class. + * @exception rb_eTypeError `klass` is a `Class.allocate`. + * @retval RUBY_Qfalse `klass` has no superclass. + * @retval otherwise `klass`' superclass. + * + * @internal + * + * Is there any class except ::rb_cBasicObject, that has no superclass? + */ +VALUE rb_class_superclass(VALUE klass); + +RBIMPL_ATTR_NONNULL(()) +/** + * Converts an object into another type. Calls the specified conversion method + * if necessary. + * + * @param[in] val An object to convert. + * @param[in] type A value of enum ::ruby_value_type. + * @param[in] name Name to display on error (e.g. "Array"). + * @param[in] mid Conversion method (e.g. "to_ary"). + * @exception rb_eTypeError Failed to convert. + * @return An object of the specified type. + */ +VALUE rb_convert_type(VALUE val, int type, const char *name, const char *mid); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_convert_type(), except it returns ::RUBY_Qnil instead of + * raising exceptions, in case of conversion failure. It still raises + * exceptions for various reasons, like when the conversion method itself + * raises, though. + * + * @param[in] val An object to convert. + * @param[in] type A value of enum ::ruby_value_type. + * @param[in] name Name to display on error (e.g. "Array"). + * @param[in] mid Conversion method (e.g. "to_ary"). + * @exception rb_eTypeError The `mid` does not generate `type`. + * @retval RUBY_Qnil No conversion defined. + * @retval otherwise An object of the specified type. + */ +VALUE rb_check_convert_type(VALUE val, int type, const char *name, const char *mid); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_check_convert_type(), except the return value type is fixed + * to ::rb_cInteger. + * + * @param[in] val An object to convert. + * @param[in] mid Conversion method (e.g. "to_ary"). + * @exception rb_eTypeError The `mid` does not generate an integer. + * @retval RUBY_Qnil No conversion defined. + * @retval otherwise An instance of ::rb_cInteger. + */ +VALUE rb_check_to_integer(VALUE val, const char *mid); + +/** + * This is complicated. + * + * - When the passed object is already an instance of ::rb_cFloat, just + * returns it as-is. + * + * - When the passed object is something numeric, the function tries to + * convert it using `#to_f` method. + * + * - If that conversion fails (this happens for instance when the numeric + * is a complex) it returns ::RUBY_Qnil. + * + * - Otherwise returns the conversion result. + * + * - Otherwise it also returns ::RUBY_Qnil. + * + * @param[in] val An object to convert. + * @retval RUBY_Qnil Conversion from `val` to float is undefined. + * @retval otherwise Converted result. + */ +VALUE rb_check_to_float(VALUE val); + +/** + * Identical to rb_check_to_int(), except it raises in case of conversion + * mismatch. + * + * @param[in] val An object to convert. + * @exception rb_eTypeError `#to_int` does not generate an integer. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_to_int(VALUE val); + +/** + * Identical to rb_check_to_integer(), except it uses `#to_int` for conversion. + * + * @param[in] val An object to convert. + * @exception rb_eTypeError `#to_int` does not return an integer. + * @retval RUBY_Qnil No conversion defined. + * @retval otherwise An instance of ::rb_cInteger. + */ +VALUE rb_check_to_int(VALUE val); + +/** + * This is the logic behind `Kernel#Integer`. Numeric types are converted + * directly, with floating point numbers being truncated. Strings are + * interpreted strictly; only leading/trailing whitespaces, plus/minus sign, + * radix indicators such as `0x`, digits, and underscores are allowed. + * Anything else are converted by first trying `#to_int`, then `#to_i`. + * + * This is slightly stricter than `String#to_i`. + * + * @param[in] val An object to convert. + * @exception rb_eArgError Malformed `val` passed. + * @exception rb_eTypeError No conversion defined. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_Integer(VALUE val); + +/** + * Identical to rb_check_to_float(), except it raises on error. + * + * @param[in] val An object to convert. + * @exception rb_eTypeError No conversion defined. + * @return An instance of ::rb_cFloat. + */ +VALUE rb_to_float(VALUE val); + +/** + * This is the logic behind `Kernel#Float`. Numeric types are converted + * directly to the nearest value that a Float can represent. Strings are + * interpreted strictly; only leading/trailing whitespaces are allowed except + * what `strtod` understands. Anything else are converted using `#to_f`. + * + * This is slightly stricter than `String#to_f`. + * + * @param[in] val An object to convert. + * @exception rb_eArgError Malformed `val` passed. + * @exception rb_eTypeError No conversion defined. + * @return An instance of ::rb_cFloat. + */ +VALUE rb_Float(VALUE val); + +/** + * This is the logic behind `Kernel#String`. Arguments are converted by first + * trying `#to_str`, then `#to_s`. + * + * @param[in] val An object to convert. + * @exception rb_eTypeError No conversion defined. + * @return An instance of ::rb_cString. + */ +VALUE rb_String(VALUE val); + +/** + * This is the logic behind `Kernel#Array`. Arguments are converted by first + * trying `#to_ary`, then `#to_a`, and if both failed, returns an array of + * length 1 that contains the passed argument as the sole contents. + * + * @param[in] val An object to convert. + * @return An instance of ::rb_cArray. + */ +VALUE rb_Array(VALUE val); + +/** + * This is the logic behind `Kernel#Hash`. Arguments are converted by first + * trying `#to_hash`. if it failed, and the argument is either ::RUBY_Qnil or + * an empty array, returns an empty hash. Otherwise an exception is raised. + * + * @param[in] val An object to convert. + * @exception rb_eTypeError No conversion defined. + * @return An instance of ::rb_cHash. + */ +VALUE rb_Hash(VALUE val); + +RBIMPL_ATTR_NONNULL(()) +/** + * Converts a textual representation of a real number into a numeric, which is + * the nearest value that the return type can represent, of the value that the + * argument represents. This is in fact a 2-in-1 function whose behaviour can + * be controlled using the second (mode) argument. If the mode is zero, this + * function is in "historical" mode which only understands "floating-constant" + * defined at ISO/IEC 9899:1990 section 6.1.3.1. If the mode is nonzero, it is + * in "extended" mode, which also accepts "hexadecimal-floating-constant" + * defined at ISO/IEC 9899:2018 section 6.4.4.2. + * + * @param[in] str A textual representation of a real number. + * @param[in] mode Conversion mode, as described above. + * @exception rb_eArgError Malformed `str` passed. + * @see https://bugs.ruby-lang.org/issues/2969 + * @note Null pointers are allowed, and it returns 0.0 then. + */ +double rb_cstr_to_dbl(const char *str, int mode); + +/** + * Identical to rb_cstr_to_dbl(), except it accepts a Ruby's string instead of + * C's. + * + * @param[in] str A textual representation of a real number. + * @param[in] mode Conversion mode, as described in rb_cstr_to_dbl(). + * @exception rb_eArgError Malformed `str` passed. + * @see https://bugs.ruby-lang.org/issues/2969 + */ +double rb_str_to_dbl(VALUE str, int mode); RBIMPL_SYMBOL_EXPORT_END() @@ -139,15 +139,6 @@ rb_equal(VALUE obj1, VALUE obj2) return RBOOL(RTEST(result)); } -/** - * Determines if \a obj1 and \a obj2 are equal in terms of - * \c Object#eql?. - * - * \note It actually calls \c #eql? when necessary. - * So you cannot implement \c #eql? with this function. - * \retval non-zero if they are eql? - * \retval zero if they are not eql?. - */ int rb_eql(VALUE obj1, VALUE obj2) { @@ -243,14 +234,6 @@ rb_obj_not_equal(VALUE obj1, VALUE obj2) return RTEST(result) ? Qfalse : Qtrue; } -/*! - * Looks up the nearest ancestor of \a cl, skipping singleton classes or - * module inclusions. - * It returns the \a cl itself if it is neither a singleton class or a module. - * - * \param[in] cl a Class object. - * \return the ancestor class found, or Qfalse if nothing found. - */ VALUE rb_class_real(VALUE cl) { @@ -478,12 +461,6 @@ mutable_obj_clone(VALUE obj, VALUE kwfreeze) return clone; } -/** - * :nodoc - *-- - * Almost same as \c Object#clone - *++ - */ VALUE rb_obj_clone(VALUE obj) { @@ -491,7 +468,7 @@ rb_obj_clone(VALUE obj) return mutable_obj_clone(obj, Qnil); } -/** +/* * call-seq: * obj.dup -> an_object * @@ -529,9 +506,6 @@ rb_obj_clone(VALUE obj) * * s3 = s1.dup #=> #<Klass:0x401c1084> * s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401c1084> - *-- - * Equivalent to \c Object\#dup in Ruby - *++ */ VALUE rb_obj_dup(VALUE obj) @@ -634,7 +608,7 @@ rb_obj_init_clone(int argc, VALUE *argv, VALUE obj) return obj; } -/** +/* * call-seq: * obj.to_s -> string * @@ -643,9 +617,6 @@ rb_obj_init_clone(int argc, VALUE *argv, VALUE obj) * case, the top-level object that is the initial execution context * of Ruby programs returns ``main''. * - *-- - * Default implementation of \c #to_s. - *++ */ VALUE rb_any_to_s(VALUE obj) @@ -658,18 +629,6 @@ rb_any_to_s(VALUE obj) return str; } -/*! - * Convenient wrapper of \c Object#inspect. - * Returns a human-readable string representation of \a obj, - * similarly to \c Object#inspect. - * - * Unlike Ruby-level \c #inspect, it escapes characters to keep the - * result compatible to the default internal or external encoding. - * If the default internal or external encoding is ASCII compatible, - * the encoding of the inspected result must be compatible with it. - * If the default internal or external encoding is ASCII incompatible, - * the result must be ASCII only. - */ VALUE rb_inspect(VALUE obj) { @@ -784,7 +743,7 @@ class_or_module_required(VALUE c) static VALUE class_search_ancestor(VALUE cl, VALUE c); -/** +/* * call-seq: * obj.instance_of?(class) -> true or false * @@ -799,13 +758,6 @@ static VALUE class_search_ancestor(VALUE cl, VALUE c); * b.instance_of? A #=> false * b.instance_of? B #=> true * b.instance_of? C #=> false - *-- - * Determines if \a obj is an instance of \a c. - * - * Equivalent to \c Object\#is_instance_of in Ruby. - * \param[in] obj the object to be determined. - * \param[in] c a Class object - *++ */ VALUE @@ -816,7 +768,7 @@ rb_obj_is_instance_of(VALUE obj, VALUE c) } -/** +/* * call-seq: * obj.is_a?(class) -> true or false * obj.kind_of?(class) -> true or false @@ -842,13 +794,6 @@ rb_obj_is_instance_of(VALUE obj, VALUE c) * b.kind_of? B #=> true * b.kind_of? C #=> false * b.kind_of? M #=> true - *-- - * Determines if \a obj is a kind of \a c. - * - * Equivalent to \c Object\#kind_of? in Ruby. - * \param[in] obj the object to be determined - * \param[in] c a Module object. - *++ */ VALUE @@ -1163,7 +1108,7 @@ rb_obj_dummy1(VALUE _x, VALUE _y) return rb_obj_dummy(); } -/** +/* * call-seq: * obj.tainted? -> false * @@ -1177,7 +1122,7 @@ rb_obj_tainted(VALUE obj) return Qfalse; } -/** +/* * call-seq: * obj.taint -> obj * @@ -1192,7 +1137,7 @@ rb_obj_taint(VALUE obj) } -/** +/* * call-seq: * obj.untaint -> obj * @@ -1206,7 +1151,7 @@ rb_obj_untaint(VALUE obj) return obj; } -/** +/* * call-seq: * obj.untrusted? -> false * @@ -1220,7 +1165,7 @@ rb_obj_untrusted(VALUE obj) return Qfalse; } -/** +/* * call-seq: * obj.untrust -> obj * @@ -1235,7 +1180,7 @@ rb_obj_untrust(VALUE obj) } -/** +/* * call-seq: * obj.trust -> obj * @@ -1255,7 +1200,7 @@ rb_obj_infect(VALUE victim, VALUE carrier) rb_warn_deprecated_to_remove_at(3.2, "rb_obj_infect", NULL); } -/** +/* * call-seq: * obj.freeze -> obj * @@ -1277,11 +1222,6 @@ rb_obj_infect(VALUE victim, VALUE carrier) * * Objects of the following classes are always frozen: Integer, * Float, Symbol. - *-- - * Make the object unmodifiable. Equivalent to \c Object\#freeze in Ruby. - * \param[in,out] obj the object to be frozen - * \return the frozen object - *++ */ VALUE @@ -1720,7 +1660,7 @@ rb_mod_eqq(VALUE mod, VALUE arg) return rb_obj_is_kind_of(arg, mod); } -/** +/* * call-seq: * mod <= other -> true, false, or nil * @@ -1729,15 +1669,6 @@ rb_mod_eqq(VALUE mod, VALUE arg) * <code>nil</code> if there's no relationship between the two. * (Think of the relationship in terms of the class definition: * "class A < B" implies "A < B".) - *-- - * Determines if \a mod inherits \a arg. Equivalent to \c Module\#<= in Ruby - * - * \param[in] mod a Module object - * \param[in] arg another Module object or an iclass of a module - * \retval Qtrue if \a mod inherits \a arg, or \a mod equals \a arg - * \retval Qfalse if \a arg inherits \a mod - * \retval Qnil if otherwise - *++ */ VALUE @@ -2048,20 +1979,6 @@ class_call_alloc_func(rb_alloc_func_t allocator, VALUE klass) return obj; } -/** - * Allocates an instance of \a klass - * - * \note It calls the allocator defined by {rb_define_alloc_func}. - * So you cannot use this function to define an allocator. - * Use {rb_newobj_of}, {TypedData_Make_Struct} or others, instead. - * \note Usually prefer rb_class_new_instance to rb_obj_alloc and rb_obj_call_init - * \param[in] klass a Class object - * \sa rb_class_new_instance - * \sa rb_obj_call_init - * \sa rb_define_alloc_func - * \sa rb_newobj_of - * \sa TypedData_Make_Struct - */ VALUE rb_obj_alloc(VALUE klass) { @@ -2103,18 +2020,6 @@ rb_class_new_instance_kw(int argc, const VALUE *argv, VALUE klass, int kw_splat) return obj; } -/** - * Allocates and initializes an instance of \a klass. - * - * Equivalent to \c Class\#new in Ruby - * - * \param[in] argc the number of arguments to \c #initialize - * \param[in] argv a pointer to an array of arguments to \c #initialize - * \param[in] klass a Class object - * \return the new instance of \a klass - * \sa rb_obj_call_init - * \sa rb_obj_alloc - */ VALUE rb_class_new_instance(int argc, const VALUE *argv, VALUE klass) { @@ -3099,19 +3004,6 @@ conversion_mismatch(VALUE val, const char *tname, const char *method, VALUE resu cname, tname, cname, method, rb_obj_class(result)); } -/*! - * Converts an object into another type. - * Calls the specified conversion method if necessary. - * - * \param[in] val the object to be converted - * \param[in] type a value of \c ruby_value_type - * \param[in] tname name of the target type. - * only used for error messages. - * \param[in] method name of the method - * \return an object of the specified type - * \throw TypeError on failure - * \sa rb_check_convert_type - */ VALUE rb_convert_type(VALUE val, int type, const char *tname, const char *method) { @@ -3139,20 +3031,6 @@ rb_convert_type_with_id(VALUE val, int type, const char *tname, ID method) return v; } -/*! - * Tries to convert an object into another type. - * Calls the specified conversion method if necessary. - * - * \param[in] val the object to be converted - * \param[in] type a value of \c ruby_value_type - * \param[in] tname name of the target type. - * only used for error messages. - * \param[in] method name of the method - * \return an object of the specified type, or Qnil if no such conversion method defined. - * \throw TypeError if the conversion method returns an unexpected type of value. - * \sa rb_convert_type - * \sa rb_check_convert_type_with_id - */ VALUE rb_check_convert_type(VALUE val, int type, const char *tname, const char *method) { @@ -3205,16 +3083,6 @@ rb_to_integer_with_id_exception(VALUE val, const char *method, ID mid, int raise #define rb_to_integer(val, method, mid) \ rb_to_integer_with_id_exception(val, method, mid, TRUE) -/** - * Tries to convert \a val into \c Integer. - * It calls the specified conversion method if necessary. - * - * \param[in] val a Ruby object - * \param[in] method a name of a method - * \return an \c Integer object on success, - * or \c Qnil if no such conversion method defined. - * \exception TypeError if the conversion method returns a non-Integer object. - */ VALUE rb_check_to_integer(VALUE val, const char *method) { @@ -3228,29 +3096,12 @@ rb_check_to_integer(VALUE val, const char *method) return v; } -/** - * Converts \a val into \c Integer. - * It calls \a #to_int method if necessary. - * - * \param[in] val a Ruby object - * \return an \c Integer object - * \exception TypeError on failure - */ VALUE rb_to_int(VALUE val) { return rb_to_integer(val, "to_int", idTo_int); } -/** - * Tries to convert \a val into Integer. - * It calls \c #to_int method if necessary. - * - * \param[in] val a Ruby object - * \return an Integer object on success, - * or \c Qnil if \c #to_int is not defined. - * \exception TypeError if \c #to_int returns a non-Integer object. - */ VALUE rb_check_to_int(VALUE val) { @@ -3317,12 +3168,6 @@ rb_convert_to_integer(VALUE val, int base, int raise_exception) return rb_to_integer(val, "to_i", idTo_i); } -/** - * Equivalent to \c Kernel\#Integer in Ruby. - * - * Converts \a val into \c Integer in a slightly more strict manner - * than \c #to_i. - */ VALUE rb_Integer(VALUE val) { @@ -3537,17 +3382,6 @@ rb_cstr_to_dbl_raise(const char *p, int badcheck, int raise, int *error) } } -/*! - * Parses a string representation of a floating point number. - * - * \param[in] p a string representation of a floating number - * \param[in] badcheck raises an exception on parse error if \a badcheck is non-zero. - * \return the floating point number in the string on success, - * 0.0 on parse error and \a badcheck is zero. - * \note it always fails to parse a hexadecimal representation like "0xAB.CDp+1" when - * \a badcheck is zero, even though it would success if \a badcheck was non-zero. - * This inconsistency is coming from a historical compatibility reason. [ruby-dev:40822] - */ double rb_cstr_to_dbl(const char *p, int badcheck) { @@ -3589,17 +3423,6 @@ rb_str_to_dbl_raise(VALUE str, int badcheck, int raise, int *error) FUNC_MINIMIZED(double rb_str_to_dbl(VALUE str, int badcheck)); -/*! - * Parses a string representation of a floating point number. - * - * \param[in] str a \c String object representation of a floating number - * \param[in] badcheck raises an exception on parse error if \a badcheck is non-zero. - * \return the floating point number in the string on success, - * 0.0 on parse error and \a badcheck is zero. - * \note it always fails to parse a hexadecimal representation like "0xAB.CDp+1" when - * \a badcheck is zero, even though it would success if \a badcheck was non-zero. - * This inconsistency is coming from a historical compatibility reason. [ruby-dev:40822] - */ double rb_str_to_dbl(VALUE str, int badcheck) { @@ -3716,12 +3539,6 @@ rb_convert_to_float(VALUE val, int raise_exception) FUNC_MINIMIZED(VALUE rb_Float(VALUE val)); -/*! - * Equivalent to \c Kernel\#Float in Ruby. - * - * Converts \a val into \c Float in a slightly more strict manner - * than \c #to_f. - */ VALUE rb_Float(VALUE val) { @@ -3745,11 +3562,6 @@ numeric_to_float(VALUE val) return rb_convert_type_with_id(val, T_FLOAT, "Float", id_to_f); } -/*! - * Converts a \c Numeric object into \c Float. - * \param[in] val a \c Numeric object - * \exception TypeError if \a val is not a \c Numeric or other conversion failures. - */ VALUE rb_to_float(VALUE val) { @@ -3760,13 +3572,6 @@ rb_to_float(VALUE val) return numeric_to_float(val); } -/*! - * Tries to convert an object into \c Float. - * It calls \c #to_f if necessary. - * - * It returns \c Qnil if the object is not a \c Numeric - * or \c #to_f is not defined on the object. - */ VALUE rb_check_to_float(VALUE val) { @@ -3858,12 +3663,6 @@ rb_num2dbl(VALUE val) return RFLOAT_VALUE(val); } -/*! - * Equivalent to \c Kernel\#String in Ruby. - * - * Converts \a val into \c String by trying \c #to_str at first and - * then trying \c #to_s. - */ VALUE rb_String(VALUE val) { @@ -3893,9 +3692,6 @@ rb_f_string(VALUE obj, VALUE arg) return rb_String(arg); } -/*! - * Equivalent to \c Kernel\#Array in Ruby. - */ VALUE rb_Array(VALUE val) { |