(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Public APIs related to rb_cRegexp. More...

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

Include dependency graph for re.h:

This graph shows which files directly or indirectly include 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. More...

void	rb_match_busy (VALUE md)
	Asserts that the given MatchData is "occupied". More...

VALUE	rb_reg_nth_defined (int n, VALUE md)
	Identical to rb_reg_nth_match(), except it just returns Boolean. More...

VALUE	rb_reg_nth_match (int n, VALUE md)
	Queries the nth captured substring. More...

int	rb_reg_backref_number (VALUE match, VALUE backref)
	Queries the index of the given named capture. More...

VALUE	rb_reg_last_match (VALUE md)
	This just returns the argument, stringified. More...

VALUE	rb_reg_match_pre (VALUE md)
	The portion of the original string before the given match. More...

VALUE	rb_reg_match_post (VALUE md)
	The portion of the original string after the given match. More...

VALUE	rb_reg_match_last (VALUE md)
	The portion of the original string that captured at the very last. More...

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. More...

VALUE	rb_reg_new (const char *src, long len, int opts)
	Creates a new Regular expression. More...

VALUE	rb_reg_match (VALUE re, VALUE str)
	This is the match operator. More...

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

int	rb_reg_options (VALUE re)
	Queries the options of the passed regular expression. More...

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 157 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 1489 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 95 of file re.c.

◆ 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 1235 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 1930 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 3695 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 3750 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 2020 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 1987 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 1954 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 3456 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 3402 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 1888 of file re.c.

Referenced by rb_f_global_variables().

◆ 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 1905 of file re.c.

Referenced by rb_reg_last_match().

◆ 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 4198 of file re.c.

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ HAVE_RB_REG_NEW_STR

◆ rb_memcmp

Function Documentation

◆ rb_match_busy()

◆ rb_memcicmp()

◆ rb_reg_backref_number()

◆ rb_reg_last_match()

◆ rb_reg_match()

◆ rb_reg_match2()

◆ rb_reg_match_last()

◆ rb_reg_match_post()

◆ rb_reg_match_pre()

◆ rb_reg_new()

◆ rb_reg_new_str()

◆ rb_reg_nth_defined()

◆ rb_reg_nth_match()

◆ rb_reg_options()