Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros | Functions
bignum.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Public APIs related to so-called rb_cBignum. More...

#include "ruby/internal/config.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/backward/2/long_long.h"
Include dependency graph for bignum.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define rb_big2int(x)   rb_big2long(x)
 Just another name of rb_big2long. More...
 
#define rb_big2uint(x)   rb_big2ulong(x)
 Just another name of rb_big2long. More...
 
Flags for rb_integer_pack()/rb_integer_unpack()
#define INTEGER_PACK_MSWORD_FIRST   0x01
 Stores/interprets the most significant word as the first word. More...
 
#define INTEGER_PACK_LSWORD_FIRST   0x02
 Stores/interprets the least significant word as the first word. More...
 
#define INTEGER_PACK_MSBYTE_FIRST   0x10
 Stores/interprets the most significant byte in a word as the first byte in the word. More...
 
#define INTEGER_PACK_LSBYTE_FIRST   0x20
 Stores/interprets the least significant byte in a word as the first byte in the word. More...
 
#define INTEGER_PACK_NATIVE_BYTE_ORDER   0x40
 Means either INTEGER_PACK_MSBYTE_FIRST or INTEGER_PACK_LSBYTE_FIRST, depending on the host processor's endian. More...
 
#define INTEGER_PACK_2COMP   0x80
 Uses 2's complement representation. More...
 
#define INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION   0x400
 Uses "generic" implementation (handy on test). More...
 
#define INTEGER_PACK_FORCE_BIGNUM   0x100
 Always generates a bignum object even if the integer can be representable using fixnum scheme (unpack only) More...
 
#define INTEGER_PACK_NEGATIVE   0x200
 Interprets the input as a signed negative number (unpack only). More...
 
#define INTEGER_PACK_LITTLE_ENDIAN
 Little endian combination. More...
 
#define INTEGER_PACK_BIG_ENDIAN
 Big endian combination. More...
 

Functions

VALUE rb_big_new (size_t len, int sign)
 Allocates a bignum object. More...
 
int rb_bigzero_p (VALUE x)
 Queries if the passed bignum instance is a "bigzero". More...
 
VALUE rb_big_clone (VALUE num)
 Duplicates the given bignum. More...
 
void rb_big_2comp (VALUE num)
 Destructively modify the passed bignum into 2's complement representation. More...
 
VALUE rb_big_norm (VALUE x)
 Normalises the passed bignum. More...
 
void rb_big_resize (VALUE big, size_t len)
 Destructively resizes the backend storage of the passed bignum. More...
 
VALUE rb_cstr_to_inum (const char *str, int base, int badcheck)
 Parses C's string to convert into a Ruby's integer. More...
 
VALUE rb_str_to_inum (VALUE str, int base, int badcheck)
 Identical to rb_cstr2inum(), except it takes Ruby's strings instead of C's. More...
 
VALUE rb_cstr2inum (const char *str, int base)
 Identical to rb_cstr_to_inum(), except the second argument controls the base and badcheck at once. More...
 
VALUE rb_str2inum (VALUE str, int base)
 Identical to rb_str_to_inum(), except the second argument controls the base and badcheck at once. More...
 
VALUE rb_big2str (VALUE x, int base)
 Generates a place-value representation of the passed integer. More...
 
long rb_big2long (VALUE x)
 Converts a bignum into C's long. More...
 
unsigned long rb_big2ulong (VALUE x)
 Converts a bignum into C's unsigned long. More...
 
void rb_big_pack (VALUE val, unsigned long *buf, long num_longs)
 Converts a bignum into a series of its parts. More...
 
VALUE rb_big_unpack (unsigned long *buf, long num_longs)
 Constructs a (possibly very big) bignum from a series of integers. More...
 
int rb_uv_to_utf8 (char buf[6], unsigned long uv)
 Encodes a Unicode codepoint into its UTF-8 representation. More...
 
VALUE rb_dbl2big (double d)
 Converts a C's double into a bignum. More...
 
double rb_big2dbl (VALUE x)
 Converts a bignum into C's double. More...
 
VALUE rb_big_cmp (VALUE lhs, VALUE rhs)
 Compares the passed two bignums. More...
 
