Ruby: include/ruby/internal/core/rmatch.h File Reference

Ruby 3.3.7p123 (2025-01-15 revision be31f993d7fa0219d85f7b3c694d454da4ecc10b)

Data Structures | Macros | Typedefs | Functions
rmatch.h File Reference

Defines struct RMatch. More...

`#include "ruby/internal/attr/artificial.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/core/rbasic.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/value_type.h"`
`#include "ruby/assert.h"`

Go to the source code of this file.

## Data Structures
struct | rmatch_offset
| Represents the region of a capture group. More...
struct | rb_matchext_struct
| Represents a match. More...
struct | RMatch
| Regular expression execution context. More...

## Macros
#define | RMATCH(obj)
| Convenient casting macro.
#define | RMATCH_EXT(m)

## Typedefs
typedef struct re_pattern_buffer | Regexp
| Old name of re_pattern_buffer.
typedef struct rb_matchext_struct | rb_matchext_t

## Functions
static struct re_registers * | RMATCH_REGS (VALUE match)
| Queries the raw re_registers.

## Detailed Description

Defines struct RMatch.

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

## Macro Definition Documentation

## ◆ RMATCH

#define RMATCH | ( |  | obj | ) |

Value:
RBIMPL_CAST((struct RMatch *)(obj))
RMatch
Regular expression execution context.
Definition rmatch.h:96

Convenient casting macro.

Parameters

  obj | An object, which is in fact an RMatch.

Returns
  The passed object casted to RMatch.

Definition at line 37 of file rmatch.h.

Referenced by rb_reg_match_last(), rb_reg_match_post(), rb_reg_match_pre(), and rb_reg_nth_match().

## ◆ RMATCH_EXT

#define RMATCH_EXT | ( |  | m | ) |

Value:
((rb_matchext_t *)((char *)(m) + sizeof(struct RMatch)))

Definition at line 112 of file rmatch.h.

## Typedef Documentation

## ◆ rb_matchext_t

typedef struct rb_matchext_struct rb_matchext_t

Definition at line 85 of file rmatch.h.

## Function Documentation

## ◆ RMATCH_REGS()

static struct re_registers * RMATCH_REGS | ( | VALUE | match | ) |
| inlinestatic

Queries the raw re_registers.

Parameters

  [in] | match | A match object

Precondition
  `match` must be of RMatch.

Returns
  Its execution result.

Note
  Good. So you are aware of the fact that it could return NULL. Yes. It actually does. This is a really bizarre thing. The situation is about `String#gsub` and its family. They take strings as arguments, like `"foo".sub("bar", "baz")`. On such situations, in order to optimise memory allocations, these methods do not involve regular expressions at all. They just sequentially scan the receiver. Okay. The story begins here. Even when they do not kick our regexp engine, there must be backref objects e.g. `$&`. But how? You know what? Ruby fakes them. It allocates an empty RMatch and behaves as if there were execution contexts. In reality there weren't. No re_registers are allocated then. There is no way for this function but to return NULL for those fake RMatch. This is the reason for the nullability of this function.

Definition at line 138 of file rmatch.h.

Referenced by rb_reg_match_last(), rb_reg_match_post(), rb_reg_match_pre(), rb_reg_nth_defined(), rb_reg_nth_match(), and RMATCH_REGS().