Travis CI Build Code Coverage Report Voca npm package

Voca is a JavaScript library for manipulating strings.

v.camelCase('bird flight');              // => 'birdFlight'
v.sprintf('%s costs $%.2f', 'Tea', 1.5); // => 'Tea costs $1.50'
v.slugify('What a wonderful world');     // => 'what-a-wonderful-world'

The Voca library offers helpful functions to make string manipulations comfortable: change case, trim, pad, slugify, latinise, sprintf'y, truncate, escape and much more. The modular design allows to load the entire library, or individual functions to minimize the application builds. The library is fully tested, well documented and long-term supported.

Features

  • Provides the complete set of functions to manipulate, chop, format, escape and query strings
  • Includes detailed, easy to read and searchable documentation
  • Supports a wide range of environments: Node.js 0.10+, Chrome, Firefox, Safari 7+, Edge 13+, IE 9+
  • 100% code coverage
  • No dependencies

Usage

Voca can be used in various environments.

Node.js, Rollup, Webpack, Browserify

Install the library with npm into your local modules directory:
npm install voca

CommonJS modules

Then in your application require the entire library:
var v = require('voca');
v.trim(' Hello World! ');            // => 'Hello World'
v.sprintf('%d red %s', 3, 'apples'); // => '3 red apples'
Or require individual functions:
var words = require('voca/words');
var slugify = require('voca/slugify');
words('welcome to Earth'); // => ['welcome', 'to', 'Earth']
slugify('caffé latté');    // => 'caffe-latte'

ES2015 modules

Voca is compatible with ES2015 modules to import the entire library:
import voca from 'voca';
voca.kebabCase('goodbye blue sky'); // => 'goodbye-blue-sky'
Or import individual functions:
import last from 'voca/last';
last('sun rises', 5); // => 'rises'

Browser

Load the UMD builds directly into browser's web page:
<script src="voca.js" type="text/javascript"></script>
Then a global variable v is exposed:
<script type="text/javascript">
   v.last('wonderful world', 5); // => 'world'
</script>

See also

Author

Dmitri Pavlutin Profile Image
Dmitri Pavlutin
@panzerdp
dmitri@rainsoft.io

License

Licensed under MIT

Case

v.camelCase(subjectopt='') → {string}

Converts the subject to camel case.

Parameters:
subject {string}

The string to convert to camel case.

[optional='']
Returns:
{string}

The camel case string.

Availability:
1.0.0
Example:
v.camelCase('bird flight');
// => 'birdFlight'

v.camelCase('BirdFlight');
// => 'birdFlight'

v.camelCase('-BIRD-FLIGHT-');
// => 'birdFlight'

v.capitalize(subjectopt='', restToLoweropt=false) → {string}

Converts the first character of subject to upper case. If restToLower is true, convert the rest of subject to lower case.

Parameters:
subject {string}

The string to capitalize.

[optional='']
restToLower {boolean}

Convert the rest of subject to lower case.

[optional=false]
Returns:
{string}

Returns the capitalized string.

Availability:
1.0.0
Example:
v.capitalize('apple');
// => 'Apple'

v.capitalize('aPPle', true);
// => 'Apple'

v.decapitalize(subjectopt='') → {string}

Converts the first character of subject to lower case.

Parameters:
subject {string}

The string to decapitalize.

[optional='']
Returns:
{string}

Returns the decapitalized string.

Availability:
1.0.0
Example:
v.decapitalize('Sun');
// => 'sun'

v.decapitalize('moon');
// => 'moon'

v.kebabCase(subjectopt='') → {string}

Converts the subject to kebab case, also called spinal case or lisp case.

Parameters:
subject {string}

The string to convert to kebab case.

[optional='']
Returns:
{string}

Returns the kebab case string.

Availability:
1.0.0
Example:
v.kebabCase('goodbye blue sky');
// => 'goodbye-blue-sky'

v.kebabCase('GoodbyeBlueSky');
// => 'goodbye-blue-sky'

v.kebabCase('-Goodbye-Blue-Sky-');
// => 'goodbye-blue-sky'

v.lowerCase(subjectopt='') → {string}

Converts the subject to lower case.

Parameters:
subject {string}

The string to convert to lower case.

[optional='']
Returns:
{string}

Returns the lower case string.

Availability:
1.0.0
Example:
v.lowerCase('Green');
// => 'green'

v.lowerCase('BLUE');
// => 'blue'

v.snakeCase(subjectopt='') → {string}

Converts the subject to snake case.

Parameters:
subject {string}

The string to convert to snake case.

[optional='']
Returns:
{string}

Returns the snake case string.

Availability:
1.0.0
Example:
v.snakeCase('learning to fly');
// => 'learning_to_fly'

v.snakeCase('LearningToFly');
// => 'learning_to_fly'

v.snakeCase('-Learning-To-Fly-');
// => 'learning_to_fly'

v.swapCase(subjectopt='') → {string}

Converts the uppercase alpha characters of subject to lowercase and lowercase characters to uppercase.

Parameters:
subject {string}

The string to swap the case.

[optional='']
Returns:
{string}

Returns the converted string.

Availability:
1.3.0
Example:
v.swapCase('League of Shadows');
// => 'lEAGUE OF sHADOWS'

v.swapCase('2 Bees');
// => '2 bEES'

v.titleCase(subjectopt='', noSplitopt) → {string}

