Ruby: include/ruby/internal/intern/bignum.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Macros | Functions
bignum.h File Reference

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"`

Go to the source code of this file.

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

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

## 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

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.

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.

Referenced by rb_big_pack(), rb_big_unpack(), rb_integer_unpack(), and rb_str_format().

## ◆ INTEGER_PACK_BIG_ENDIAN

#define INTEGER_PACK_BIG_ENDIAN

Value:
(INTEGER_PACK_MSWORD_FIRST | \
INTEGER_PACK_MSBYTE_FIRST)
INTEGER_PACK_MSBYTE_FIRST
#define INTEGER_PACK_MSBYTE_FIRST
Stores/interprets the most significant byte in a word as the first byte in the word.
Definition bignum.h:534
INTEGER_PACK_MSWORD_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.

Referenced by rb_str_format().

## ◆ 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.

Referenced by rb_integer_unpack().

## ◆ 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.

Referenced by rb_integer_unpack().

## ◆ INTEGER_PACK_LITTLE_ENDIAN

#define INTEGER_PACK_LITTLE_ENDIAN

Value:
(INTEGER_PACK_LSWORD_FIRST | \
INTEGER_PACK_LSBYTE_FIRST)
INTEGER_PACK_LSBYTE_FIRST
#define INTEGER_PACK_LSBYTE_FIRST
Stores/interprets the least significant byte in a word as the first byte in the word.
Definition bignum.h:540
INTEGER_PACK_LSWORD_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.

Referenced by rb_integer_unpack().

## ◆ 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.

Referenced by rb_big_pack(), rb_big_unpack(), and rb_integer_unpack().

## ◆ 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.

Referenced by rb_integer_unpack().

## ◆ 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.

Referenced by rb_integer_unpack().

## ◆ 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.

Referenced by rb_big_pack(), rb_big_unpack(), and rb_integer_unpack().

## ◆ 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.

Referenced by rb_integer_unpack().

## ◆ rb_big2int

#define rb_big2int | ( |  | x | ) |

Value:
rb_big2long(x)
rb_big2long
long rb_big2long(VALUE x)
Converts a bignum into C's long.
Definition bignum.c:5165

Just another name of rb_big2long.

Definition at line 219 of file bignum.h.

## ◆ rb_big2uint

#define rb_big2uint | ( |  | x | ) |

Value:
rb_big2ulong(x)
rb_big2ulong
unsigned long rb_big2ulong(VALUE x)
Converts a bignum into C's unsigned long.
Definition bignum.c:5150

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] | val | Integer or integer-like object which has `#to_int` method.
  [in] | word_numbits | Number of bits per word.
  [out] | nlz_bits_ret | Number of leading zero bits in the most significant word is returned if not `NULL`.

Exceptions

  rb_eTypeError | `val` doesn't respond to `#to_int`.

Return values

  (size_t)-1 | Overflowed.
  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 3411 of file bignum.c.

## ◆ rb_absint_singlebit_p()

int rb_absint_singlebit_p | ( | VALUE | val | ) |

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

Parameters

  [in] | val | Integer or integer-like object which has `#to_int` method.

Exceptions

  rb_eTypeError | `val` doesn't respond to `#to_int`.

Return values

  1 | `abs(val) == 1 << n` for some `n >= 0`.
  0 | Otherwise.

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--;
FIX2LONG
#define FIX2LONG
Old name of RB_FIX2LONG.
Definition long.h:46
FIXNUM_P
#define FIXNUM_P
Old name of RB_FIXNUM_P.
Definition special_consts.h:53

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++;

Definition at line 3476 of file bignum.c.

## ◆ 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] | val | Integer or integer-like object which has `#to_int` method.
  [out] | nlz_bits_ret | Number of leading zero bits in the most significant byte is returned if not `NULL`.

Exceptions

  rb_eTypeError | `val` 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 3276 of file bignum.c.

## ◆ rb_big2dbl()

double rb_big2dbl | ( | VALUE | x | ) |

