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

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

Macros | Functions
complex.h File Reference

Public APIs related to rb_cComplex. More...

`#include "ruby/internal/attr/deprecated.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/arithmetic/long.h"`

Go to the source code of this file.

## Macros
#define | rb_complex_raw1(x)
| Shorthand of `x+0i`.
#define | rb_complex_raw2(x, y)
| Just another name of rb_complex_raw.
#define | rb_complex_new1(x)
| Shorthand of `x+0i`.
#define | rb_complex_new2(x, y)
| Just another name of rb_complex_new.
#define | rb_complex_add rb_complex_plus
| Just another name of rb_complex_plus.
#define | rb_complex_sub rb_complex_minus
| Just another name of rb_complex_minus.
#define | rb_complex_nagate rb_complex_uminus
| Just another name of rb_complex_uminus.
#define | rb_Complex1(x)
| Shorthand of `x+0i`.
#define | rb_Complex2(x, y)
| Just another name of rb_Complex.

## Functions
VALUE | rb_complex_raw (VALUE real, VALUE imag)
| Identical to rb_complex_new(), except it assumes both arguments are not instances of rb_cComplex.
VALUE | rb_complex_new (VALUE real, VALUE imag)
| Constructs a Complex, by first multiplying the imaginary part with `1i` then adds it to the real part.
VALUE | rb_complex_new_polar (VALUE abs, VALUE arg)
| Constructs a Complex using polar representations.
VALUE | rb_complex_polar (VALUE abs, VALUE arg)
| Old name of rb_complex_new_polar.
VALUE | rb_complex_real (VALUE z)
| Queries the real part of the passed Complex.
VALUE | rb_complex_imag (VALUE z)
| Queries the imaginary part of the passed Complex.
VALUE | rb_complex_plus (VALUE x, VALUE y)
| Performs addition of the passed two objects.
VALUE | rb_complex_minus (VALUE x, VALUE y)
| Performs subtraction of the passed two objects.
VALUE | rb_complex_mul (VALUE x, VALUE y)
| Performs multiplication of the passed two objects.
VALUE | rb_complex_div (VALUE x, VALUE y)
| Performs division of the passed two objects.
VALUE | rb_complex_uminus (VALUE z)
| Performs negation of the passed object.
VALUE | rb_complex_conjugate (VALUE z)
| Performs complex conjugation of the passed object.
VALUE | rb_complex_abs (VALUE z)
| Queries the absolute (or the magnitude) of the passed object.
VALUE | rb_complex_arg (VALUE z)
| Queries the argument (or the angle) of the passed object.
VALUE | rb_complex_pow (VALUE base, VALUE exp)
| Performs exponentiation of the passed two objects.
VALUE | rb_dbl_complex_new (double real, double imag)
| Identical to rb_complex_new(), except it takes the arguments as C's double instead of Ruby's object.
VALUE | rb_Complex (VALUE real, VALUE imag)
| Converts various values into a Complex.

## Detailed Description

Public APIs related to rb_cComplex.

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 complex.h.

## Macro Definition Documentation

## ◆ rb_Complex1

#define rb_Complex1 | ( |  | x | ) |

Value:
rb_Complex((x), INT2FIX(0))
INT2FIX
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
rb_Complex
VALUE rb_Complex(VALUE real, VALUE imag)
Converts various values into a Complex.
Definition complex.c:1566

Shorthand of `x+0i`.

It practically converts `x` into a Complex of the identical value.

Parameters

  [in] | x | rb_cNumeric, rb_cString, or something that responds to `#to_c`.

Returns
  An instance of rb_cComplex, whose value is `x + 0i`.

Definition at line 246 of file complex.h.

## ◆ rb_Complex2

#define rb_Complex2 | ( |  | x,
|  |  | y )

Value:
rb_Complex((x), (y))

Just another name of rb_Complex.

Definition at line 249 of file complex.h.

## ◆ rb_complex_add

#define rb_complex_add rb_complex_plus

Just another name of rb_complex_plus.

Definition at line 205 of file complex.h.

## ◆ rb_complex_nagate

