Class: RE2::Set

Inherits:

Object

• Object
• RE2::Set

Defined in:

ext/re2/re2.cc

Class Method Summary

• .match_raises_errors? ⇒ Boolean

  Returns whether the underlying RE2 version outputs error information from `RE2::Set::Match`.

• .size? ⇒ Boolean

  Returns whether the underlying RE2 version has a Set::Size method.

Instance Method Summary

• #add(pattern) ⇒ Integer

  Adds a pattern to the set.

• #compile ⇒ Boolean

  Compiles a Set so it can be used to match against.

• #initialize(*args) ⇒ RE2::Set constructor

  Returns a new Set object, a collection of patterns that can be searched for simultaneously.

• #initialize_copy() ⇒ Object
• #length ⇒ Integer

  Returns the size of the Set.

• #match(*args) ⇒ Array<Integer>

  Matches the given text against patterns in the set, returning an array of integer indices of the matching patterns if matched or an empty array if there are no matches.

• #size ⇒ Integer

  Returns the size of the Set.

Constructor Details

#initialize ⇒ RE2::Set #initialize(anchor) ⇒ RE2::Set #initialize(anchor, options) ⇒ RE2::Set

Returns a new RE2::Set object, a collection of patterns that can be searched for simultaneously.

Overloads:

• #initialize ⇒ RE2::Set

  Returns a new RE2::Set object for unanchored patterns with the default options.

  Raises:

  • (NoMemoryError) —

    if memory could not be allocated for the compiled pattern

• #initialize(anchor) ⇒ RE2::Set

  Returns a new RE2::Set object for the specified anchor with the default options.

  Parameters:

  • anchor (Symbol) —

    one of :unanchored, :anchor_start, :anchor_both

  Raises:

  • (ArgumentError) —

    if anchor is not :unanchored, :anchor_start or :anchor_both

  • (NoMemoryError) —

    if memory could not be allocated for the compiled pattern

• #initialize(anchor, options) ⇒ RE2::Set

  Returns a new RE2::Set object with the specified options.

  Parameters:

  • anchor (Symbol) —

    one of :unanchored, :anchor_start, :anchor_both

  • options (Hash) —

    the options with which to compile the pattern

  Options Hash (options):

  • :utf8 (Boolean) — default: true —

    text and pattern are UTF-8; otherwise Latin-1

  • :posix_syntax (Boolean) — default: false —

    restrict regexps to POSIX egrep syntax

  • :longest_match (Boolean) — default: false —

    search for longest match, not first match

  • :log_errors (Boolean) — default: true —

    log syntax and execution errors to ERROR

  • :max_mem (Integer) —

    approx. max memory footprint of RE2

  • :literal (Boolean) — default: false —

    interpret string as literal, not regexp

  • :never_nl (Boolean) — default: false —

    never match \n, even if it is in regexp

  • :case_sensitive (Boolean) — default: true —

    match is case-sensitive (regexp can override with (?i) unless in posix_syntax mode)

  • :perl_classes (Boolean) — default: false —

    allow Perl's \d \s \w \D \S \W when in posix_syntax mode

  • :word_boundary (Boolean) — default: false —

    allow \b \B (word boundary and not) when in posix_syntax mode

  • :one_line (Boolean) — default: false —

    ^ and $ only match beginning and end of text when in posix_syntax mode

  Raises:

  • (ArgumentError) —

    if anchor is not one of the accepted choices

  • (NoMemoryError) —

    if memory could not be allocated for the compiled pattern

# File 'ext/re2/re2.cc', line 2559

static VALUE re2_set_initialize(int argc, VALUE *argv, VALUE self) {
  VALUE anchor, options;
  re2_set *s;

  rb_scan_args(argc, argv, "02", &anchor, &options);
  TypedData_Get_Struct(self, re2_set, &re2_set_data_type, s);

  RE2::Anchor re2_anchor = RE2::UNANCHORED;

  if (!NIL_P(anchor)) {
    Check_Type(anchor, T_SYMBOL);
    ID id_anchor_arg = SYM2ID(anchor);
    if (id_anchor_arg == id_unanchored) {
      re2_anchor = RE2::UNANCHORED;
    } else if (id_anchor_arg == id_anchor_start) {
      re2_anchor = RE2::ANCHOR_START;
    } else if (id_anchor_arg == id_anchor_both) {
      re2_anchor = RE2::ANCHOR_BOTH;
    } else {
      rb_raise(rb_eArgError, "anchor should be one of: :unanchored, :anchor_start, :anchor_both");
    }
  }

  RE2::Options re2_options;

  if (RTEST(options)) {
    parse_re2_options(&re2_options, options);
  }

  rb_check_frozen(self);

  /* Prevent re-initialisation: #match releases the GVL while holding a
   * pointer to s->set, so replacing s->set from another thread would free
   * the object out from under a concurrent match.
   */
  if (s->set) {
    rb_raise(rb_eTypeError, "already initialized RE2::Set");
  }

  s->set = new(std::nothrow) RE2::Set(re2_options, re2_anchor);
  if (s->set == nullptr) {
    rb_raise(rb_eNoMemError, "not enough memory to allocate RE2::Set object");
  }

  return self;
}