Converts a bignum into C's `double`.

Parameters

  [in] | x | A bignum.

Returns
  The passed value converted into C's `double`.

Definition at line 5335 of file bignum.c.

## ◆ rb_big2long()

long rb_big2long | ( | VALUE | x | ) |

Converts a bignum into C's `long`.

Parameters

  [in] | x | A bignum.

Exceptions

  rb_eRangeError | `x` is out of range of `long`.

Returns
  The passed value converted into C's `long`.

Definition at line 5165 of file bignum.c.

## ◆ rb_big2str()

VALUE rb_big2str | ( | VALUE | x,
|  | int | base )

Generates a place-value representation of the passed integer.

Parameters

  [in] | x | An integer to stringify.
  [in] | base | `2` to `36` inclusive for each radix.

Exceptions

  rb_eArgError | `base` is out of range.
  rb_eRangeError | `x` is too big, cannot represent in string.

Returns
  An instance of rb_cString which represents `x`.

Definition at line 5116 of file bignum.c.

## ◆ rb_big2ulong()

unsigned long rb_big2ulong | ( | VALUE | x | ) |

Converts a bignum into C's `unsigned long`.

Parameters

  [in] | x | A bignum.

Exceptions

  rb_eRangeError | `x` is out of range of `unsigned long`.

Returns
  The passed value converted into C's `unsigned long`.

Definition at line 5150 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] | num | A bignum to modify.

Definition at line 3078 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] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x & y` evaluates to.

See also
  rb_num_coerce_bit()

Definition at line 6377 of file bignum.c.

## ◆ rb_big_clone()

VALUE rb_big_clone | ( | VALUE | num | ) |

Duplicates the given bignum.

Parameters

  [in] | num | A bignum.

Returns
  An allocated bignum, who is equivalent to `num`.

Definition at line 3049 of file bignum.c.

## ◆ rb_big_cmp()

VALUE rb_big_cmp | ( | VALUE | lhs,
|  | VALUE | rhs )

Compares the passed two bignums.

Parameters

  [in] | lhs | Comparison LHS.
  [in] | rhs | Comparison RHS.

Return values

  -1 | `rhs` is bigger than `lhs`.
  0 | They are identical.
  1 | `lhs` is bigger than `rhs`.

See also
  rb_num_coerce_cmp()

Definition at line 5438 of file bignum.c.

## ◆ rb_big_div()

VALUE rb_big_div | ( | VALUE | x,
|  | VALUE | y )

Performs division of the passed two objects.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x / y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 6108 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] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x.divmod y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 6152 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] | lhs | Comparison LHS.
  [in] | rhs | Comparison RHS.

Return values

  RUBY_Qtrue | They are the same.
  RUBY_Qfalse | They are different.

Definition at line 5543 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] | lhs | Comparison LHS.
  [in] | rhs | Comparison RHS.

Return values

  RUBY_Qtrue | They are identical.
  RUBY_Qfalse | They are distinct.

Definition at line 5562 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] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x.div y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 6114 of file bignum.c.

## ◆ rb_big_lshift()

VALUE rb_big_lshift | ( | VALUE | x,
|  | VALUE | y )

Performs shift left.

Parameters

  [in] | x | A bignum.
  [in] | y | Shift amount.

Exceptions

  rb_eTypeError | `y` is not an integer.
  rb_eArgError | `y` is too big.

Returns
  `x` shifted left to `y` bits.

Note
  `y` can be negative. Shifts right then.

Definition at line 6638 of file bignum.c.

## ◆ rb_big_minus()

VALUE rb_big_minus | ( | VALUE | x,
|  | VALUE | y )

Performs subtraction of the passed two objects.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x - y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 5870 of file bignum.c.

## ◆ rb_big_modulo()

VALUE rb_big_modulo | ( | VALUE | x,
|  | VALUE | y )

Performs modulo of the passed two objects.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x % y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 6120 of file bignum.c.

## ◆ rb_big_mul()

VALUE rb_big_mul | ( | VALUE | x,
|  | VALUE | y )

Performs multiplication of the passed two objects.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x * y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 5950 of file bignum.c.

## ◆ rb_big_new()

VALUE rb_big_new | ( | size_t | len,
|  | int | sign )

Allocates a bignum object.

Parameters

  [in] | len | Length of the bignum's backend storage, in words.
  [in] | sign | Sign of the bignum.

Returns
  An allocated new bignum instance.

Note
  This only allocates an object, doesn't fill its value in.

Definition at line 3043 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] | x | Target bignum (can be destructively modified).

Returns
  An integer of the identical value (can be `x` itself).

Definition at line 3181 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] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x | y` evaluates to.