#define rb_complex_nagate rb_complex_uminus

Just another name of rb_complex_uminus.

Definition at line 211 of file complex.h.

## ◆ rb_complex_new1

#define rb_complex_new1 | ( |  | x | ) |

Value:
rb_complex_new((x), INT2FIX(0))
rb_complex_new
VALUE rb_complex_new(VALUE real, VALUE imag)
Constructs a Complex, by first multiplying the imaginary part with 1i then adds it to the real part.
Definition complex.c:1548

Shorthand of `x+0i`.

It practically converts `x` into a Complex of the identical value.

Parameters

  [in] | x | Any numeric value.

Returns
  An instance of rb_cComplex, whose value is `x + 0i`.

Definition at line 74 of file complex.h.

## ◆ rb_complex_new2

#define rb_complex_new2 | ( |  | x,
|  |  | y )

Value:
rb_complex_new((x), (y))

Just another name of rb_complex_new.

Definition at line 77 of file complex.h.

## ◆ rb_complex_raw1

#define rb_complex_raw1 | ( |  | x | ) |

Value:
rb_complex_raw((x), INT2FIX(0))
rb_complex_raw
VALUE rb_complex_raw(VALUE real, VALUE imag)
Identical to rb_complex_new(), except it assumes both arguments are not instances of rb_cComplex.
Definition complex.c:1542

Shorthand of `x+0i`.

It practically converts `x` into a Complex of the identical value.

Parameters

  [in] | x | Any numeric except Complex.

Returns
  An instance of rb_cComplex, whose value is `x + 0i`.

Definition at line 50 of file complex.h.

## ◆ rb_complex_raw2

#define rb_complex_raw2 | ( |  | x,
|  |  | y )

Value:
rb_complex_raw((x), (y))

Just another name of rb_complex_raw.

Definition at line 53 of file complex.h.

## ◆ rb_complex_sub

#define rb_complex_sub rb_complex_minus

Just another name of rb_complex_minus.

Definition at line 208 of file complex.h.

## Function Documentation

## ◆ rb_Complex()

VALUE rb_Complex | ( | VALUE | real,
|  | VALUE | imag )

Converts various values into a Complex.

This function accepts:

- Instances of rb_cComplex (taken as-is),
- Instances of rb_cNumeric (adds `0i`),
- Instances of rb_cString (parses),
- Other objects that respond to `#to_c`.

It (possibly recursively) applies `#to_c` until both sides become a Complex value, then computes `imag * 1i + real`.

As a special case, passing RUBY_Qundef to `imag` is the same as passing `RB_INT2NUM(0)`.

Parameters

  [in] | real | Real part (see above).
  [in] | imag | Imaginary part (see above).

Exceptions

  rb_eTypeError | Passed something not described above.

Returns
  An instance of rb_cComplex whose value is `1i * imag + real`.

Definition at line 1566 of file complex.c.

## ◆ rb_complex_abs()

VALUE rb_complex_abs | ( | VALUE | z | ) |

Queries the absolute (or the magnitude) of the passed object.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  Its magnitude, in rb_cFloat.

Definition at line 1181 of file complex.c.

## ◆ rb_complex_arg()

VALUE rb_complex_arg | ( | VALUE | z | ) |

Queries the argument (or the angle) of the passed object.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  Its magnitude, in rb_cFloat.

Definition at line 1228 of file complex.c.

## ◆ rb_complex_conjugate()

VALUE rb_complex_conjugate | ( | VALUE | z | ) |

Performs complex conjugation of the passed object.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  Its complex conjugate, in rb_cComplex.

Definition at line 1274 of file complex.c.

## ◆ rb_complex_div()

VALUE rb_complex_div | ( | VALUE | x,
|  | VALUE | y )

Performs division of the passed two objects.

Parameters

  [in] | x | An instance of rb_cComplex.
  [in] | y | Arbitrary ruby object.

