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

Ruby 3.4.7p58 (2025-10-08 revision 7a5688e2a27668e48f8d6ff4af5b2208b98a2f5e)

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 "bigzero".
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)

Just another name of rb_big2long.

Definition at line 219 of file bignum.h.

## ◆ rb_big2uint

#define rb_big2uint | ( |  | x | ) |

Value:
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] | 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 3424 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
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.
Definition bignum.c:3424
rb_absint_singlebit_p
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++;
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.
Definition bignum.c:3289

Definition at line 3487 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 3289 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 5346 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 5176 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 5127 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 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] | num | A 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] | x | A bignum.
  [in] | y | Arbitrary 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] | num | A 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] | 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 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] | x | A bignum.
  [in] | y | Arbitrary 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] | x | A bignum.
  [in] | y | Arbitrary 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] | lhs | Comparison LHS.
  [in] | rhs | Comparison RHS.

Return values

  RUBY_Qtrue | They are the same.
  RUBY_Qfalse | They 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] | lhs | Comparison LHS.
  [in] | rhs | Comparison RHS.

Return values

  RUBY_Qtrue | They are identical.
  RUBY_Qfalse | They 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] | x | A bignum.
  [in] | y | Arbitrary 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] | 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 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] | x | A bignum.
  [in] | y | Arbitrary 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] | x | A bignum.
  [in] | y | Arbitrary 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] | x | A bignum.
  [in] | y | Arbitrary 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] | 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 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] | x | Target 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] | x | A bignum.
  [in] | y | Arbitrary 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] | 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 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] | x | A bignum.
  [in] | y | Arbitrary 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] | 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 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] | big | A bignum.
  [in] | len | New 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] | 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 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] | 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 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] | x | A bignum.
  [in] | y | Arbitrary 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] | x | A bignum.

Return values

  1 | It is a bigzero.
  0 | Otherwise.

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] | 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 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] | 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 4051 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 5285 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 3588 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 3674 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 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] | 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 4308 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 1601 of file pack.c.

Referenced by rb_uv_to_utf8().