voca/words.js

The ultimate JavaScript string library

'use strict';

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

/**
 * Splits `subject` into an array of words.
 *
 * @function words
 * @static
 * @since 1.0.0
 * @memberOf Split
 * @param {string} [subject=''] The string to split into words.
 * @param {string|RegExp} [pattern] The pattern to watch words. 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 {Array} Returns the array of words.
 * @example
 * v.words('gravity can cross dimensions');
 * // => ['gravity', 'can', 'cross', 'dimensions']
 *
 * v.words('GravityCanCrossDimensions');
 * // => ['Gravity', 'Can', 'Cross', 'Dimensions']
 *
 * v.words('Gravity - can cross dimensions!');
 * // => ['Gravity', 'can', 'cross', 'dimensions']
 *
 * v.words('Earth gravity', /[^\s]+/g);
 * // => ['Earth', 'gravity']
 */

function words(subject, pattern, flags) {
  var subjectString = coerce_to_string.coerceToString(subject);
  var patternRegExp;

  if (is_nil.isNil(pattern)) {
    patternRegExp = const_extended.REGEXP_EXTENDED_ASCII.test(subjectString) ? const_extended.REGEXP_LATIN_WORD : const_extended.REGEXP_WORD;
  } else if (pattern instanceof RegExp) {
    patternRegExp = pattern;
  } else {
    var flagsString = to_string.toString(nil_default.nilDefault(flags, ''));
    patternRegExp = new RegExp(to_string.toString(pattern), flagsString);
  }

  return nil_default.nilDefault(subjectString.match(patternRegExp), []);
}

module.exports = words;