voca/matches.js

The ultimate JavaScript string library

'use strict';

require('./internal/is_nil.js');
require('./is_string.js');
var coerce_to_string = require('./internal/coerce_to_string.js');
var to_string = require('./internal/to_string.js');

/**
 * Checks whether `subject` matches the regular expression `pattern`.
 *
 * @function matches
 * @static
 * @since 1.0.0
 * @memberOf Query
 * @param {string} [subject=''] The string to verify.
 * @param {RegExp|string} pattern The pattern to match. If `pattern` is not RegExp, it is transformed to `new RegExp(pattern, flags)`.
 * @param {string} [flags=''] The regular expression flags. Applies when `pattern` is string type.
 * @return {boolean} Returns `true` if `subject` matches `pattern` or `false` otherwise.
 * @example
 * v.matches('pluto', /plu.{2}/);
 * // => true
 *
 * v.matches('sun', 'S', 'i');
 * // => true
 *
 * v.matches('apollo 11', '\\d{3}');
 * // => false
 */

function matches(subject, pattern, flags) {
  var subjectString = coerce_to_string.coerceToString(subject);
  var flagsString = coerce_to_string.coerceToString(flags);
  var patternString;

  if (!(pattern instanceof RegExp)) {
    patternString = to_string.toString(pattern);

    if (patternString === null) {
      return false;
    }

    pattern = new RegExp(patternString, flagsString);
  }

  return pattern.test(subjectString);
}

module.exports = matches;