Class Method Details

.match_raises_errors? ⇒ Boolean

Returns whether the underlying RE2 version outputs error information from `RE2::Set::Match`. If not, #match will raise an error if attempting to set its :exception option to true.

Returns:

• (Boolean) —

  whether the underlying RE2 outputs error information from RE2::Set matches

# File 'ext/re2/re2.cc', line 2694

static VALUE re2_set_match_raises_errors_p(VALUE) {
#ifdef HAVE_ERROR_INFO_ARGUMENT
  return Qtrue;
#else
  return Qfalse;
#endif
}

.size? ⇒ Boolean

Returns whether the underlying RE2 version has a Set::Size method.

Returns:

• (Boolean) —

  whether the underlying RE2 has a Set::Size method

# File 'ext/re2/re2.cc', line 2707

static VALUE re2_set_size_p(VALUE) {
#ifdef HAVE_SET_SIZE
  return Qtrue;
#else
  return Qfalse;
#endif
}

Instance Method Details

#add(pattern) ⇒ Integer

Adds a pattern to the set. Returns the index that will identify the pattern in the output of #match. Cannot be called after #compile has been called.

Examples:

set = RE2::Set.new
set.add("abc") #=> 0
set.add("def") #=> 1

Parameters:

• pattern (String) —

  the regex pattern

Returns:

• (Integer) —

  the index of the pattern in the set

Raises:

• (ArgumentError) —

  if called after compile or the pattern is rejected

# File 'ext/re2/re2.cc', line 2619

static VALUE re2_set_add(VALUE self, VALUE pattern) {
  StringValue(pattern);

  re2_set *s = unwrap_re2_set(self);
  rb_check_frozen(self);

  int index;
  VALUE msg;

  {
    std::string err;
    index = s->set->Add(
        re2::StringPiece(RSTRING_PTR(pattern), RSTRING_LEN(pattern)), &err);
    msg = rb_str_new(err.data(), err.size());
  }

  if (index < 0) {
    rb_raise(rb_eArgError,
             "str rejected by RE2::Set->Add(): %s", RSTRING_PTR(msg));
  }

  return INT2FIX(index);
}

#compile ⇒ Boolean

Compiles a RE2::Set so it can be used to match against. Must be called after #add and before #match.

Examples:

set = RE2::Set.new
set.add("abc")
set.compile #=> true

Returns:

• (Boolean) —

  whether compilation was a success

# File 'ext/re2/re2.cc', line 2653

static VALUE re2_set_compile(VALUE self) {
  re2_set *s = unwrap_re2_set(self);
  rb_check_frozen(self);

  bool compiled = s->set->Compile();

  if (compiled) {
    s->compiled = true;
    rb_obj_freeze(self);
  }

  return BOOL2RUBY(compiled);
}

#initialize_copy() ⇒ Object

# File 'ext/re2/re2.cc', line 2514

static VALUE re2_set_initialize_copy(VALUE, VALUE) {
  rb_raise(rb_eTypeError, "cannot copy RE2::Set");
}

#length ⇒ Integer

Returns the size of the RE2::Set.

Examples:

set = RE2::Set.new
set.add("abc")
set.size #=> 1

Returns:

• (Integer) —

  the number of patterns in the set

# File 'ext/re2/re2.cc', line 2676

static VALUE re2_set_size(VALUE self) {
#ifdef HAVE_SET_SIZE
  re2_set *s = unwrap_re2_set(self);

  return INT2FIX(s->set->Size());
#else
  rb_raise(re2_eSetUnsupportedError, "current version of RE2::Set does not have Size method");
#endif
}

#match(str) ⇒ Array<Integer> #match(str, options) ⇒ Array<Integer>

Matches the given text against patterns in the set, returning an array of integer indices of the matching patterns if matched or an empty array if there are no matches.

Overloads:

• #match(str) ⇒ Array<Integer>

  Returns an array of integer indices of patterns matching the given string (if any). Raises exceptions if there are any errors while matching.

  Examples:

  set = RE2::Set.new
  set.add("abc")
  set.add("def")
  set.compile
  set.match("abcdef") #=> [0, 1]

  Parameters:

  • str (String) —

    the text to match against

  Returns:

  • (Array<Integer>) —

    the indices of matching regexps

  Raises:

  • (MatchError) —

    if an error occurs while matching

  • (UnsupportedError) —

    if the underlying version of RE2 does not output error information

