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

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

Macros | Functions
re.h File Reference

Public APIs related to rb_cRegexp. 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.

## Macros
#define | rb_memcmp memcmp
#define | HAVE_RB_REG_NEW_STR 1

## Functions
int | rb_memcicmp (const void *s1, const void *s2, long n)
| Identical to st_locale_insensitive_strcasecmp(), except it is timing safe and returns something different.
void | rb_match_busy (VALUE md)
| Asserts that the given MatchData is "occupied".
VALUE | rb_reg_nth_defined (int n, VALUE md)
| Identical to rb_reg_nth_match(), except it just returns Boolean.
VALUE | rb_reg_nth_match (int n, VALUE md)
| Queries the nth captured substring.
int | rb_reg_backref_number (VALUE match, VALUE backref)
| Queries the index of the given named capture.
VALUE | rb_reg_last_match (VALUE md)
| This just returns the argument, stringified.
VALUE | rb_reg_match_pre (VALUE md)
| The portion of the original string before the given match.
VALUE | rb_reg_match_post (VALUE md)
| The portion of the original string after the given match.
VALUE | rb_reg_match_last (VALUE md)
| The portion of the original string that captured at the very last.
VALUE | rb_reg_new_str (VALUE src, int opts)
| Identical to rb_reg_new(), except it takes the expression in Ruby's string instead of C's.
VALUE | rb_reg_new (const char *src, long len, int opts)
| Creates a new Regular expression.
VALUE | rb_reg_match (VALUE re, VALUE str)
| This is the match operator.
VALUE | rb_reg_match2 (VALUE re)
| Identical to rb_reg_match(), except it matches against rb_lastline_get() (or, the `$_`).
int | rb_reg_options (VALUE re)
| Queries the options of the passed regular expression.

## Detailed Description

Public APIs related to rb_cRegexp.

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

## Macro Definition Documentation

## ◆ HAVE_RB_REG_NEW_STR

#define HAVE_RB_REG_NEW_STR 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 162 of file re.h.

## ◆ rb_memcmp

#define rb_memcmp memcmp

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 42 of file re.h.

## Function Documentation

## ◆ rb_match_busy()

void rb_match_busy | ( | VALUE | md | ) |

Asserts that the given MatchData is "occupied".

MatchData shares its backend storages with its Regexp object. But programs can destructively tamper its contents. Calling this function beforehand shall prevent such modifications to spill over into other objects.

Parameters

  [out] | md | Target instance of rb_cMatch.

Postcondition
  The object is "busy".

Definition at line 1435 of file re.c.

## ◆ rb_memcicmp()

int rb_memcicmp | ( | const void * | s1,
|  | const void * | s2,
|  | long | n )

Identical to st_locale_insensitive_strcasecmp(), except it is timing safe and returns something different.

Parameters

  [in] | s1 | Comparison LHS.
  [in] | s2 | Comparison RHS.
  [in] | n | Comparison shall stop after first `n` bytes are scanned.

Return values

  <0 | `s1` is "less" than `s2`.
  0 | Both sides converted into lowercase would be identical.
  >0 | `s1` is "greater" than `s2`.

Note
  The "case" here means that of the POSIX Locale.

Definition at line 92 of file re.c.

Referenced by rb_memcicmp().

## ◆ rb_reg_backref_number()

int rb_reg_backref_number | ( | VALUE | match,
|  | VALUE | backref )

Queries the index of the given named capture.

Captures could be named. But that doesn't mean named ones are not indexed. A regular expression can mix named and non-named captures, and they are all indexed. This function converts from a name to its index.

Parameters

  [in] | match | An instance of rb_cMatch.
  [in] | backref | Capture name, in String, Symbol, or Numeric.

Exceptions

  rb_eIndexError | No such named capture.

Returns
  The index of the given name.

Definition at line 1229 of file re.c.

## ◆ rb_reg_last_match()

VALUE rb_reg_last_match | ( | VALUE | md | ) |

This just returns the argument, stringified.

What a poor name.

Parameters

  [in] | md | An instance of rb_cMatch.

Returns
  Its 0th capture (i.e. entire matched string).

Definition at line 1886 of file re.c.

## ◆ rb_reg_match()

VALUE rb_reg_match | ( | VALUE | re,
|  | VALUE | str )

This is the match operator.

Parameters

  [in] | re | An instance of rb_cRegexp.
  [in] | str | An instance of rb_cString.

Exceptions

  rb_eTypeError | `str` is not a string.
  rb_eRegexpError | Error inside of Onigmo (unlikely).