See also
  rb_num_coerce_bit()

Definition at line 6496 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] | val | An integer.
  [out] | buf | Return buffer.
  [in] | num_longs | Number of words of `buf`.

Exceptions

  rb_eTypeError | `val` 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 3244 of file bignum.c.

## ◆ rb_big_plus()

VALUE rb_big_plus | ( | VALUE | x,
|  | VALUE | y )

Performs addition of the passed two objects.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x + y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 5841 of file bignum.c.

## ◆ rb_big_pow()

VALUE rb_big_pow | ( | VALUE | x,
|  | VALUE | y )

Raises `x` to the powerof `y`.

Parameters

  [in] | x | A bignum.
  [in] | y | Arbitrary 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 6261 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] | big | A bignum.
  [in] | len | New length of `big`'s backend, in words.

Definition at line 3017 of file bignum.c.

## ◆ rb_big_rshift()

VALUE rb_big_rshift | ( | VALUE | x,
|  | VALUE | y )

Performs shift right.

Parameters

  [in] | x | A bignum.
  [in] | y | Shift amount.

Exceptions

  rb_eTypeError | `y` 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 6668 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] | buf | A series of integers.
  [in] | num_longs | Number of words of `buf`.

Exceptions

  rb_eArgError | Result 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 3252 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] | x | A bignum.
  [in] | y | Arbitrary ruby object.

Returns
  What `x ^ y` evaluates to.

See also
  rb_num_coerce_bit()

Definition at line 6590 of file bignum.c.

## ◆ rb_bigzero_p()

int rb_bigzero_p | ( | VALUE | x | ) |

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

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] | x | A bignum.

Return values

  1 | It is a bigzero.
  0 | Otherwise.

Definition at line 2947 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] | str | Stringised representation of the return value.
  [in] | base | Base 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_eArgError | Failed 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 4567 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] | str | Stringised representation of the return value.
  [in] | base | Base 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] | badcheck | Whether to raise rb_eArgError on failure. If `0` is passed here this function can return `INT2FIX(0)` for parse errors.

Exceptions

  rb_eArgError | Failed 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 4040 of file bignum.c.

## ◆ rb_dbl2big()

VALUE rb_dbl2big | ( | double | d | ) |

Converts a C's `double` into a bignum.

Parameters

  [in] | d | A value to convert.

Exceptions

  rb_eFloatDomainError | `d` is Inf/NaN.

Returns
  An instance of rb_cInteger whose value is approximately `d`.

Definition at line 5274 of file bignum.c.

## ◆ 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] | val | Integer or integer-like object which has `#to_int` method.
  [out] | words | Return buffer.
  [in] | numwords | Number of words of `words`.
  [in] | wordsize | Number of bytes per word.
  [in] | nails | Number of padding bits in a word. Most significant nails bits of each word are filled by zero.
  [in] | flags | Bitwise or of constants whose name starts "INTEGER_PACK_".

Exceptions

  rb_eTypeError | `val` doesn't respond to `#to_int`.

Possible flags are:

