kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

include/ruby/internal/intern/object.h: add doxygen

Browse source 
Must not be a bad idea to improve documents. [ci skip]
This commit is contained in:
卜部昌平 2021-03-11 16:34:49 +09:00
parent 4f97917474
commit d43accae15
Notes: git 2021-09-10 20:01:32 +09:00
3 changed files with 542 additions and 259 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
include/ruby/internal/attr/deprecated.h
View file

@ -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 */

565
include/ruby/internal/intern/object.h
View file

@ -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 */
/**
* 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()
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()
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()
/**
* 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);
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 */
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);
RBIMPL_ATTR_PURE()
VALUE rb_obj_tainted(VALUE);
VALUE rb_obj_untaint(VALUE);
VALUE rb_obj_untrust(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()
VALUE rb_obj_untrusted(VALUE);
VALUE rb_obj_trust(VALUE);
VALUE rb_obj_freeze(VALUE);
/**
* 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_obj_frozen_p(VALUE);
/**
* 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);
VALUE rb_obj_id(VALUE);
VALUE rb_memory_id(VALUE);
VALUE rb_obj_class(VALUE);
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_PURE()
VALUE rb_class_real(VALUE);
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_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);
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()

228
object.c
View file

@ -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)
{