VALUE rb_big_eq (VALUE lhs, VALUE rhs)
 Equality, in terms of ==. More...
 
VALUE rb_big_eql (VALUE lhs, VALUE rhs)
 Equality, in terms of eql?. More...
 
VALUE rb_big_plus (VALUE x, VALUE y)
 Performs addition of the passed two objects. More...
 
VALUE rb_big_minus (VALUE x, VALUE y)
 Performs subtraction of the passed two objects. More...
 
VALUE rb_big_mul (VALUE x, VALUE y)
 Performs multiplication of the passed two objects. More...
 
VALUE rb_big_div (VALUE x, VALUE y)
 Performs division of the passed two objects. More...
 
VALUE rb_big_idiv (VALUE x, VALUE y)
 Performs "integer division". More...
 
VALUE rb_big_modulo (VALUE x, VALUE y)
 Performs modulo of the passed two objects. More...
 
VALUE rb_big_divmod (VALUE x, VALUE y)
 Performs "divmod" operation. More...
 
VALUE rb_big_pow (VALUE x, VALUE y)
 Raises x to the powerof y. More...
 
VALUE rb_big_and (VALUE x, VALUE y)
 Performs bitwise and of the passed two objects. More...
 
VALUE rb_big_or (VALUE x, VALUE y)
 Performs bitwise or of the passed two objects. More...
 
VALUE rb_big_xor (VALUE x, VALUE y)
 Performs exclusive or of the passed two objects. More...
 
VALUE rb_big_lshift (VALUE x, VALUE y)
 Performs shift left. More...
 
VALUE rb_big_rshift (VALUE x, VALUE y)
 Performs shift right. More...
 
int rb_integer_pack (VALUE val, void *words, size_t numwords, size_t wordsize, size_t nails, int flags)
 Exports an integer into a buffer. More...
 
VALUE rb_integer_unpack (const void *words, size_t numwords, size_t wordsize, size_t nails, int flags)
 Import an integer from a buffer. More...
 
size_t rb_absint_size (VALUE val, int *nlz_bits_ret)
 Calculates the number of bytes needed to represent the absolute value of the passed integer. More...
 
size_t rb_absint_numwords (VALUE val, size_t word_numbits, size_t *nlz_bits_ret)
 Calculates the number of words needed represent the absolute value of the passed integer. More...
 
int rb_absint_singlebit_p (VALUE val)
 Tests abs(val) consists only of a bit or not. More...
 

Detailed Description

Public APIs related to so-called rb_cBignum.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
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.

Definition in file bignum.h.

Macro Definition Documentation

◆ INTEGER_PACK_2COMP

#define INTEGER_PACK_2COMP   0x80

Uses 2's complement representation.

Definition at line 549 of file bignum.h.

◆ INTEGER_PACK_BIG_ENDIAN

#define INTEGER_PACK_BIG_ENDIAN
Value:
INTEGER_PACK_MSBYTE_FIRST)
#define INTEGER_PACK_MSWORD_FIRST
Stores/interprets the most significant word as the first word.
Definition: bignum.h:525

Big endian combination.

Definition at line 572 of file bignum.h.

◆ INTEGER_PACK_FORCE_BIGNUM

#define INTEGER_PACK_FORCE_BIGNUM   0x100

Always generates a bignum object even if the integer can be representable using fixnum scheme (unpack only)

Definition at line 558 of file bignum.h.

◆ INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION

#define INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION   0x400

Uses "generic" implementation (handy on test).

Definition at line 552 of file bignum.h.

◆ INTEGER_PACK_LITTLE_ENDIAN

#define INTEGER_PACK_LITTLE_ENDIAN
Value:
INTEGER_PACK_LSBYTE_FIRST)
#define INTEGER_PACK_LSWORD_FIRST
Stores/interprets the least significant word as the first word.
Definition: bignum.h:528

Little endian combination.

Definition at line 567 of file bignum.h.

◆ INTEGER_PACK_LSBYTE_FIRST

#define INTEGER_PACK_LSBYTE_FIRST   0x20