- INTEGER_PACK_MSWORD_FIRST: Stores the most significant word as the first word.
- INTEGER_PACK_LSWORD_FIRST: Stores the least significant word as the first word.
- INTEGER_PACK_MSBYTE_FIRST: Stores the most significant byte in a word as the first byte in the word.
- INTEGER_PACK_LSBYTE_FIRST: Stores the least significant byte in a word as the first byte in the word.
- INTEGER_PACK_NATIVE_BYTE_ORDER: Either INTEGER_PACK_MSBYTE_FIRST or INTEGER_PACK_LSBYTE_FIRST corresponding to the host's endian.
- INTEGER_PACK_2COMP: Uses 2's complement representation.
- INTEGER_PACK_LITTLE_ENDIAN: Shorthand of `INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_LSBYTE_FIRST`.
- INTEGER_PACK_BIG_ENDIAN: Shorthand of `INTEGER_PACK_MSWORD_FIRST|INTEGER_PACK_MSBYTE_FIRST`.
- INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION: Uses generic implementation (for test and debug).

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 3577 of file bignum.c.

## ◆ 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] | words | Buffer to import.
  [in] | numwords | Number of words of `words`.
  [in] | wordsize | Number of bytes per word.
  [in] | nails | Number of padding bits in a word. Most significant nails bits of each word are ignored.
  [in] | flags | Bitwise or of constants whose name starts "INTEGER_PACK_".

Exceptions

  rb_eArgError | `numwords * wordsize` too big.

Possible flags are:

- INTEGER_PACK_MSWORD_FIRST: Interpret the first word as the most significant word.
- INTEGER_PACK_LSWORD_FIRST: Interpret the first word as the least significant word.
- INTEGER_PACK_MSBYTE_FIRST: Interpret the first byte in a word as the most significant byte in the word.
- INTEGER_PACK_LSBYTE_FIRST: Interpret the first byte in a word as the least significant byte in the word.
- INTEGER_PACK_NATIVE_BYTE_ORDER: Either INTEGER_PACK_MSBYTE_FIRST or INTEGER_PACK_LSBYTE_FIRST corresponding to the host's endian.
- INTEGER_PACK_2COMP: Uses 2's complement representation.
- INTEGER_PACK_LITTLE_ENDIAN: Shorthand of `INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_LSBYTE_FIRST`
- INTEGER_PACK_BIG_ENDIAN: Shorthand of `INTEGER_PACK_MSWORD_FIRST|INTEGER_PACK_MSBYTE_FIRST`
- INTEGER_PACK_FORCE_BIGNUM: Returns a bignum even if its value is representable as a fixnum.
- INTEGER_PACK_NEGATIVE: Returns a non-positive value. (Returns a non-negative value if not specified.)
- INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION: Uses generic implementation (for test and debug).

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 3663 of file bignum.c.

## ◆ 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] | str | Stringised representation of the return value.
  [in] | base | Base 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_eArgError | Failed to parse (and `base` is zero).
  rb_eTypeError | `str` is not a string.
  rb_eEncCompatError | `str` is not ASCII compatible.

Returns
  An instance of rb_cInteger, which is a numeric interpretation of what is written in `str`.

Definition at line 4573 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] | str | Stringised representation of the return value.
  [in] | base | Base 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] | badcheck | Whether to raise rb_eArgError on failure. If `0` is passed here this function can return `INT2FIX(0)` for parse errors.

Exceptions

  rb_eArgError | Failed to parse (and `badcheck` is truthy).
  rb_eTypeError | `str` is not a string.
  rb_eEncCompatError | `str` is not ASCII compatible.

Returns
  An instance of rb_cInteger, which is a numeric interpretation of what is written in `str`.

Definition at line 4297 of file bignum.c.

## ◆ 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] | buf | Return buffer, must at least be 6 bytes width.
  [in] | uv | An Unicode codepoint.

Exceptions

  rb_eRangeError | `uv` is out of Unicode.

Returns
  Number of bytes written to `buf`

Postcondition
  `buf` holds a UTF-8 representation of `uv`.

Definition at line 1625 of file pack.c.

Referenced by rb_uv_to_utf8().