Converts the subject to title case.

Parameters:
subject {string}

The string to convert to title case.

[optional='']
noSplit {Array}

Do not split words at the specified characters.

[optional]
Returns:
{string}

Returns the title case string.

Availability:
1.4.0
Example:
v.titleCase('learning to fly');
// => 'Learning To Fly'

v.titleCase('jean-luc is good-looking', ['-']);
// => 'Jean-luc Is Good-looking'

v.upperCase(subjectopt='') → {string}

Converts the subject to upper case.

Parameters:
subject {string}

The string to convert to upper case.

[optional='']
Returns:
{string}

Returns the upper case string.

Availability:
1.0.0
Example:
v.upperCase('school');
// => 'SCHOOL'

Chain

v(subject) → {Object}

Creates a chain object that wraps subject, enabling implicit chain sequences.
A function that returns number, boolean or array type terminates the chain sequence and returns the unwrapped value. Otherwise use v.prototype.value() to unwrap the result.

Parameters:
subject {string}

The string to wrap.

Returns:
{Object}

Returns the new wrapper object.

Availability:
1.0.0
Example:
v('Back to School')
 .lowerCase()
 .words()
// => ['back', 'to', 'school']

v(" Back to School ")
 .trim()
 .truncate(7)
 .value()
// => 'Back...'

v.chain(subject) → {Object}

Creates a chain object that wraps subject, enabling explicit chain sequences.
Use v.prototype.value() to unwrap the result.

Parameters:
subject {string}

The string to wrap.

Returns:
{Object}

Returns the new wrapper object.

Availability:
1.0.0
Example:
v
 .chain('Back to School')
 .lowerCase()
 .words()
 .value()
// => ['back', 'to', 'school']

v.prototype.chain() → {Object}

Creates a new chain object that enables explicit chain sequences. Use v.prototype.value() to unwrap the result.
Does not modify the wrapped value.

Returns:
{Object}

Returns the wrapper in explicit mode.

Availability:
1.0.0
Example:
v('Back to School')
 .chain()
 .lowerCase()
 .words()
 .value()
// => ['back', 'to', 'school']

v(" Back to School ")
 .chain()
 .trim()
 .truncate(7)
 .value()
// => 'Back...'

v.prototype.thru(changer) → {Object}

Modifies the wrapped value with the invocation result of changer function. The current wrapped value is the argument of changer invocation.

Parameters:
changer {function}

The function to invoke.

Returns:
{Object}

Returns the new wrapper that wraps the invocation result of changer.

Availability:
1.0.0
Example:
v
 .chain('sun is shining')
 .words()
 .thru(function(words) {
   return words[0];
 })
 .value()
// => 'sun'

v.prototype.value() → {*}

Unwraps the chain sequence wrapped value.

Returns:
{*}

Returns the unwrapped value.

Availability:
1.0.0
Example:
v
 .chain('Hello world')
 .replace('Hello', 'Hi')
 .lowerCase()
 .slugify()
 .value()
// => 'hi-world'

v(' Space travel ')
 .trim()
 .truncate(8)
 .value()
// => 'Space...'

Chop

v.charAt(subjectopt='', position) → {string}

Access a character from subject at specified position.

Parameters:
subject {string}

The string to extract from.

[optional='']
position {numbers}

The position to get the character.

Returns:
{string}

Returns the character at specified position.

Availability:
1.0.0
Example:
v.charAt('helicopter', 0);
// => 'h'

v.charAt('helicopter', 1);
// => 'e'

v.codePointAt(subjectopt='', position) → {number}

Get the Unicode code point value of the character at position.
If a valid UTF-16 surrogate pair starts at position, the astral code point value at position is returned.

Parameters:
subject {string}

The string to extract from.

[optional='']
position {number}

The position to get the code point number.

Returns:
{number}

Returns a non-negative number less than or equal to 0x10FFFF.

Availability:
1.0.0
Example:
v.codePointAt('rain', 1);
// => 97, or 0x0061

v.codePointAt('\uD83D\uDE00 is smile', 0); // or '😀 is smile'
// => 128512, or 0x1F600

v.first(subjectopt='', lengthopt=1) → {string}

Extracts the first length characters from subject.

Parameters:
subject {string}

The string to extract from.

[optional='']
length {int}

The number of characters to extract.

[optional=1]
Returns:
{string}

Returns the first characters string.

Availability:
1.0.0
Example:
v.first('helicopter');
// => 'h'

v.first('vehicle', 2);
// => 've'

v.first('car', 5);
// => 'car'

v.graphemeAt(subjectopt='', position) → {string}

Get a grapheme from subject at specified position taking care of surrogate pairs and combining marks.

Parameters:
subject {string}

The string to extract from.

[optional='']
position {number}

The position to get the grapheme.

Returns:
{string}

Returns the grapheme at specified position.

Availability:
1.0.0
Example:
v.graphemeAt('\uD835\uDC00\uD835\uDC01', 0); // or '𝐀𝐁'
// => 'A'

v.graphemeAt('cafe\u0301', 3); // or 'café'
// => 'é'

v.last(subjectopt='', lengthopt=1) → {string}

Extracts the last length characters from subject.

Parameters:
subject {string}

The string to extract from.

[optional='']
length {int}

The number of characters to extract.

[optional=1]
Returns:
{string}

