← Back
Editing: numeric.h
#ifndef RBIMPL_INTERN_NUMERIC_H /*-*-C++-*-vi:se ft=cpp:*/ #define RBIMPL_INTERN_NUMERIC_H /** * @file * @author Ruby developers <ruby-core@ruby-lang.org> * @copyright This file is a part of the programming language Ruby. * Permission is hereby granted, to either redistribute and/or * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. * @warning Symbols prefixed with either `RBIMPL` or `rbimpl` are * implementation details. Don't take them as canon. They could * rapidly appear then vanish. The name (path) of this header file * is also an implementation detail. Do not expect it to persist * at the place it is now. Developers are free to move it anywhere * anytime at will. * @note To ruby-core: remember that this header can be possibly * recursively included from extension libraries written in C++. * Do not expect for instance `__VA_ARGS__` is always available. * We assume C99 for ruby itself but we don't assume languages of * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cNumeric. */ #include "ruby/internal/attr/cold.h" #include "ruby/internal/attr/noreturn.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" /** * @private * * @deprecated This macro 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. */ #define RB_NUM_COERCE_FUNCS_NEED_OPID 1 RBIMPL_SYMBOL_EXPORT_BEGIN() /* numeric.c */ RBIMPL_ATTR_NORETURN() RBIMPL_ATTR_COLD() /** * Just always raises an exception. * * @exception rb_eZeroDivError Division by zero error. */ void rb_num_zerodiv(void); /** * @name Coercion operators. * * What is a coercion? Well Ruby is basically an OOPL but it also has * arithmetic operators. They are implemented in OO manners. For instance * `a+b` is a binary operation `+`, whose receiver is `a`, and whose (sole) * argument is `b`. * * The problem is, you often want `a+b == b+a` to hold. That is easy if both * `a` and `b` belongs to the same class... Ensuring `1 + 2 == 2 + 1` is kind * of intuitive. But if you want `1.0 + 2 == 2 + 1.0`, things start getting * complicated. `1.0+2` is `Float#+`, while `2+1.0` is `Integer#+`. In order * to achieve the equality Float's and Integer's methods must agree with their * behaviours. * * Now. Floats versus Integers situation is still controllable because they * are both built-in. But in Ruby you can define your own numeric classes. * BigDecimal, which is a rubygems gem distributed along with the interpreter, * is one of such examples. Rational was another such example before. In * short you cannot create list of all possible combination of the classes that * could be the operand of `+` operator. Then how do we achieve the * commutativity? * * Here comes the concept of coercion. If a definition of an operator * encounters an object which is unknown to the author, just assumes that the * unknown object knows how to handle the situation. So for instance when * `1+x` has unknown `x`, it lets the `x` handle this. * * ```ruby * class Foo * def +(x) * if we_know_what_is_x? then * ... # handle here * else * y, z = x.coerce self * return y + z * end * end * end * ``` * * The `x.coerce` method returns a 2-element array which are "casted" versions * of `x` and `self`. * * @{ */ /** * Coerced binary operation. This function first coerces the two objects, then * applies the operation. * * @param[in] lhs LHS operand. * @param[in] rhs RHS operand. * @param[in] op Operator method name. * @exception rb_eTypeError Coercion failed for some reason. * @return `lhs op rhs`, in a coerced way. */ VALUE rb_num_coerce_bin(VALUE lhs, VALUE rhs, ID op); /** * Identical to rb_num_coerce_bin(), except for return values. This function * best suits for comparison operators e.g. `<=>`. * * @param[in] lhs LHS operand. * @param[in] rhs RHS operand. * @param[in] op Operator method name. * @retval RUBY_Qnil Coercion failed for some reason. * @retval otherwise `lhs op rhs`, in a coerced way. */ VALUE rb_num_coerce_cmp(VALUE lhs, VALUE rhs, ID op); /** * Identical to rb_num_coerce_cmp(), except for return values. This function * best suits for relationship operators e.g. `<=`. * * @param[in] lhs LHS operand. * @param[in] rhs RHS operand. * @param[in] op Operator method name. * @exception rb_eArgError Coercion failed for some reason. * @return `lhs op rhs`, in a coerced way. */ VALUE rb_num_coerce_relop(VALUE lhs, VALUE rhs, ID op); /** * This one is optimised for bitwise operations, but the API is identical to * rb_num_coerce_bin(). * * @param[in] lhs LHS operand. * @param[in] rhs RHS operand. * @param[in] op Operator method name. * @exception rb_eArgError Coercion failed for some reason. * @return `lhs op rhs`, in a coerced way. */ VALUE rb_num_coerce_bit(VALUE lhs, VALUE rhs, ID op); /** @} */ /** * Converts a numeric value into a Fixnum. This is not a preserving * conversion; for instance 1.5 would be converted into 1. * * @param[in] val A numeric object. * @exception rb_eTypeError No conversion from `val` to Integer. * @exception rb_eRangeError `val` out of range. * @return A fixnum converted from `val`. * * @internal * * This seems used from nowhere? */ VALUE rb_num2fix(VALUE val); /** * Generates a place-value representation of the given Fixnum, with given * radix. * * @param[in] val A fixnum to stringify. * @param[in] base `2` to `36` inclusive for each radix. * @exception rb_eArgError `base` is out of range. * @return An instance of ::rb_cString representing `val`. * @pre `val` must be a Fixnum (no checks performed). */ VALUE rb_fix2str(VALUE val, int base); RBIMPL_ATTR_CONST() /** * Compares two `double`s. Handy when implementing a spaceship operator. * * @param[in] lhs A value. * @param[in] rhs Another value. * @retval RB_INT2FIX(-1) `lhs` is "bigger than" `rhs`. * @retval RB_INT2FIX(1) `rhs` is "bigger than" `lhs`. * @retval RB_INT2FIX(0) They are equal. * @retval RUBY_Qnil Not comparable, e.g. NaN. */ VALUE rb_dbl_cmp(double lhs, double rhs); /** * Raises the passed `x` to the power of `y`. * * @note The return value can be really big. * @note Also the return value can be really small, in case `x` is a * negative number. * @param[in] x A number. * @param[in] y Another number. * @retval Inf Cannot express the result. * @retval 1 Either `y` is 0 or `x` is 1. * @retval otherwise An instance of ::rb_cInteger whose value is `x ** y`. * * @internal * * This function returns Infinity when `y` is big enough not to fit into a * Fixnum. Warning is issued then. */ RUBY_EXTERN VALUE rb_int_positive_pow(long x, unsigned long y); RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_INTERN_NUMERIC_H */
Save File
Cancel