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

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

Functions
range.h File Reference

Public APIs related to rb_cRange. More...

`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
VALUE | rb_range_new (VALUE beg, VALUE end, int excl)
| Creates a new Range.
VALUE | rb_range_beg_len (VALUE range, long *begp, long *lenp, long len, int err)
| Deconstructs a numerical range.
int | rb_range_values (VALUE range, VALUE *begp, VALUE *endp, int *exclp)
| Deconstructs a range into its components.

## Detailed Description

Public APIs related to rb_cRange.

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

## Function Documentation

## ◆ rb_range_beg_len()

VALUE rb_range_beg_len | ( | VALUE | range,
|  | long * | begp,
|  | long * | lenp,
|  | long | len,
|  | int | err )

Deconstructs a numerical range.

As the arguments are `long` based, it expects everything are in the `long` domain.

Parameters

  [in] | range | A range of numerical endpoints.
  [out] | begp | Return value buffer.
  [out] | lenp | Return value buffer.
  [in] | len | Updated length.
  [in] | err | In case `len` is out of range... `0`: returns RUBY_Qnil. `1`: raises rb_eRangeError. `2`: `beg` and `len` expanded accordingly.

Exceptions

  rb_eTypeError | `range` is not a numerical range.
  rb_eRangeError | `range` cannot fit into `long`.

Return values

  RUBY_Qfalse | `range` is not an rb_cRange.
  RUBY_Qnil | `len` is out of `range` but `err` is zero.
  RUBY_Qtrue | Otherwise.

Postcondition
  `beg` is the (possibly updated) left endpoint.
  `len` is the (possibly updated) length of the range.

Definition at line 1578 of file range.c.

Referenced by rb_get_values_at().

## ◆ rb_range_new()

VALUE rb_range_new | ( | VALUE | beg,
|  | VALUE | end,
|  | int | excl )

Creates a new Range.

Parameters

  [in] | beg | "Left" or "lowest" endpoint of the range.
  [in] | end | "Right" or "highest" endpoint of the range.
  [in] | excl | Whether the range is open-ended.

Exceptions

  rb_eArgError | `beg` and `end` are not comparable.

Note
  These days both endpoints can be RUBY_Qnil, which means that endpoint is unbound.

Definition at line 67 of file range.c.

Referenced by rb_range_new().

## ◆ rb_range_values()

int rb_range_values | ( | VALUE | range,
|  | VALUE * | begp,
|  | VALUE * | endp,
|  | int * | exclp )

Deconstructs a range into its components.

Parameters

  [in] | range | Range or range-ish object.
  [out] | begp | Return value buffer.
  [out] | endp | Return value buffer.
  [out] | exclp | Return value buffer.

Return values

  RUBY_Qfalse | `range` is not an instance of rb_cRange.
  RUBY_Qtrue | Argument pointers are updated.

Postcondition
  `*begp` is the left endpoint of the range.
  `*endp` is the right endpoint of the range.
  `*exclp` is whether the range is open-ended or not.

Definition at line 1490 of file range.c.

Referenced by rb_arithmetic_sequence_extract(), and rb_range_beg_len().