Returns the last characters string.

Availability:
1.0.0
Example:
v.last('helicopter');
// => 'r'

v.last('vehicle', 2);
// => 'le'

v.last('car', 5);
// => 'car'

v.prune(subjectopt='', length, endopt='...') → {string}

Truncates subject to a new length and does not break the words. Guarantees that the truncated string is no longer than length.

Parameters:
subject {string}

The string to prune.

[optional='']
length {int}

The length to prune the string.

end {string}

The string to be added at the end.

[optional='...']
Returns:
{string}

Returns the pruned string.

Availability:
1.0.0
Example:
v.prune('Once upon a time', 7);
// => 'Once...'

v.prune('Good day, Little Red Riding Hood', 16, ' (more)');
// => 'Good day (more)'

v.prune('Once upon', 10);
// => 'Once upon'

v.slice(subjectopt='', start, endopt=subject.length) → {string}

Extracts from subject a string from start position up to end position. The character at end position is not included.

Parameters:
subject {string}

The string to extract from.

[optional='']
start {number}

The position to start extraction. If negative use subject.length + start.

end {number}

The position to end extraction. If negative use subject.length + end.

[optional=subject.length]
Returns:
{string}

Returns the extracted string.

Availability:
1.0.0
Example:
v.slice('miami', 1);
// => 'iami'

v.slice('florida', -4);
// => 'rida'

v.slice('florida', 1, 4);
// => "lor"

v.substr(subjectopt='', start, lengthopt=subject.endOfString) → {string}

Extracts from subject a string from start position a number of length characters.

Parameters:
subject {string}

The string to extract from.

[optional='']
start {number}

The position to start extraction.

length {number}

The number of characters to extract. If omitted, extract to the end of subject.

[optional=subject.endOfString]
Returns:
{string}

Returns the extracted string.

Availability:
1.0.0
Example:
v.substr('infinite loop', 9);
// => 'loop'

v.substr('dreams', 2, 2);
// => 'ea'

v.substring(subjectopt='', start, endopt=subject.length) → {string}

Extracts from subject a string from start position up to end position. The character at end position is not included.

Parameters:
subject {string}

The string to extract from.

[optional='']
start {number}

The position to start extraction.

end {number}

The position to end extraction.

[optional=subject.length]
Returns:
{string}

Returns the extracted string.

Availability:
1.0.0
Example:
v.substring('beach', 1);
// => 'each'

v.substring('ocean', 1, 3);
// => 'ea'

v.truncate(subjectopt='', length, endopt='...') → {string}

Truncates subject to a new length.

Parameters:
subject {string}

The string to truncate.

[optional='']
length {int}

The length to truncate the string.

end {string}

The string to be added at the end.

[optional='...']
Returns:
{string}

Returns the truncated string.

Availability:
1.0.0
Example:
v.truncate('Once upon a time', 7);
// => 'Once...'

v.truncate('Good day, Little Red Riding Hood', 14, ' (...)');
// => 'Good day (...)'

v.truncate('Once upon', 10);
// => 'Once upon'

Count

v.count(subjectopt='') → {number}

Counts the characters in subject.

Parameters:
subject {string}

The string to count characters.

[optional='']
Returns:
{number}

Returns the number of characters in subject.

Availability:
1.0.0
Example:
v.count('rain');
// => 4

v.countGraphemes(subjectopt='') → {number}

Counts the graphemes in subject taking care of surrogate pairs and combining marks.

Parameters:
subject {string}

The string to count graphemes.

[optional='']
Returns:
{number}

Returns the number of graphemes in subject.

Availability:
1.0.0
Example:
v.countGraphemes('cafe\u0301'); // or 'café'
// => 4

v.countGraphemes('\uD835\uDC00\uD835\uDC01'); // or '𝐀𝐁'
// => 2

v.countGraphemes('rain');
// => 4

v.countSubstrings(subjectopt='', substring) → {number}

Counts the number of substring appearances in subject.

Parameters:
subject {string}

The string where to count.

[optional='']
substring {string}

The substring to be counted.

Returns:
{number}

Returns the number of substring appearances.

Availability:
1.0.0
Example:
v.countSubstrings('bad boys, bad boys whatcha gonna do?', 'boys');
// => 2

v.countSubstrings('every dog has its day', 'cat');
// => 0

v.countWhere(subjectopt='', predicate, contextopt) → {number}

Counts the characters in subject for which predicate returns truthy.

Parameters:
subject {string}

The string to count characters.

[optional='']
predicate {function}

The predicate function invoked on each character with parameters (character, index, string).

context {Object}

The context to invoke the predicate.

[optional]
Returns:
{number}

Returns the number of characters for which predicate returns truthy.

Availability:
1.0.0
Example:
v.countWhere('hola!', v.isAlpha);
// => 4

v.countWhere('2022', function(character, index, str) {
  return character === '2';
});
// => 3

v.countWords(subjectopt='', patternopt, flagsopt='') → {number}

Counts the number of words in subject.

Parameters:
subject {string}

The string to split into words.

[optional='']
pattern {string|RegExp}

The pattern to watch words. If pattern is not RegExp, it is transformed to new RegExp(pattern, flags).

[optional]
flags {string}

The regular expression flags. Applies when pattern is string type.

[optional='']
Returns:
{number}

Returns the number of words.