Stores/interprets the least significant byte in a word as the first byte in the word.

Definition at line 540 of file bignum.h.

◆ INTEGER_PACK_LSWORD_FIRST

#define INTEGER_PACK_LSWORD_FIRST   0x02

Stores/interprets the least significant word as the first word.

Definition at line 528 of file bignum.h.

◆ INTEGER_PACK_MSBYTE_FIRST

#define INTEGER_PACK_MSBYTE_FIRST   0x10

Stores/interprets the most significant byte in a word as the first byte in the word.

Definition at line 534 of file bignum.h.

◆ INTEGER_PACK_MSWORD_FIRST

#define INTEGER_PACK_MSWORD_FIRST   0x01

Stores/interprets the most significant word as the first word.

Definition at line 525 of file bignum.h.

◆ INTEGER_PACK_NATIVE_BYTE_ORDER

#define INTEGER_PACK_NATIVE_BYTE_ORDER   0x40

Means either INTEGER_PACK_MSBYTE_FIRST or INTEGER_PACK_LSBYTE_FIRST, depending on the host processor's endian.

Definition at line 546 of file bignum.h.

◆ INTEGER_PACK_NEGATIVE

#define INTEGER_PACK_NEGATIVE   0x200

Interprets the input as a signed negative number (unpack only).

If not specified returns a positive number.

Definition at line 564 of file bignum.h.

◆ rb_big2int

#define rb_big2int (   x)    rb_big2long(x)

Just another name of rb_big2long.

Definition at line 219 of file bignum.h.

◆ rb_big2uint

#define rb_big2uint (   x)    rb_big2ulong(x)

Just another name of rb_big2long.

Definition at line 238 of file bignum.h.

Function Documentation

◆ rb_absint_numwords()

size_t rb_absint_numwords ( VALUE  val,
size_t  word_numbits,
size_t *  nlz_bits_ret 
)

Calculates the number of words needed represent the absolute value of the passed integer.

Unlike rb_absint_size() this function can overflow. It returns (size_t)-1 then.

Parameters
[in]valInteger or integer-like object which has #to_int method.
[in]word_numbitsNumber of bits per word.
[out]nlz_bits_retNumber of leading zero bits in the most significant word is returned if not NULL.
Exceptions
rb_eTypeErrorval doesn't respond to #to_int.
Return values
(size_t)-1Overflowed.
otherwise((val_numbits * CHAR_BIT + word_numbits - 1) / word_numbits), where val_numbits is the number of bits of abs(val).
Postcondition
If nlz_bits_ret is not NULL and there is no overflow, (return_value * word_numbits - val_numbits) is stored in *nlz_bits_ret. In this case, 0 <= *nlz_bits_ret < word_numbits.

Definition at line 3424 of file bignum.c.

Referenced by rb_big_pow(), and rb_str_format().

◆ rb_absint_singlebit_p()

int rb_absint_singlebit_p ( VALUE  val)

Tests abs(val) consists only of a bit or not.

Parameters
[in]valInteger or integer-like object which has #to_int method.
Exceptions
rb_eTypeErrorval doesn't respond to #to_int.
Return values
1abs(val) == 1 << n for some n >= 0.
0Otherwise.