• #match(str, options) ⇒ Array<Integer>

  Returns an array of integer indices of patterns matching the given string (if any). Raises exceptions if there are any errors while matching and the :exception option is set to true.

  Examples:

  set = RE2::Set.new
  set.add("abc")
  set.add("def")
  set.compile
  set.match("abcdef", exception: true) #=> [0, 1]

  Parameters:

  • str (String) —

    the text to match against

  • options (Hash) —

    the options with which to match

  Options Hash (options):

  • :exception (Boolean) — default: true —

    whether to raise exceptions with RE2's error information (not supported on ABI version 0 of RE2)

  Returns:

  • (Array<Integer>) —

    the indices of matching regexps

  Raises:

  • (MatchError) —

    if an error occurs while matching

  • (UnsupportedError) —

    if the underlying version of RE2 does not output error information

Returns:

• (Array<Integer>)

# File 'ext/re2/re2.cc', line 2755

static VALUE re2_set_match(int argc, VALUE *argv, const VALUE self) {
  VALUE str, options;
  bool raise_exception = true;
  rb_scan_args(argc, argv, "11", &str, &options);

  StringValue(str);
  str = rb_str_new_frozen(str);

  re2_set *s = unwrap_re2_set(self);

  if (RTEST(options)) {
    Check_Type(options, T_HASH);

    VALUE exception_option = rb_hash_aref(options, ID2SYM(id_exception));
    if (!NIL_P(exception_option)) {
      raise_exception = RTEST(exception_option);
    }
  }

  std::vector<int> v;

  if (raise_exception) {
#ifdef HAVE_ERROR_INFO_ARGUMENT
    /* RE2::Set::Match dereferences a null program after a failed Compile. */
    if (!s->compiled) {
      rb_raise(re2_eSetMatchError, "#match must not be called before #compile");
    }

    RE2::Set::ErrorInfo e;
    nogvl_set_match_arg arg;
    arg.set = s->set;
    arg.text = re2::StringPiece(RSTRING_PTR(str), RSTRING_LEN(str));
    arg.v = &v;
    arg.error_info = &e;
    arg.matched = false;

#ifdef _WIN32
    nogvl_set_match(&arg);
#else
    rb_thread_call_without_gvl(nogvl_set_match, &arg, NULL, NULL);
#endif
    RB_GC_GUARD(str);

    bool match_failed = !arg.matched;
    VALUE result = rb_ary_new2(v.size());

    if (match_failed) {
      switch (e.kind) {
        case RE2::Set::kNoError:
          break;
        case RE2::Set::kNotCompiled:
          rb_raise(re2_eSetMatchError, "#match must not be called before #compile");
        case RE2::Set::kOutOfMemory:
          rb_raise(re2_eSetMatchError, "The DFA ran out of memory");
        case RE2::Set::kInconsistent:
          rb_raise(re2_eSetMatchError, "RE2::Prog internal error");
        default:  // Just in case a future version of libre2 adds new ErrorKinds
          rb_raise(re2_eSetMatchError, "Unknown RE2::Set::ErrorKind: %d", e.kind);
      }
    } else {
      for (int index : v) {
        rb_ary_push(result, INT2FIX(index));
      }
    }

    return result;
#else
    rb_raise(re2_eSetUnsupportedError, "current version of RE2::Set::Match() does not output error information, :exception option can only be set to false");
#endif
  } else {
    if (!s->compiled) {
      return rb_ary_new();
    }

    nogvl_set_match_arg arg;
    arg.set = s->set;
    arg.text = re2::StringPiece(RSTRING_PTR(str), RSTRING_LEN(str));
    arg.v = &v;
#ifdef HAVE_ERROR_INFO_ARGUMENT
    arg.error_info = nullptr;
#endif
    arg.matched = false;

#ifdef _WIN32
    nogvl_set_match(&arg);
#else
    rb_thread_call_without_gvl(nogvl_set_match, &arg, NULL, NULL);
#endif
    RB_GC_GUARD(str);

    VALUE result = rb_ary_new2(v.size());

    if (arg.matched) {
      for (int index : v) {
        rb_ary_push(result, INT2FIX(index));
      }
    }

    return result;
  }
}

#size ⇒ Integer

Returns the size of the RE2::Set.

Examples:

set = RE2::Set.new
set.add("abc")
set.size #=> 1

Returns:

• (Integer) —

  the number of patterns in the set

# File 'ext/re2/re2.cc', line 2676

static VALUE re2_set_size(VALUE self) {
#ifdef HAVE_SET_SIZE
  re2_set *s = unwrap_re2_set(self);

  return INT2FIX(s->set->Size());
#else
  rb_raise(re2_eSetUnsupportedError, "current version of RE2::Set does not have Size method");
#endif
}