Availability:
1.0.0
Example:
v.countWords('gravity can cross dimensions');
// => 4

v.countWords('GravityCanCrossDimensions');
// => 4

v.countWords('Gravity - can cross dimensions!');
// => 4

v.words('Earth gravity', /[^\s]+/g);
// => 2

Escape

v.escapeHtml(subjectopt='') → {string}

Escapes HTML special characters < > & ' " ` in subject.

Parameters:
subject {string}

The string to escape.

[optional='']
Returns:
{string}

Returns the escaped string.

Availability:
1.0.0
Example:
v.escapeHtml('<p>wonderful world</p>');
// => '&lt;p&gt;wonderful world&lt;/p&gt;'

v.escapeRegExp(subjectopt='') → {string}

Escapes the regular expression special characters - [ ] / { } ( ) * + ? . \ ^ $ | in subject.

Parameters:
subject {string}

The string to escape.

[optional='']
Returns:
{string}

Returns the escaped string.

Availability:
1.0.0
Example:
v.escapeRegExp('(hours)[minutes]{seconds}');
// => '\(hours\)\[minutes\]\{seconds\}'

v.unescapeHtml(subjectopt='') → {string}

Unescapes HTML special characters from &lt; &gt; &amp; &quot; &#x27; &#x60; to corresponding < > & ' " ` in subject.

Parameters:
subject {string}

The string to unescape.

[optional='']
Returns:
{string}

Returns the unescaped string.

Availability:
1.0.0
Example:
v.unescapeHtml('&lt;p&gt;wonderful world&lt;/p&gt;');
// => '<p>wonderful world</p>'

Format

v.sprintf(formatopt='', …replacements) → {string}

Produces a string according to format.

`format` string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output string and conversion specifications, each of which results in fetching zero or more subsequent arguments.

Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width and an optional precision.
The syntax is: ConversionSpecification = "%" { Flags } [ MinimumFieldWidth ] [ Precision ] ConversionSpecifier, where curly braces { } denote repetition and square brackets [ ] optionality.

By default, the arguments are used in the given order.
For argument numbering and swapping, %m$ (where m is a number indicating the argument order) is used instead of % to specify explicitly which argument is taken. For instance %1$s fetches the 1st argument, %2$s the 2nd and so on, no matter what position the conversion specification has in format.

The flags
The character % is followed by zero or more of the following flags:

+ A sign (+ or -) should always be placed before a number produced by a signed conversion. By default a sign is used only for negative numbers.
0 The value should be zero padded.
(a space) The value should be space padded.
' Indicates alternate padding character, specified by prefixing it with a single quote '.
- The converted value is to be left adjusted on the field boundary (the default is right justification).

The minimum field width
An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given).

The precision
An optional precision, in the form of a period . followed by an optional decimal digit string.
This gives the number of digits to appear after the radix character for e, E, f and F conversions, the maximum number of significant digits for g and G conversions or the maximum number of characters to be printed from a string for s conversion.

The conversion specifier
A specifier that mentions what type the argument should be treated as:

`s` The string argument is treated as and presented as a string.
`d` `i` The integer argument is converted to signed decimal notation.
`b` The unsigned integer argument is converted to unsigned binary.
`c` The unsigned integer argument is converted to an ASCII character with that number.
`o` The unsigned integer argument is converted to unsigned octal.
`u` The unsigned integer argument is converted to unsigned decimal.
`x` `X` The unsigned integer argument is converted to unsigned hexadecimal. The letters `abcdef` are used for `x` conversions; the letters `ABCDEF` are used for `X` conversions.
`f` The float argument is rounded and converted to decimal notation in the style `[-]ddd.ddd`, where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.
`e` `E` The float argument is rounded and converted in the style `[-]d.ddde±dd`, where there is one digit before the decimal-point character and the number of digits after it is equal to the precision. If the precision is missing, it is taken as `6`; if the precision is zero, no decimal-point character appears. An `E` conversion uses the letter `E` (rather than `e`) to introduce the exponent.
`g` `G` The float argument is converted in style `f` or `e` (or `F` or `E` for `G` conversions). The precision specifies the number of significant digits. If the precision is missing, `6` digits are given; if the precision is zero, it is treated as `1`. Style `e` is used if the exponent from its conversion is less than `-6` or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.
`%` A literal `%` is written. No argument is converted. The complete conversion specification is `%%`.
Parameters:
format {string}

The format string.

[optional='']
replacements {*}

The replacements to produce the string.

Returns:
{string}

Returns the produced string.

Availability:
1.0.0
Example:
v.sprintf('%s, %s!', 'Hello', 'World');
// => 'Hello World!'

v.sprintf('%s costs $%d', 'coffee', 2);
// => 'coffee costs $2'

v.sprintf('%1$s %2$s %1$s %2$s, watcha gonna %3$s', 'bad', 'boys', 'do')
// => 'bad boys bad boys, watcha gonna do'

v.sprintf('% 6s', 'bird');
// => '  bird'

v.sprintf('% -6s', 'crab');
// => 'crab  '

v.sprintf("%'*5s", 'cat');
// => '**cat'

v.sprintf("%'*-6s", 'duck');
// => 'duck**'

v.sprintf('%d %i %+d', 15, -2, 25);
// => '15 -2 +25'

v.sprintf("%06d", 15);
// => '000015'