Returns
  What `x / y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 957 of file complex.c.

## ◆ rb_complex_imag()

VALUE rb_complex_imag | ( | VALUE | z | ) |

Queries the imaginary part of the passed Complex.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  Its imaginary part, which is an instance of rb_cNumeric.

Definition at line 752 of file complex.c.

## ◆ rb_complex_minus()

VALUE rb_complex_minus | ( | VALUE | x,
|  | VALUE | y )

Performs subtraction of the passed two objects.

Parameters

  [in] | x | An instance of rb_cComplex.
  [in] | y | Arbitrary ruby object.

Returns
  What `x - y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 821 of file complex.c.

## ◆ rb_complex_mul()

VALUE rb_complex_mul | ( | VALUE | x,
|  | VALUE | y )

Performs multiplication of the passed two objects.

Parameters

  [in] | x | An instance of rb_cComplex.
  [in] | y | Arbitrary ruby object.

Returns
  What `x * y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 881 of file complex.c.

## ◆ rb_complex_new()

VALUE rb_complex_new | ( | VALUE | real,
|  | VALUE | imag )

Constructs a Complex, by first multiplying the imaginary part with `1i` then adds it to the real part.

This definition doesn't need both arguments be real numbers. It can happily combine two instances of rb_cComplex (with rotating the latter one).

Parameters

  [in] | real | An instance of rb_cNumeric.
  [in] | imag | Another instance of rb_cNumeric.

Returns
  An instance of rb_cComplex whose value is `imag * 1i + real`.

Definition at line 1548 of file complex.c.

## ◆ rb_complex_new_polar()

VALUE rb_complex_new_polar | ( | VALUE | abs,
|  | VALUE | arg )

Constructs a Complex using polar representations.

Unlike rb_complex_new() it makes no sense to pass non-real instances to this function.

Parameters

  [in] | abs | Magnitude, in any numeric except Complex.
  [in] | arg | Angle, in radians, in any numeric except Complex.

Returns
  An instance of rb_cComplex which denotes the given polar coordinates.

Definition at line 1554 of file complex.c.

## ◆ rb_complex_plus()

VALUE rb_complex_plus | ( | VALUE | x,
|  | VALUE | y )

Performs addition of the passed two objects.

Parameters

  [in] | x | An instance of rb_cComplex.
  [in] | y | Arbitrary ruby object.

Returns
  What `x + y` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 787 of file complex.c.

## ◆ rb_complex_pow()

VALUE rb_complex_pow | ( | VALUE | base,
|  | VALUE | exp )

Performs exponentiation of the passed two objects.

Parameters

  [in] | base | An instance of rb_cComplex.
  [in] | exp | Arbitrary ruby object.

Returns
  What `base ** exp` evaluates to.

See also
  rb_num_coerce_bin()

Definition at line 994 of file complex.c.

## ◆ rb_complex_raw()

VALUE rb_complex_raw | ( | VALUE | real,
|  | VALUE | imag )

Identical to rb_complex_new(), except it assumes both arguments are not instances of rb_cComplex.

It is thus dangerous for extension libraries.

Parameters

  [in] | real | Real part, in any numeric except Complex.
  [in] | imag | Imaginary part, in any numeric except Complex.

Returns
  An instance of rb_cComplex whose value is `real + (imag)i`.

Definition at line 1542 of file complex.c.

## ◆ rb_complex_real()

VALUE rb_complex_real | ( | VALUE | z | ) |

Queries the real part of the passed Complex.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  Its real part, which is an instance of rb_cNumeric.

Definition at line 735 of file complex.c.

## ◆ rb_complex_uminus()

VALUE rb_complex_uminus | ( | VALUE | z | ) |

Performs negation of the passed object.

Parameters

  [in] | z | An instance of rb_cComplex.

Returns
  What `-z` evaluates to.

Definition at line 767 of file complex.c.

## ◆ rb_dbl_complex_new()

VALUE rb_dbl_complex_new | ( | double | real,
|  | double | imag )

Identical to rb_complex_new(), except it takes the arguments as C's double instead of Ruby's object.

Parameters

  [in] | real | Real part.
  [in] | imag | Imaginary part.

Returns
  An instance of rb_cComplex whose value is `real + (imag)i`.

Definition at line 1575 of file complex.c.