Ruby: include/ruby/internal/arithmetic/long.h File Reference

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

Macros | Functions
long.h File Reference

Arithmetic conversion between C's `long` and Ruby's. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/arithmetic/fixnum.h"`
`#include "ruby/internal/arithmetic/intptr_t.h"`
`#include "ruby/internal/assume.h"`
`#include "ruby/internal/attr/artificial.h"`
`#include "ruby/internal/attr/cold.h"`
`#include "ruby/internal/attr/const.h"`
`#include "ruby/internal/attr/constexpr.h"`
`#include "ruby/internal/attr/noreturn.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/special_consts.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/assert.h"`

Go to the source code of this file.

## Macros
#define | FIX2LONG RB_FIX2LONG
| Old name of RB_FIX2LONG.
#define | FIX2ULONG RB_FIX2ULONG
| Old name of RB_FIX2ULONG.
#define | INT2FIX RB_INT2FIX
| Old name of RB_INT2FIX.
#define | LONG2FIX RB_INT2FIX
| Old name of RB_INT2FIX.
#define | LONG2NUM RB_LONG2NUM
| Old name of RB_LONG2NUM.
#define | NUM2LONG RB_NUM2LONG
| Old name of RB_NUM2LONG.
#define | NUM2ULONG RB_NUM2ULONG
| Old name of RB_NUM2ULONG.
#define | RB_FIX2LONG rb_fix2long
| Just another name of rb_fix2long.
#define | RB_FIX2ULONG rb_fix2ulong
| Just another name of rb_fix2ulong.
#define | RB_LONG2FIX RB_INT2FIX
| Just another name of RB_INT2FIX.
#define | RB_LONG2NUM rb_long2num_inline
| Just another name of rb_long2num_inline.
#define | RB_NUM2LONG rb_num2long_inline
| Just another name of rb_num2long_inline.
#define | RB_NUM2ULONG rb_num2ulong_inline
| Just another name of rb_num2ulong_inline.
#define | RB_ULONG2NUM rb_ulong2num_inline
| Just another name of rb_ulong2num_inline.
#define | ULONG2NUM RB_ULONG2NUM
| Old name of RB_ULONG2NUM.
#define | rb_fix_new RB_INT2FIX
| Just another name of RB_INT2FIX.
#define | rb_long2int rb_long2int_inline
| Just another name of rb_long2int_inline.

## Functions
void | rb_out_of_int (SIGNED_VALUE num)
| This is an utility function to raise an rb_eRangeError.
long | rb_num2long (VALUE num)
| Converts an instance of rb_cNumeric into C's `long`.
unsigned long | rb_num2ulong (VALUE num)
| Converts an instance of rb_cNumeric into C's `unsigned long`.
static VALUE | RB_INT2FIX (long i)
| Converts a C's `long` into an instance of rb_cInteger.
static int | rb_long2int_inline (long n)
| Checks if `int` can hold the given integer.
static long | rb_fix2long (VALUE x)
| Converts a Fixnum into C's `long`.
static unsigned long | rb_fix2ulong (VALUE x)
| Converts a Fixnum into C's `unsigned long`.
static long | rb_num2long_inline (VALUE x)
| Converts an instance of rb_cNumeric into C's `long`.
static unsigned long | rb_num2ulong_inline (VALUE x)
| Converts an instance of rb_cNumeric into C's `unsigned long`.
static VALUE | rb_long2num_inline (long v)
| Converts a C's `long` into an instance of rb_cInteger.
static VALUE | rb_ulong2num_inline (unsigned long v)
| Converts a C's `unsigned long` into an instance of rb_cInteger.

## Detailed Description

Arithmetic conversion between C's `long` and Ruby's.

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.

### Q&A

- Q: Why are INT2FIX etc. here, not in `int.h`?
- A: Because they are in fact handling `long`. It seems someone did not understand the difference of `int` and `long` when they designed those macros.

Definition in file long.h.

## Macro Definition Documentation

## ◆ RB_FIX2LONG

#define RB_FIX2LONG rb_fix2long

Just another name of rb_fix2long.

Definition at line 53 of file long.h.

Referenced by RB_FIX2INT(), rb_num2ll_inline(), rb_num2long_inline(), and rb_num2ull_inline().

## ◆ RB_FIX2ULONG

#define RB_FIX2ULONG rb_fix2ulong

Just another name of rb_fix2ulong.

Definition at line 54 of file long.h.

Referenced by RB_FIX2UINT(), rb_fix2uint(), and rb_num2ulong_inline().

## ◆ rb_fix_new

#define rb_fix_new RB_INT2FIX

Just another name of RB_INT2FIX.

Definition at line 61 of file long.h.

## ◆ RB_LONG2FIX

#define RB_LONG2FIX RB_INT2FIX

Just another name of RB_INT2FIX.

Definition at line 55 of file long.h.

Referenced by rb_long2num_inline(), RB_ST2FIX(), rb_uint2num_inline(), and rb_ulong2num_inline().

## ◆ rb_long2int

#define rb_long2int rb_long2int_inline

Just another name of rb_long2int_inline.

Definition at line 62 of file long.h.

Referenced by RARRAY_LENINT(), rb_profile_frame_full_label(), rb_str_format(), rb_struct_new(), and RSTRING_LENINT().