v.sprintf('0b%b 0o%o 0x%X', 12, 9, 155);
// => '0b1100 0o11 0x9B'

v.sprintf('%.2f', 10.469);
// => '10.47'

v.sprintf('%.2e %g', 100.5, 0.455);
// => '1.01e+2 0.455'

v.vprintf(format, replacements) → {string}

Produces a string according to format. Works exactly like sprintf(), with the only difference that accepts the formatting arguments in an array values.
See here format string specifications.

Parameters:
format {string}

The format string.

replacements {Array}

The array of replacements to produce the string.

Returns:
{string}

Returns the produced string.

Availability:
1.0.0
Example:
v.vprintf('%s', ['Welcome'])
// => 'Welcome'

v.vprintf('%s has %d apples', ['Alexandra', 3]);
// => 'Alexandra has 3 apples'

Index

v.indexOf(subjectopt='', search, fromIndexopt=0) → {number}

Returns the first occurrence index of search in subject.

Parameters:
subject {string}

The string where to search.

[optional='']
search {string}

The string to search.

fromIndex {number}

The index to start searching.

[optional=0]
Returns:
{number}

Returns the first occurrence index or -1 if not found.

Availability:
1.0.0
Example:
v.indexOf('morning', 'n');
// => 3

v.indexOf('evening', 'o');
// => -1

v.lastIndexOf(subjectopt='', search, fromIndexopt=subject.length - 1) → {number}

Returns the last occurrence index of search in subject.

Parameters:
subject {string}

The string where to search.

[optional='']
search {string}

The string to search.

fromIndex {number}

The index to start searching backward in the string.

[optional=subject.length - 1]
Returns:
{number}

Returns the last occurrence index or -1 if not found.

Availability:
1.0.0
Example:
v.lastIndexOf('morning', 'n');
// => 5

v.lastIndexOf('evening', 'o');
// => -1

Manipulate

v.insert(subjectopt='', toInsertopt='', positionopt=0) → {string}

Inserts into subject a string toInsert at specified position.

Parameters:
subject {string}

The string where to insert.

[optional='']
toInsert {string}

The string to be inserted.

[optional='']
position {number}

The position to insert.

[optional=0]
Returns:
{string}

Returns the string after insertion.

Availability:
1.0.0
Example:
v.insert('ct', 'a', 1);
// => 'cat'

v.insert('sunny', ' day', 5);
// => 'sunny day'

v.latinise(subjectopt='') → {string}

Latinises the subject by removing diacritic characters.

Parameters:
subject {string}

The string to latinise.

[optional='']
Returns:
{string}

Returns the latinised string.

Availability:
1.0.0
Example:
v.latinise('cafe\u0301'); // or 'café'
// => 'cafe'

v.latinise('août décembre');
// => 'aout decembre'

v.latinise('как прекрасен этот мир');
// => 'kak prekrasen etot mir'

v.pad(subjectopt='', lengthopt=0, padopt=' ') → {string}

Pads subject to a new length.

Parameters:
subject {string}

The string to pad.

[optional='']
length {int}

The length to pad the string. No changes are made if length is less than subject.length.

[optional=0]
pad {string}

The string to be used for padding.

[optional=' ']
Returns:
{string}

Returns the padded string.

Availability:
1.0.0
Example:
v.pad('dog', 5);
// => ' dog '

v.pad('bird', 6, '-');
// => '-bird-'

v.pad('cat', 6, '-=');
// => '-cat-='

v.padLeft(subjectopt='', lengthopt=0, padopt=' ') → {string}

Pads subject from left to a new length.

Parameters:
subject {string}

The string to pad.

[optional='']
length {int}

The length to left pad the string. No changes are made if length is less than subject.length.

[optional=0]
pad {string}

The string to be used for padding.

[optional=' ']
Returns:
{string}

Returns the left padded string.

Availability:
1.0.0
Example:
v.padLeft('dog', 5);
// => '  dog'

v.padLeft('bird', 6, '-');
// => '--bird'

v.padLeft('cat', 6, '-=');
// => '-=-cat'

v.padRight(subjectopt='', lengthopt=0, padopt=' ') → {string}

Pads subject from right to a new length.

Parameters:
subject {string}

The string to pad.

[optional='']
length {int}

The length to right pad the string. No changes are made if length is less than subject.length.

[optional=0]
pad {string}

The string to be used for padding.

[optional=' ']
Returns:
{string}

Returns the right padded string.

Availability:
1.0.0
Example:
v.padRight('dog', 5);
// => 'dog  '

v.padRight('bird', 6, '-');
// => 'bird--'

v.padRight('cat', 6, '-=');
// => 'cat-=-'

v.repeat(subjectopt='', timesopt=1) → {string}

Repeats the subject number of times.

Parameters:
subject {string}

The string to repeat.

[optional='']
times {number}

The number of times to repeat.

[optional=1]
Returns:
{string}

Returns the repeated string.

Availability:
1.0.0
Example:
v.repeat('w', 3);
// => 'www'

v.repeat('world', 0);
// => ''

v.replace(subjectopt='', search, replace) → {string}

Replaces the matches of search with replace.

Parameters:
subject {string}

The string to verify.

[optional='']
search {string|RegExp}

The search pattern to replace. If search is a string, a simple string match is evaluated and only the first occurrence replaced.

replace {string|function}

The string or function which invocation result replaces search match.

