(37a72b0150ec36b4ea27175039afc28c62207b0c)

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

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.

◆ INTEGER_PACK_BIG_ENDIAN

#define INTEGER_PACK_BIG_ENDIAN

Value:

(INTEGER_PACK_MSWORD_FIRST | \

INTEGER_PACK_MSBYTE_FIRST)

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.

◆ 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_LSWORD_FIRST | \

INTEGER_PACK_LSBYTE_FIRST)

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.

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

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

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 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]	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.

Referenced by rb_absint_numwords().

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

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] 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.

Referenced by rb_num2long().

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

Referenced by rb_str_format().

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

Referenced by rb_cstr2inum().

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

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]	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.

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]	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.

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]	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.

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]	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.

(37a72b0150ec36b4ea27175039afc28c62207b0c)

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ INTEGER_PACK_2COMP

◆ INTEGER_PACK_BIG_ENDIAN

◆ INTEGER_PACK_FORCE_BIGNUM

◆ INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION

◆ INTEGER_PACK_LITTLE_ENDIAN

◆ INTEGER_PACK_LSBYTE_FIRST

◆ INTEGER_PACK_LSWORD_FIRST

◆ INTEGER_PACK_MSBYTE_FIRST

◆ INTEGER_PACK_MSWORD_FIRST

◆ INTEGER_PACK_NATIVE_BYTE_ORDER

◆ INTEGER_PACK_NEGATIVE

◆ rb_big2int

◆ rb_big2uint

Function Documentation

◆ rb_absint_numwords()

◆ rb_absint_singlebit_p()

◆ rb_absint_size()

◆ rb_big2dbl()

◆ rb_big2long()

◆ rb_big2str()

◆ rb_big2ulong()

◆ rb_big_2comp()

◆ rb_big_and()

◆ rb_big_clone()

◆ rb_big_cmp()

◆ rb_big_div()

◆ rb_big_divmod()

◆ rb_big_eq()

◆ rb_big_eql()

◆ rb_big_idiv()

◆ rb_big_lshift()

◆ rb_big_minus()

◆ rb_big_modulo()

◆ rb_big_mul()

◆ rb_big_new()

◆ rb_big_norm()

◆ rb_big_or()

◆ rb_big_pack()

◆ rb_big_plus()

◆ rb_big_pow()

◆ rb_big_resize()

◆ rb_big_rshift()

◆ rb_big_unpack()

◆ rb_big_xor()

◆ rb_bigzero_p()

◆ rb_cstr2inum()

◆ rb_cstr_to_inum()

◆ rb_dbl2big()

◆ rb_integer_pack()

◆ rb_integer_unpack()

◆ rb_str2inum()

◆ rb_str_to_inum()

◆ rb_uv_to_utf8()