## ◆ RB_LONG2NUM

#define RB_LONG2NUM rb_long2num_inline

Just another name of rb_long2num_inline.

Definition at line 56 of file long.h.

## ◆ RB_NUM2LONG

#define RB_NUM2LONG rb_num2long_inline

Just another name of rb_num2long_inline.

Definition at line 57 of file long.h.

Referenced by rb_num2int_inline(), and RSTRUCT_LEN().

## ◆ RB_NUM2ULONG

#define RB_NUM2ULONG rb_num2ulong_inline

Just another name of rb_num2ulong_inline.

Definition at line 58 of file long.h.

Referenced by RB_NUM2UINT().

## ◆ RB_ULONG2NUM

#define RB_ULONG2NUM rb_ulong2num_inline

Just another name of rb_ulong2num_inline.

Definition at line 59 of file long.h.

## Function Documentation

## ◆ rb_fix2long()

static long rb_fix2long | ( | VALUE | x | ) |
| inlinestatic

Converts a Fixnum into C's `long`.

Parameters

  [in] | x | Some Fixnum.

Precondition
  Must not pass anything other than a Fixnum.

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

Definition at line 231 of file long.h.

Referenced by rb_fix2ulong().

## ◆ rb_fix2ulong()

static unsigned long rb_fix2ulong | ( | VALUE | x | ) |
| inlinestatic

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

Parameters

  [in] | x | Some Fixnum.

Precondition
  Must not pass anything other than a Fixnum.

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

Note
  Negative fixnums will be converted into large unsigned longs.

Definition at line 252 of file long.h.

## ◆ RB_INT2FIX()

static VALUE RB_INT2FIX | ( | long | i | ) |
| inlinestatic

Converts a C's `long` into an instance of rb_cInteger.

Parameters

  [in] | i | Arbitrary `long` value.

Returns
  An instance of rb_cInteger.

Definition at line 111 of file long.h.

Referenced by RB_CHR2FIX(), and rb_int2num_inline().

## ◆ rb_long2int_inline()

static int rb_long2int_inline | ( | long | n | ) |
| inlinestatic

Checks if `int` can hold the given integer.

Parameters

  [in] | n | Arbitrary `long` value.

Exceptions

  rb_eRangeError | `n` is out of range of `int`.

Returns
  Identical value of type `int`

Definition at line 135 of file long.h.

## ◆ rb_long2num_inline()

static VALUE rb_long2num_inline | ( | long | v | ) |
| inlinestatic

Converts a C's `long` into an instance of rb_cInteger.

Parameters

  [in] | v | Arbitrary `long` value.

Returns
  An instance of rb_cInteger.

Definition at line 308 of file long.h.

## ◆ rb_num2long()

long rb_num2long | ( | VALUE | num | ) |

Converts an instance of rb_cNumeric into C's `long`.

Parameters

  [in] | num | Something numeric.

Exceptions

  rb_eTypeError | `num` is not a numeric.
  rb_eRangeError | `num` is out of range of `long`.

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

Definition at line 3136 of file numeric.c.

Referenced by rb_fix2short(), rb_num2fix(), rb_num2int(), rb_num2long(), rb_num2long_inline(), and rb_num2short().

## ◆ rb_num2long_inline()

static long rb_num2long_inline | ( | VALUE | x | ) |
| inlinestatic

Converts an instance of rb_cNumeric into C's `long`.

Parameters

  [in] | x | Something numeric.

Exceptions

  rb_eTypeError | `x` is not a numeric.
  rb_eRangeError | `x` is out of range of `long`.

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

Definition at line 267 of file long.h.

## ◆ rb_num2ulong()

unsigned long rb_num2ulong | ( | VALUE | num | ) |

Converts an instance of rb_cNumeric into C's `unsigned long`.

Parameters

  [in] | num | Something numeric.

Exceptions

  rb_eTypeError | `num` is not a numeric.
  rb_eRangeError | `num` is out of range of `unsigned long`.

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

Definition at line 3205 of file numeric.c.

Referenced by rb_num2uint(), rb_num2ulong(), and rb_num2ulong_inline().

## ◆ rb_num2ulong_inline()

static unsigned long rb_num2ulong_inline | ( | VALUE | x | ) |
| inlinestatic

Converts an instance of rb_cNumeric into C's `unsigned long`.

Parameters

  [in] | x | Something numeric.

Exceptions

  rb_eTypeError | `x` is not a numeric.
  rb_eRangeError | `x` is out of range of `unsigned long`.

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

Definition at line 293 of file long.h.

## ◆ rb_out_of_int()

void rb_out_of_int | ( | SIGNED_VALUE | num | ) |

This is an utility function to raise an rb_eRangeError.

Parameters

  [in] | num | A signed value about to overflow.

Exceptions

  rb_eRangeError | `num` is out of range of `int`.

Definition at line 3211 of file numeric.c.

Referenced by rb_long2int_inline(), and rb_out_of_int().

## ◆ rb_ulong2num_inline()

static VALUE rb_ulong2num_inline | ( | unsigned long | v | ) |
| inlinestatic

Converts a C's `unsigned long` into an instance of rb_cInteger.

Parameters

  [in] | v | Arbitrary `unsigned long` value.

Returns
  An instance of rb_cInteger.

Definition at line 323 of file long.h.