Returns:
{string}

Returns the replacement result.

Availability:
1.0.0
Example:
v.replace('swan', 'wa', 'u');
// => 'sun'

v.replace('domestic duck', /domestic\s/, '');
// => 'duck'

v.replace('nice duck', /(nice)(duck)/, function(match, nice, duck) {
  return 'the ' + duck + ' is ' + nice;
});
// => 'the duck is nice'

v.replaceAll(subjectopt='', search, replace) → {string}

Replaces all occurrences of search with replace.

Parameters:
subject {string}

The string to verify.

[optional='']
search {string|RegExp}

The search pattern to replace. If search is a string, a simple string match is evaluated. All matches are replaced.

replace {string|function}

The string or function which invocation result replaces all search matches.

Returns:
{string}

Returns the replacement result.

Availability:
1.0.0
Example:
v.replaceAll('good morning', 'o', '*');
// => 'g**d m*rning'
v.replaceAll('evening', /n/g, 's');
// => 'evesisg'

v.reverse(subjectopt='') → {string}

Reverses the subject.

Parameters:
subject {string}

The string to reverse.

[optional='']
Returns:
{string}

Returns the reversed string.

Availability:
1.0.0
Example:
v.reverse('winter');
// => 'retniw'

v.reverseGrapheme(subjectopt='') → {string}

Reverses the subject taking care of surrogate pairs and combining marks.

Parameters:
subject {string}

The string to reverse.

[optional='']
Returns:
{string}

Returns the reversed string.

Availability:
1.0.0
Example:
v.reverseGrapheme('summer');
// => 'remmus'

v.reverseGrapheme('𝌆 bar mañana mañana');
// => 'anañam anañam rab 𝌆'

v.slugify(subjectopt='') → {string}

Slugifies the subject. Cleans the subject by replacing diacritics with corresponding latin characters.

Parameters:
subject {string}

The string to slugify.

[optional='']
Returns:
{string}

Returns the slugified string.

Availability:
1.0.0
Example:
v.slugify('Italian cappuccino drink');
// => 'italian-cappuccino-drink'

v.slugify('caffé latté');
// => 'caffe-latte'

v.slugify('хорошая погода');
// => 'horoshaya-pogoda'

v.splice(subjectopt='', start, deleteCountopt=subject.length-start, toAddopt='') → {string}

Changes subject by deleting deleteCount of characters starting at position start. Places a new string toAdd instead of deleted characters.

Parameters:
subject {string}

The string where to insert.

[optional='']
start {string}

The position to start changing the string. For a negative position will start from the end of the string.

deleteCount {number}

The number of characters to delete from string.

[optional=subject.length-start]
toAdd {string}

The string to be added instead of deleted characters.

[optional='']
Returns:
{string}

Returns the modified string.

Availability:
1.0.0
Example:
v.splice('new year', 0, 4);
// => 'year'

v.splice('new year', 0, 3, 'happy');
// => 'happy year'

v.splice('new year', -4, 4, 'day');
// => 'new day'

v.tr(subjectopt='', from, to) → {string}

Translates characters or replaces substrings in subject.

Parameters:
subject {string}

The string to translate.

[optional='']
from {string|Object}

The string of characters to translate from. Or an object, then the object keys are replaced with corresponding values (longest keys are tried first).

to {string}

The string of characters to translate to. Ignored when from is an object.

Returns:
{string}

Returns the translated string.

Availability:
1.3.0
Example:
v.tr('hello', 'el', 'ip');
// => 'hippo'

v.tr('légèreté', 'éè', 'ee');
// => 'legerete'

v.tr('Yes. The fire rises.', {
  'Yes': 'Awesome',
  'fire': 'flame'
})
// => 'Awesome. The flame rises.'

v.tr(':where is the birthplace of :what', {
  ':where': 'Africa',
  ':what': 'Humanity'
});
// => 'Africa is the birthplace of Humanity'

v.trim(subjectopt='', whitespaceopt=whitespace) → {string}

Removes whitespaces from left and right sides of the subject.

Parameters:
subject {string}

The string to trim.

[optional='']
whitespace {string}

The whitespace characters to trim. List all characters that you want to be stripped.

[optional=whitespace]
Returns:
{string}

Returns the trimmed string.

Availability:
1.0.0
Example:
v.trim(' Mother nature ');
// => 'Mother nature'

v.trim('--Earth--', '-');
// => 'Earth'

v.trimLeft(subjectopt='', whitespaceopt=whitespace) → {string}

Removes whitespaces from the left side of the subject.

Parameters:
subject {string}

The string to trim.

[optional='']
whitespace {string}

The whitespace characters to trim. List all characters that you want to be stripped.

[optional=whitespace]
Returns:
{string}

Returns the trimmed string.

Availability:
1.0.0
Example:
v.trimLeft('  Starship Troopers');
// => 'Starship Troopers'

v.trimLeft('***Mobile Infantry', '*');
// => 'Mobile Infantry'

v.trimRight(subjectopt='', whitespaceopt=whitespace) → {string}

Removes whitespaces from the right side of the subject.

Parameters:
subject {string}

The string to trim.

[optional='']
whitespace {string}

The whitespace characters to trim. List all characters that you want to be stripped.

[optional=whitespace]
Returns:
{string}

Returns the trimmed string.