rb_absint_singlebit_p() can be used to determine required buffer size for rb_integer_pack() used with INTEGER_PACK_2COMP (two's complement).

Following example calculates number of bits required to represent val in two's complement number, without sign bit.

size_t size;
int neg = FIXNUM_P(val) ? FIX2LONG(val) < 0 : BIGNUM_NEGATIVE_P(val);
size = rb_absint_numwords(val, 1, NULL)
if (size == (size_t)-1) ...overflow...
if (neg && rb_absint_singlebit_p(val))
size--;
#define FIX2LONG
Old name of RB_FIX2LONG.
Definition: long.h:46
#define FIXNUM_P
Old name of RB_FIXNUM_P.
size_t rb_absint_numwords(VALUE val, size_t word_numbits, size_t *nlz_bits_ret)
Calculates the number of words needed represent the absolute value of the passed integer.
Definition: bignum.c:3424
int rb_absint_singlebit_p(VALUE val)
Tests abs(val) consists only of a bit or not.
Definition: bignum.c:3487

Following example calculates number of bytes required to represent val in two's complement number, with sign bit.

size_t size;
int neg = FIXNUM_P(val) ? FIX2LONG(val) < 0 : BIGNUM_NEGATIVE_P(val);
int nlz_bits;
size = rb_absint_size(val, &nlz_bits);
if (nlz_bits == 0 && !(neg && rb_absint_singlebit_p(val)))
size++;
size_t rb_absint_size(VALUE val, int *nlz_bits_ret)
Calculates the number of bytes needed to represent the absolute value of the passed integer.
Definition: bignum.c:3289

Definition at line 3487 of file bignum.c.

Referenced by rb_str_format().

◆ rb_absint_size()

size_t rb_absint_size ( VALUE  val,
int *  nlz_bits_ret 
)

Calculates the number of bytes needed to represent the absolute value of the passed integer.

Parameters
[in]valInteger or integer-like object which has #to_int method.
[out]nlz_bits_retNumber of leading zero bits in the most significant byte is returned if not NULL.
Exceptions
rb_eTypeErrorval doesn't respond to #to_int.
Returns
((val_numbits * CHAR_BIT + CHAR_BIT - 1) / CHAR_BIT), where val_numbits is the number of bits of abs(val).
Postcondition
If nlz_bits_ret is not NULL, (return_value * CHAR_BIT - val_numbits) is stored in *nlz_bits_ret. In this case, 0 <= *nlz_bits_ret < CHAR_BIT.

This function should not overflow.

Definition at line 3289 of file bignum.c.

Referenced by rb_absint_numwords().

◆ rb_big2dbl()

double rb_big2dbl ( VALUE  x)

Converts a bignum into C's double.

Parameters
[in]xA bignum.
Returns
The passed value converted into C's double.

Definition at line 5346 of file bignum.c.

Referenced by rb_big_minus(), rb_big_mul(), rb_big_plus(), and rb_big_pow().

◆ rb_big2long()

long rb_big2long ( VALUE  x)

Converts a bignum into C's long.

Parameters
[in]xA bignum.
Exceptions
rb_eRangeErrorx is out of range of long.
Returns
The passed value converted into C's long.

Definition at line 5176 of file bignum.c.

Referenced by rb_num2long().

◆ rb_big2str()

VALUE rb_big2str ( VALUE  x,
int  base 
)

Generates a place-value representation of the passed integer.

Parameters
[in]xAn integer to stringify.
[in]base2 to 36 inclusive for each radix.
Exceptions
rb_eArgErrorbase is out of range.
rb_eRangeErrorx is too big, cannot represent in string.
Returns
An instance of rb_cString which represents x.

Definition at line 5127 of file bignum.c.

Referenced by rb_str_format().

◆ rb_big2ulong()

unsigned long rb_big2ulong ( VALUE  x)

Converts a bignum into C's unsigned long.

Parameters
[in]xA bignum.
Exceptions
rb_eRangeErrorx is out of range of unsigned long.
Returns
The passed value converted into C's unsigned long.

Definition at line 5161 of file bignum.c.

◆ rb_big_2comp()

void rb_big_2comp ( VALUE  num)

Destructively modify the passed bignum into 2's complement representation.

Note
By default bignums are in signed magnitude system.
Parameters
[out]numA bignum to modify.

Definition at line 3091 of file bignum.c.

◆ rb_big_and()

VALUE rb_big_and ( VALUE  x,
VALUE  y 
)

Performs bitwise and of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x & y evaluates to.
See also
rb_num_coerce_bit()

Definition at line 6395 of file bignum.c.

◆ rb_big_clone()

VALUE rb_big_clone ( VALUE  num)

Duplicates the given bignum.

Parameters
[in]numA bignum.
Returns
An allocated bignum, who is equivalent to num.

Definition at line 3062 of file bignum.c.

◆ rb_big_cmp()

VALUE rb_big_cmp ( VALUE  lhs,
VALUE  rhs 
)

Compares the passed two bignums.

Parameters
[in]lhsComparison LHS.
[in]rhsComparison RHS.
Return values
-1rhs is bigger than lhs.
0They are identical.
1lhs is bigger than rhs.
See also
rb_num_coerce_cmp()

Definition at line 5449 of file bignum.c.

◆ rb_big_div()

VALUE rb_big_div ( VALUE  x,
VALUE  y 
)

Performs division of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x / y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 6123 of file bignum.c.

◆ rb_big_divmod()

VALUE rb_big_divmod ( VALUE  x,
VALUE  y 
)

Performs "divmod" operation.

The operation in bignum's context is that it calculates rb_big_idiv() and rb_big_modulo() at once.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x.divmod y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 6167 of file bignum.c.

◆ rb_big_eq()

VALUE rb_big_eq ( VALUE  lhs,
VALUE  rhs 
)

Equality, in terms of ==.

This checks if the value is the same, not the identity. For instance 1 == 1.0 must hold.

Parameters
[in]lhsComparison LHS.
[in]rhsComparison RHS.
Return values
RUBY_QtrueThey are the same.
RUBY_QfalseThey are different.

Definition at line 5554 of file bignum.c.

◆ rb_big_eql()

VALUE rb_big_eql ( VALUE  lhs,
VALUE  rhs 
)

Equality, in terms of eql?.

Unlike rb_big_eq() it does not convert rb_cFloat etc. This function returns RUBY_Qtrue if and only if both parameters are bignums, which represent the identical numerical value.

Parameters
[in]lhsComparison LHS.
[in]rhsComparison RHS.
Return values
RUBY_QtrueThey are identical.
RUBY_QfalseThey are distinct.

Definition at line 5573 of file bignum.c.

◆ rb_big_idiv()

VALUE rb_big_idiv ( VALUE  x,
VALUE  y 
)

Performs "integer division".

This is different from rb_big_div().

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x.div y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 6129 of file bignum.c.

◆ rb_big_lshift()

VALUE rb_big_lshift ( VALUE  x,
VALUE  y 
)

Performs shift left.

Parameters
[in]xA bignum.
[in]yShift amount.
Exceptions
rb_eTypeErrory is not an integer.
rb_eArgErrory is too big.
Returns
x shifted left to y bits.
Note
y can be negative. Shifts right then.

Definition at line 6656 of file bignum.c.

◆ rb_big_minus()

VALUE rb_big_minus ( VALUE  x,
VALUE  y 
)

Performs subtraction of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x - y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 5881 of file bignum.c.

◆ rb_big_modulo()

VALUE rb_big_modulo ( VALUE  x,
VALUE  y 
)

Performs modulo of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x % y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 6135 of file bignum.c.

◆ rb_big_mul()

VALUE rb_big_mul ( VALUE  x,
VALUE  y 
)

Performs multiplication of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x * y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 5965 of file bignum.c.

◆ rb_big_new()

VALUE rb_big_new ( size_t  len,
int  sign 
)

Allocates a bignum object.

Parameters
[in]lenLength of the bignum's backend storage, in words.
[in]signSign of the bignum.
Returns
An allocated new bignum instance.
Note
This only allocates an object, doesn't fill its value in.

Definition at line 3056 of file bignum.c.

◆ rb_big_norm()

VALUE rb_big_norm ( VALUE  x)

Normalises the passed bignum.

It for instance returns a fixnum of the same value if fixnum can represent that number.

Parameters
[out]xTarget bignum (can be destructively modified).
Returns
An integer of the identical value (can be x itself).

Definition at line 3194 of file bignum.c.

◆ rb_big_or()

VALUE rb_big_or ( VALUE  x,
VALUE  y 
)

Performs bitwise or of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x | y evaluates to.
See also
rb_num_coerce_bit()

Definition at line 6514 of file bignum.c.

◆ rb_big_pack()

void rb_big_pack ( VALUE  val,
unsigned long *  buf,
long  num_longs 
)

Converts a bignum into a series of its parts.

Parameters
[in]valAn integer.
[out]bufReturn buffer.
[in]num_longsNumber of words of buf.
Exceptions
rb_eTypeErrorval doesn't respond to #to_int.
Postcondition
buf is filled with val's 2's complement representation, in the host CPU's native byte order, from least significant word towards the most significant one, for num_longs words.
Note
The "pack" terminology comes from Array#pack.

Definition at line 3257 of file bignum.c.

◆ rb_big_plus()

VALUE rb_big_plus ( VALUE  x,
VALUE  y 
)

Performs addition of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x + y evaluates to.
See also
rb_num_coerce_bin()

Definition at line 5852 of file bignum.c.

◆ rb_big_pow()

VALUE rb_big_pow ( VALUE  x,
VALUE  y 
)

Raises x to the powerof y.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x ** y evaluates to.
See also
rb_num_coerce_bin()
Note
This can return an instance of rb_cFloat, even when both x and y are bignums. Or an instance of rb_cRational, when for instance y is negative.

Definition at line 6276 of file bignum.c.

◆ rb_big_resize()

void rb_big_resize ( VALUE  big,
size_t  len 
)

Destructively resizes the backend storage of the passed bignum.

Parameters
[out]bigA bignum.
[in]lenNew length of big's backend, in words.

Definition at line 3029 of file bignum.c.

◆ rb_big_rshift()

VALUE rb_big_rshift ( VALUE  x,
VALUE  y 
)

Performs shift right.

Parameters
[in]xA bignum.
[in]yShift amount.
Exceptions
rb_eTypeErrory is not an integer.
Returns
x shifted right to y bits.
Note
This is arithmetic. Because bignums are not bitfields there is no shift right logical operator.

Definition at line 6686 of file bignum.c.

◆ rb_big_unpack()

VALUE rb_big_unpack ( unsigned long *  buf,
long  num_longs 
)

Constructs a (possibly very big) bignum from a series of integers.

buf[0] would be the return value's least significant word; buf[num_longs-1] would be that of most significant.

Parameters
[in]bufA series of integers.
[in]num_longsNumber of words of buf.
Exceptions
rb_eArgErrorResult would be too big.
Returns
An instance of rb_cInteger which is an "unpack"-ed value of the parameters.
Note
The "unpack" terminology comes from String#pack.

Definition at line 3265 of file bignum.c.

◆ rb_big_xor()

VALUE rb_big_xor ( VALUE  x,
VALUE  y 
)

Performs exclusive or of the passed two objects.

Parameters
[in]xA bignum.
[in]yArbitrary ruby object.
Returns
What x ^ y evaluates to.
See also
rb_num_coerce_bit()

Definition at line 6608 of file bignum.c.

◆ rb_bigzero_p()

int rb_bigzero_p ( VALUE  x)

Queries if the passed bignum instance is a "bigzero".

What is a bigzero? Well, bignums are for very big integers, but can also represent tiny ones like -1, 0, 1. Bigzero are instances of bignums whose values are zero. Knowing if a bignum is bigzero can be handy on occasions, like for instance detecting division by zero situation.

Parameters
[in]xA bignum.
Return values
1It is a bigzero.
0Otherwise.

Definition at line 2959 of file bignum.c.

◆ rb_cstr2inum()

VALUE rb_cstr2inum ( const char *  str,
int  base 
)

Identical to rb_cstr_to_inum(), except the second argument controls the base and badcheck at once.

It basically doesn't raise for parse errors, unless the base is zero.

This is an older API. New codes might prefer rb_cstr_to_inum().

Parameters
[in]strStringised representation of the return value.
[in]baseBase of conversion. Must be -36..36 inclusive, except 1. 2..36 means the conversion is done according to it, with unmatched prefix understood as a part of the result. -36..-2 means the conversion honours prefix when present, or use -base when absent. 0 is equivalent to -10. -1 mandates a prefix. 1 is an error.
Exceptions
rb_eArgErrorFailed to parse (and base is zero).
Returns
An instance of rb_cInteger, which is a numeric interpretation of what is written in str.

Definition at line 4578 of file bignum.c.

◆ rb_cstr_to_inum()

VALUE rb_cstr_to_inum ( const char *  str,
int  base,
int  badcheck 
)

Parses C's string to convert into a Ruby's integer.

It understands prefixes (e.g. 0x) and underscores.

Parameters
[in]strStringised representation of the return value.
[in]baseBase of conversion. Must be -36..36 inclusive, except 1. 2..36 means the conversion is done according to it, with unmatched prefix understood as a part of the result. -36..-2 means the conversion honours prefix when present, or use -base when absent. 0 is equivalent to -10. -1 mandates a prefix. 1 is an error.
[in]badcheckWhether to raise rb_eArgError on failure. If 0 is passed here this function can return INT2FIX(0) for parse errors.
Exceptions
rb_eArgErrorFailed to parse (and badcheck is truthy).
Returns
An instance of rb_cInteger, which is a numeric interpretation of what is written in str.

Definition at line 4051 of file bignum.c.

Referenced by rb_cstr2inum().

◆ rb_dbl2big()

VALUE rb_dbl2big ( double  d)

Converts a C's double into a bignum.

Parameters
[in]dA value to convert.
Exceptions
rb_eFloatDomainErrord is Inf/NaN.
Returns
An instance of rb_cInteger whose value is approximately d.

Definition at line 5285 of file bignum.c.

Referenced by rb_str_format().

◆ rb_integer_pack()

int rb_integer_pack ( VALUE  val,
void *  words,
size_t  numwords,
size_t  wordsize,
size_t  nails,
int  flags 
)

Exports an integer into a buffer.

This function fills the buffer specified by words and numwords as val in the format specified by wordsize, nails and flags.

Parameters
[in]valInteger or integer-like object which has #to_int method.
[out]wordsReturn buffer.
[in]numwordsNumber of words of words.
[in]wordsizeNumber of bytes per word.
[in]nailsNumber of padding bits in a word. Most significant nails bits of each word are filled by zero.
[in]flagsBitwise or of constants whose name starts "INTEGER_PACK_".
Exceptions
rb_eTypeErrorval doesn't respond to #to_int.

Possible flags are:

This function fills the buffer specified by words as val's 2's complement representation if INTEGER_PACK_2COMP is specified in flags. Otherwise it fills words as abs(val) and signedness is returned via the return value.

Returns
The signedness and overflow condition. The overflow condition depends on INTEGER_PACK_2COMP.

When INTEGER_PACK_2COMP is not specified:

  • -2 : Negative overflow. val <= -2**(numwords*(wordsize*CHAR_BIT-nails))
  • -1 : Negative without overflow. -2**(numwords*(wordsize*CHAR_BIT-nails)) < val < 0
  • 0 : zero. val == 0
  • 1 : Positive without overflow. 0 < val < 2**(numwords*(wordsize*CHAR_BIT-nails))
  • 2 : Positive overflow. 2**(numwords*(wordsize*CHAR_BIT-nails)) <= val

When INTEGER_PACK_2COMP is specified:

  • -2 : Negative overflow. val < -2**(numwords*(wordsize*CHAR_BIT-nails))
  • -1 : Negative without overflow. -2**(numwords*(wordsize*CHAR_BIT-nails)) <= val < 0
  • 0 : zero. val == 0
  • 1 : Positive without overflow. 0 < val < 2**(numwords*(wordsize*CHAR_BIT-nails))
  • 2 : Positive overflow. 2**(numwords*(wordsize*CHAR_BIT-nails)) <= val

The value, -2**(numwords*(wordsize*CHAR_BIT-nails)), is representable in 2's complement representation but not representable in absolute value. So -1 is returned for the value if INTEGER_PACK_2COMP is specified but returns -2 if INTEGER_PACK_2COMP is not specified.

The least significant words are filled in the buffer when overflow occur.

Definition at line 3588 of file bignum.c.

Referenced by rb_big_pack(), and rb_str_format().

◆ rb_integer_unpack()

VALUE rb_integer_unpack ( const void *  words,
size_t  numwords,
size_t  wordsize,
size_t  nails,
int  flags 
)

Import an integer from a buffer.

Parameters
[in]wordsBuffer to import.
[in]numwordsNumber of words of words.
[in]wordsizeNumber of bytes per word.
[in]nailsNumber of padding bits in a word. Most significant nails bits of each word are ignored.
[in]flagsBitwise or of constants whose name starts "INTEGER_PACK_".
Exceptions
rb_eArgErrornumwords * wordsize too big.

Possible flags are:

Returns
An instance of rb_cInteger whose value is the interpreted words. The range of the result value depends on INTEGER_PACK_2COMP and INTEGER_PACK_NEGATIVE.

When INTEGER_PACK_2COMP is not set:

  • 0 <= val < 2**(numwords*(wordsize*CHAR_BIT-nails)) if !INTEGER_PACK_NEGATIVE
  • -2**(numwords*(wordsize*CHAR_BIT-nails)) < val <= 0 if INTEGER_PACK_NEGATIVE

When INTEGER_PACK_2COMP is set:

  • -2**(numwords*(wordsize*CHAR_BIT-nails)-1) <= val <= 2**(numwords*(wordsize*CHAR_BIT-nails)-1)-1 if !INTEGER_PACK_NEGATIVE
  • -2**(numwords*(wordsize*CHAR_BIT-nails)) <= val <= -1 if INTEGER_PACK_NEGATIVE

Passing INTEGER_PACK_2COMP without INTEGER_PACK_NEGATIVE means sign extension. INTEGER_PACK_2COMP with INTEGER_PACK_NEGATIVE means assuming the higher bits are 1.

Note that this function returns 0 when numwords is zero and INTEGER_PACK_2COMP is set but INTEGER_PACK_NEGATIVE is not set.

Definition at line 3674 of file bignum.c.

Referenced by rb_big_unpack().

◆ rb_str2inum()

VALUE rb_str2inum ( VALUE  str,
int  base 
)

Identical to rb_str_to_inum(), except the second argument controls the base and badcheck at once.

It can also be seen as a routine identical to rb_cstr2inum(), except it takes Ruby's strings instead of C's.

This is an older API. New codes might prefer rb_cstr_to_inum().

Parameters
[in]strStringised representation of the return value.
[in]baseBase of conversion. Must be -36..36 inclusive, except 1. 2..36 means the conversion is done according to it, with unmatched prefix understood as a part of the result. -36..-2 means the conversion honours prefix when present, or use -base when absent. 0 is equivalent to -10. -1 mandates a prefix. 1 is an error.
Exceptions
rb_eArgErrorFailed to parse (and base is zero).
rb_eTypeErrorstr is not a string.
rb_eEncCompatErrorstr is not ASCII compatible.
Returns
An instance of rb_cInteger, which is a numeric interpretation of what is written in str.

Definition at line 4584 of file bignum.c.

◆ rb_str_to_inum()

VALUE rb_str_to_inum ( VALUE  str,
int  base,
int  badcheck 
)

Identical to rb_cstr2inum(), except it takes Ruby's strings instead of C's.

Parameters
[in]strStringised representation of the return value.
[in]baseBase of conversion. Must be -36..36 inclusive, except 1. 2..36 means the conversion is done according to it, with unmatched prefix understood as a part of the result. -36..-2 means the conversion honours prefix when present, or use -base when absent. 0 is equivalent to -10. -1 mandates a prefix. 1 is an error.
[in]badcheckWhether to raise rb_eArgError on failure. If 0 is passed here this function can return INT2FIX(0) for parse errors.
Exceptions
rb_eArgErrorFailed to parse (and badcheck is truthy).
rb_eTypeErrorstr is not a string.
rb_eEncCompatErrorstr is not ASCII compatible.
Returns
An instance of rb_cInteger, which is a numeric interpretation of what is written in str.

Definition at line 4308 of file bignum.c.

Referenced by rb_str2inum(), and rb_str_format().

◆ rb_uv_to_utf8()

int rb_uv_to_utf8 ( char  buf[6],
unsigned long  uv 
)

Encodes a Unicode codepoint into its UTF-8 representation.

Parameters
[out]bufReturn buffer, must at least be 6 bytes width.
[in]uvAn Unicode codepoint.
Exceptions
rb_eRangeErroruv is out of Unicode.
Returns
Number of bytes written to buf
Postcondition
buf holds a UTF-8 representation of uv.

Definition at line 1601 of file pack.c.