Return values

  RUBY_Qnil | Match failed.
  otherwise | Matched position (character index inside of `str`).

Postcondition
  `Regexp.last_match` is updated.
  `$&`, `$~`, etc., are updated.

Note
  If you do this in ruby, named captures are assigned to local variable of the local scope. But that doesn't happen here. The assignment is done by the interpreter.

Definition at line 3601 of file re.c.

## ◆ rb_reg_match2()

VALUE rb_reg_match2 | ( | VALUE | re | ) |

Identical to rb_reg_match(), except it matches against rb_lastline_get() (or, the `$_`).

Parameters

  [in] | re | An instance of rb_cRegexp.

Exceptions

  rb_eRegexpError | Error inside of Onigmo (unlikely).

Return values

  RUBY_Qnil | Match failed or `$_` is absent.
  otherwise | Matched position (character index inside of `$_`).

Postcondition
  `Regexp.last_match` is updated.
  `$&`, `$~`, etc., are updated.

Definition at line 3656 of file re.c.

## ◆ rb_reg_match_last()

VALUE rb_reg_match_last | ( | VALUE | md | ) |

The portion of the original string that captured at the very last.

Parameters

  [in] | md | An instance of rb_cMatch.

Returns
  Its "lastmatch". This is perl's `$+`.

Definition at line 1960 of file re.c.

## ◆ rb_reg_match_post()

VALUE rb_reg_match_post | ( | VALUE | md | ) |

The portion of the original string after the given match.

Parameters

  [in] | md | An instance of rb_cMatch.

Returns
  Its "postmatch". This is perl's ‘$’`.

Definition at line 1943 of file re.c.

## ◆ rb_reg_match_pre()

VALUE rb_reg_match_pre | ( | VALUE | md | ) |

The portion of the original string before the given match.

Parameters

  [in] | md | An instance of rb_cMatch.

Returns
  Its "prematch". This is perl's `$``.

Definition at line 1910 of file re.c.

## ◆ rb_reg_new()

VALUE rb_reg_new | ( | const char * | src,
|  | long | len,
|  | int | opts )

Creates a new Regular expression.

Parameters

  [in] | src | Source code.
  [in] | len | `strlen(src)`.
  [in] | opts | Options e.g. ONIG_OPTION_MULTILINE.

Returns
  Allocated new instance of rb_cRegexp.

Definition at line 3356 of file re.c.

## ◆ rb_reg_new_str()

VALUE rb_reg_new_str | ( | VALUE | src,
|  | int | opts )

Identical to rb_reg_new(), except it takes the expression in Ruby's string instead of C's.

Parameters

  [in] | src | Source code in String.
  [in] | opts | Options e.g. ONIG_OPTION_MULTILINE.

Exceptions

  rb_eRegexpError | `src` and `opts` do not interface.

Returns
  Allocated new instance of rb_cRegexp.

Definition at line 3302 of file re.c.

Referenced by rb_reg_regcomp().

## ◆ rb_reg_nth_defined()

VALUE rb_reg_nth_defined | ( | int | n,
|  | VALUE | md )

Identical to rb_reg_nth_match(), except it just returns Boolean.

This could skip allocating a returning string, resulting in reduced memory footprints if applicable.

Parameters

  [in] | n | Match index.
  [in] | md | An instance of rb_cMatch.

Exceptions

  rb_eTypeError | `md` is not initialised.

Return values

  RUBY_Qnil | There is no `n`-th capture.
  RUBY_Qfalse | There is a `n`-th capture and is empty.
  RUBY_Qtrue | There is a `n`-th capture that has something.

Definition at line 1844 of file re.c.

## ◆ rb_reg_nth_match()

VALUE rb_reg_nth_match | ( | int | n,
|  | VALUE | md )

Queries the nth captured substring.

Parameters

  [in] | n | Match index.
  [in] | md | An instance of rb_cMatch.

Exceptions

  rb_eTypeError | `md` is not initialised.

Return values

  RUBY_Qnil | There is no `n`-th capture.
  otherwise | An allocated instance of rb_cString containing the contents captured.

Definition at line 1861 of file re.c.

Referenced by rb_reg_last_match(), and rb_reg_match_last().

## ◆ rb_reg_options()

int rb_reg_options | ( | VALUE | re | ) |

Queries the options of the passed regular expression.

Parameters

  [in] | re | An instance of rb_cRegexp.

Returns
  Its options.

Note
  Possible return values are defined in Onigmo.h.

Definition at line 4118 of file re.c.

Referenced by rb_reg_options().