Availability:
1.0.0
Example:
v.trimRight('the fire rises   ');
// => 'the fire rises'

v.trimRight('do you feel in charge?!!!', '!');
// => 'do you feel in charge?'

v.wordWrap(subjectopt='', optionsopt={}) → {string}

Wraps subject to a given number of characters using a string break character.

Parameters:
subject {string}

The string to wrap.

[optional='']
options {Object}

The wrap options.

[optional={}]
Properties:
width {number}

The number of characters at which to wrap.

[optional=75]
newLine {string}

The string to add at the end of line.

[optional='\n']
indent {string}

The string to intend the line.

[optional='']
cut {boolean}

When false (default) does not split the word even if word length is bigger than width.
When true breaks the word that has length bigger than width.

[optional=false]
Returns:
{string}

Returns wrapped string.

Availability:
1.0.0
Example:
v.wordWrap('Hello world', {
  width: 5
});
// => 'Hello\nworld'

v.wordWrap('Hello world', {
  width: 5,
  newLine: '<br/>',
  indent: '__'
});
// => '__Hello<br/>__world'

v.wordWrap('Wonderful world', {
  width: 5,
  cut: true
});
// => 'Wonde\nrful\nworld'

Query

v.endsWith(subjectopt='', end, positionopt=subject.length) → {boolean}

Checks whether subject ends with end.

Parameters:
subject {string}

The string to verify.

[optional='']
end {string}

The ending string.

position {number}

Search within subject as if the string were only position long.

[optional=subject.length]
Returns:
{boolean}

Returns true if subject ends with end or false otherwise.

Availability:
1.0.0
Example:
v.endsWith('red alert', 'alert');
// => true

v.endsWith('metro south', 'metro');
// => false

v.endsWith('Murphy', 'ph', 5);
// => true

v.includes(subjectopt='', search, positionopt=0) → {boolean}

Checks whether subject includes search starting from position.

Parameters:
subject {string}

The string where to search.

[optional='']
search {string}

The string to search.

position {number}

The position to start searching.

[optional=0]
Returns:
{boolean}

Returns true if subject includes search or false otherwise.

Availability:
1.0.0
Example:
v.includes('starship', 'star');
// => true

v.includes('galaxy', 'g', 1);
// => false

v.isAlpha(subjectopt='') → {boolean}

Checks whether subject contains only alpha characters.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject contains only alpha characters or false otherwise.

Availability:
1.0.0
Example:
v.isAlpha('bart');
// => true

v.isAlpha('lisa!');
// => false

v.isAlpha('lisa and bart');
// => false

v.isAlphaDigit(subjectopt='') → {boolean}

Checks whether subject contains only alpha and digit characters.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject contains only alpha and digit characters or false otherwise.

Availability:
1.0.0
Example:
v.isAlphaDigit('year2020');
// => true

v.isAlphaDigit('1448');
// => true

v.isAlphaDigit('40-20');
// => false

v.isBlank(subjectopt='') → {boolean}

Checks whether subject is empty or contains only whitespaces.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject is empty or contains only whitespaces or false otherwise.

Availability:
1.0.0
Example:
v.isBlank('');
// => true

v.isBlank('  ');
// => true

v.isBlank('World');
// => false

v.isDigit(subjectopt='') → {boolean}

Checks whether subject contains only digit characters.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject contains only digit characters or false otherwise.

Availability:
1.0.0
Example:
v.isDigit('35');
// => true

v.isDigit('1.5');
// => false

v.isDigit('ten');
// => false

v.isEmpty(subjectopt='') → {boolean}

Checks whether subject is empty.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject is empty or false otherwise

Availability:
1.0.0
Example:
v.isEmpty('');
// => true

v.isEmpty('  ');
// => false

v.isEmpty('sun');
// => false

v.isLowerCase(subjectopt='') → {boolean}

Checks whether subject has only lower case characters.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject is lower case or false otherwise.

Availability:
1.0.0
Example:
v.isLowerCase('motorcycle');
// => true

v.isLowerCase('John');
// => false

v.isLowerCase('T1000');
// => false

v.isNumeric(subjectopt='') → {boolean}

Checks whether subject is numeric.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject is numeric or false otherwise.

Availability:
1.0.0
Example:
v.isNumeric('350');
// => true

v.isNumeric('-20.5');
// => true

v.isNumeric('1.5E+2');
// => true

v.isNumeric('five');
// => false

v.isString(subject) → {boolean}

Checks whether subject is a string primitive type.

Parameters:
subject {string}

The value to verify.

Returns:
{boolean}

Returns true if subject is string primitive type or false otherwise.

Availability:
1.0.0
Example:
v.isString('vacation');
// => true

v.isString(560);
// => false

v.isUpperCase(subjectopt='') → {boolean}

Checks whether subject contains only upper case characters.

Parameters:
subject {string}

The string to verify.

[optional='']
Returns:
{boolean}

Returns true if subject is upper case or false otherwise.

Availability:
1.0.0
Example:
v.isUpperCase('ACDC');
// => true

v.isUpperCase('Morning');
// => false

v.matches(subjectopt='', pattern, flagsopt='') → {boolean}

Checks whether subject matches the regular expression pattern.

Parameters:
subject {string}

The string to verify.

[optional='']
pattern {RegExp|string}

The pattern to match. If pattern is not RegExp, it is transformed to new RegExp(pattern, flags).

flags {string}

The regular expression flags. Applies when pattern is string type.

[optional='']
Returns:
{boolean}

Returns true if subject matches pattern or false otherwise.

Availability:
1.0.0
Example:
v.matches('pluto', /plu.{2}/);
// => true

v.matches('sun', 'S', 'i');
// => true

v.matches('apollo 11', '\\d{3}');
// => false

v.startsWith(subjectopt='', start, positionopt=0) → {boolean}

Checks whether subject starts with start.

Parameters:
subject {string}

The string to verify.

[optional='']
start {string}

The starting string.

position {number}

The position to start searching.

[optional=0]
Returns:
{boolean}

Returns true if subject starts with start or false otherwise.

Availability:
1.0.0
Example:
v.startsWith('say hello to my little friend', 'say hello');
// => true

v.startsWith('tony', 'on', 1);
// => true

v.startsWith('the world is yours', 'world');
// => false

Split

v.chars(subjectopt='') → {Array}

Splits subject into an array of characters.

Parameters:
subject {string}

The string to split into characters.

[optional='']
Returns:
{Array}

Returns the array of characters.

Availability:
1.0.0
Example:
v.chars('cloud');
// => ['c', 'l', 'o', 'u', 'd']

v.codePoints(subjectopt='') → {Array}

Returns an array of Unicode code point values from characters of subject.

Parameters:
subject {string}

The string to extract from.

[optional='']
Returns:
{Array}

Returns an array of non-negative numbers less than or equal to 0x10FFFF.

Availability:
1.0.0
Example:
v.codePoints('rain');
// => [114, 97, 105, 110], or
//    [0x72, 0x61, 0x69, 0x6E]

v.codePoints('\uD83D\uDE00 smile'); // or '😀 smile'
// => [128512, 32, 115, 109, 105, 108, 101], or
//    [0x1F600, 0x20, 0x73, 0x6D, 0x69, 0x6C, 0x65]

v.graphemes(subjectopt='') → {Array}

Splits subject into an array of graphemes taking care of surrogate pairs and combining marks.

Parameters:
subject {string}

The string to split into characters.

[optional='']
Returns:
{Array}

Returns the array of graphemes.

Availability:
1.0.0
Example:
v.graphemes('\uD835\uDC00\uD835\uDC01'); // or '𝐀𝐁'
// => ['\uD835\uDC00', '\uD835\uDC01'], or
//    ['𝐀', '𝐁']

v.graphemes('cafe\u0301'); // or 'café'
// => ['c', 'a', 'f', 'e\u0301'], or
//    ['c', 'a', 'f', 'é']

v.split(subjectopt='', separatoropt, limitopt) → {Array}

Splits subject into an array of chunks by separator.

Parameters:
subject {string}

The string to split into characters.

[optional='']
separator {string|RegExp}

The pattern to match the separator.

[optional]
limit {number}

Limit the number of chunks to be found.

[optional]
Returns:
{Array}

Returns the array of chunks.

Availability:
1.0.0
Example:
v.split('rage against the dying of the light', ' ');
// => ['rage', 'against', 'the', 'dying', 'of', 'the', 'light']

v.split('the dying of the light', /\s/, 3);
// => ['the', 'dying', 'of']

v.words(subjectopt='', patternopt, flagsopt='') → {Array}

Splits subject into an array of words.

Parameters:
subject {string}

The string to split into words.

[optional='']
pattern {string|RegExp}

The pattern to watch words. If pattern is not RegExp, it is transformed to new RegExp(pattern, flags).

[optional]
flags {string}

The regular expression flags. Applies when pattern is string type.

[optional='']
Returns:
{Array}

Returns the array of words.

Availability:
1.0.0
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']

Strip

v.stripBom(subjectopt='') → {string}

Strips the byte order mark (BOM) from the beginning of subject.

Parameters:
subject {string}

The string to strip from.

[optional='']
Returns:
{string}

Returns the stripped string.

Availability:
1.2.0
Example:
v.stripBom('\uFEFFsummertime sadness');
// => 'summertime sadness'

v.stripBom('summertime happiness');
// => 'summertime happiness'

v.stripTags(subjectopt='', allowableTagsopt, replacementopt='') → {string}

Strips HTML tags from subject.

Parameters:
subject {string}

The string to strip from.

[optional='']
allowableTags {string|Array}

The string '<tag1><tag2>' or array ['tag1', 'tag2'] of tags that should not be stripped.

[optional]
replacement {string}

The string to replace the stripped tag.

[optional='']
Returns:
{string}

Returns the stripped string.

Availability:
1.1.0
Example:
v.stripTags('<span><a href="#">Summer</a> is nice</span>');
// => 'Summer is nice'

v.stripTags('<span><i>Winter</i> is <b>cold</b></span>', ['b', 'i']);
// => '<i>Winter</i> is <b>cold</b>'

v.stripTags('Sun<br/>set', '', '-');
// => 'Sun-set'

Util

v.noConflict() → {Object}

Restores v variable to previous value and returns Voca library instance.

Returns:
{Object}

Returns Voca library instance.

Availability:
1.0.0
Example:
var voca = v.noConflict();
voca.isAlpha('Hello');
// => true

v.version

A property that contains the library semantic version number.

Type:
{string}
Availability:
1.0.0
Example
v.version
// => '1.4.0'