JavaScript String : Object

constructor primitive iterable

Strings contain text. They are represented as a sequence of characters. JavaScript strings are immutable.

Spec

String(value : Object) : String

Returns a string representation of value by calling value.toString().

Example:

console.log(String(true));

var x = {
  foo: 'bar',
  toString: function() {
    return this.foo;
  }
};

console.log(String(x));

Run

Results:

Spec

Constructors

new String(value : String) : Object

Creates a box for a string value.

Example:

var literal = 'string literal';
var boxed = new String('boxed string');
literal.foo = 'bar';
boxed.foo = 'bar';
console.log(literal.foo);
console.log(boxed.foo);

Run

Results:

Spec

Instance Properties

length : Number readonly

The length property is the number of characters in the string. It is 1 greater than the index of the last character.

Example:

console.log(''.length);
console.log('abc'.length);

Run

Results:

Spec

Instance Methods

charAt(pos : Number) : String

Returns a String of length 1 that contains the character at position pos. Another way to retrieve a character in a string is this[pos].

Example:

console.log('abc'.charAt(2));
console.log('abc'[2]);

Run

Results:

Spec

charCodeAt(pos : Number) : Number

Returns the unicode value of the character at position pos. Use String.fromCharCode() to generate a string from character code values.

Example:

console.log('abc'.charCodeAt(2));

Run

Results:

Spec

codePointAt(pos : Number) : Number

Returns the UTF-32 code point of starting at pos. If the UTF-16 value at pos does not start a surrogate pair, the returned value will be the UTF-16 value at pos. Use String.fromCodePoint() to generate a string from code points.

Example:

console.log('abc'.codePointAt(2));
console.log('😀🐱⚽️'.codePointAt(2).toString(16));

Run

Results:

Spec

concat(string0 : String, [string1 : String, [...]]) : String

Returns a new String formed by joining each of the string parameters.

Example:

var x = 'a';
console.log(x.concat('bc', 'd'));
console.log(x); // x is unchanged

Run

Results:

Spec

endsWith(searchString : String, [endIndex : Number]) : Boolean

Returns true if searchString is at the end of this. If endIndex is specified, the last character of searchString must be at endIndex - 1 in this.

Example:

var a = 'abcxyz';
console.log(a.endsWith('xyz'));
console.log(a.endsWith('xy', 5));

Run

Results:

Spec

includes(searchString : String, [startingIndex = 0 : Number]) : Boolean

Returns true if searchString is somewhere in this starting the search from startingIndex. If startingIndex is negative, this.length is added to it before starting the search.

Example:

var x = ['a', 'b', 'c', 'd'];
console.log(x.includes('b'));
console.log(x.includes('b', 2));
console.log(x.includes('a', -2));
console.log(x.includes('e'));

Run

Results:

ECMAScript 2016 Spec

indexOf(searchString : String, [startingIndex = 0 : Number]) : Number

Returns the first location of searchString in this starting the search from startingIndex. Returns -1 if searchString is not found.

Example:

var a = 'abcdbca';
console.log(a.indexOf('b'));
console.log(a.indexOf('bc', 2));

Run

Results:

Spec

lastIndexOf(searchString : String, [startingIndex : Number]) : Number

Returns the location of searchString in this starting the search from startingIndex by searching backwards through the string. If startingIndex is not specified, the search starts from the end of the string. Returns -1 if searchString is not found.

Example:

var a = 'abcdbca';
console.log(a.lastIndexOf('b'));
console.log(a.lastIndexOf('b', 3));
console.log(a.lastIndexOf('ef', 2));

Run

Results:

Spec

localeCompare(that : String, [locales : Array<String>, [options : Object]]) : Number

options : {

caseFirst	Boolean
/* */ ignorePunctuation	Boolean
/* */ localeMatcher	String
/* */ numeric	Boolean
/* */ sensitivity	String
/* */ usage	String

}

Compares this to that. Returns a negative number if this would sort before that, 0 if this and that are equal, and a positive number if this would sort after that.

Example:

console.log('hey'.localeCompare('hello'));
console.log('hey'.localeCompare('hey'));
console.log('hey'.localeCompare('hi'));

var x = ['foo', 'bar', 'baz'];
console.log(x.sort(function(a, b) {
  return a.localeCompare(b);
}));

Run

Results:

Spec

match(regexp : RegExp) : Array<String>

If regexp matches this, returns a new Array with item 0 equal to the portion of this that matched the regular expression, item 1 equal to the first capturing group in regexp, item 2 equal to the second capturing group in regexp, and so on. The returned Array will also have an index property set to the starting index of the match and an input property set to this. If regexp doesn't match this, returns null. See also String.matchAll() and RegExp.exec().

Example:

var regexp = /(\d\d\d)-(\d\d\d\d)/;
var result = 'call me: 555-4385'.match(regexp);
if (result) {
  console.log(result[0]);
  console.log(result[1]);
  console.log(result[2]);

  console.log('index: ' + result.index);
  console.log('input: ' + result.input);
}

Run

Results:

You can name capture groups by placing ?<name> at the start of the group. The captured values are available on a groups property on the returned array. Note, this is new with ECMAScript 2018.

Example:

var regexp = /(?<areacode>\d\d\d)-(?<number>\d\d\d-\d\d\d\d)/;
var result = 'call me: 333-555-4385'.match(regexp);
if (result) {
  console.dir(result.groups.areacode);
  console.dir(result[1]);
  console.dir(result.groups.number);
  console.dir(result[2]);
}

Run

Results:

Spec

matchAll(regexp : RegExp) : Iterator<Array<String>>

Returns an iterator of all places regexp matches this. regexp must be a global RegExp.

Example:

const string = 'a: 12, b: 5, d: 6';

// Find all numbers in the string
let regexp = /\d+/g;
for (const match of string.matchAll(regexp)) {
  console.log(match[0]);
}
console.log();

// Capture groups are available in the 1, 2, ... elements of the array
regexp = /(\w+): (\d+)/g;
for (const match of string.matchAll(regexp)) {
  console.log(match[1], match[2]);
}
console.log();

// Capture groups can also be named
regexp = /(?<key>\w+): (?<value>\d+)/g;
for (const match of string.matchAll(regexp)) {
  console.log(match.groups.key, match.groups.value);
}

Run

Results:

ECMAScript 2020

normalize(form : String) : String

Returns a normalized form of this according to form. form must be one of 'NFC', 'NFD', 'NFKC', or 'NFKD'. See https://unicode.org/reports/tr15/.

Example:

// See Figure 3 in https://unicode.org/reports/tr15/
var a = String.fromCharCode(0x212B);

var printString = function(form, s) {
  var charCodes = [...s].map(c => `   ${c}  0x${c.charCodeAt(0).toString(16)}  `);
  console.log(form, ' ', s, ' ', s.length, charCodes.join(' '));
};

console.log();
console.log('         len  char/code0  char/code1');  
printString('   ', a);
printString('NFD', a.normalize('NFD'));
printString('NFC', a.normalize('NFC'));

Run

Results:

Spec

padEnd(minLength : Number, [fill = ' ' : String]) : String

Returns a new string with fill added to the end of this until length is equal to minLength. If length is already greater than or equal to minLength, returns this unchanged.

Example:

console.log('x'.padEnd(6) + '.');
console.log('long'.padEnd(6) + '.');
console.log('really long'.padEnd(6) + '.');
console.log();

console.log('x'.padEnd(10, '.'));
console.log('y'.padEnd(10, '-_'));
console.log();

for (let i = -4; i <= 4; i++) {
  var cols = [i, i * i, i / 4];
  var colLengths = [5, 5, 7];
  var colStrings = cols.map(function(x, index) {
    return x.toString().padEnd(colLengths[index]);
  })
  console.log(colStrings.join(' | '));
}

Run

Results:

ECMAScript 2017 Spec

padStart(minLength : Number, [fill = ' ' : String]) : String

Returns a new string with fill added to the start of this until length is equal to minLength. If length is already greater than or equal to minLength, returns this unchanged.

Example:

console.log('x'.padStart(6));
console.log('long'.padStart(6));
console.log('really long'.padStart(6));
console.log();

console.log('x'.padStart(10, '.'));
console.log('y'.padStart(10, '-_'));
console.log();

for (let i = -4; i <= 4; i++) {
  var cols = [i, i * i, i / 4];
  var colLengths = [5, 5, 7];
  var colStrings = cols.map(function(x, index) {
    return x.toString().padStart(colLengths[index]);
  })
  console.log(colStrings.join(' | '));
}

Run

Results:

ECMAScript 2017 Spec

repeat(count : Number) : String

Returns a new String formed by repeating this count times.

Example:

console.log('.'.repeat(5));
console.log('-_'.repeat(5));

Run

Results:

Spec

replace 4 variants

replace(searchValue : String, replaceFunction : Function) : String

replaceFunction(match : String, offset : Number, string : String) : String

Returns a new String where the first occurrence of searchValue in this is replaced with the value returned from calling replaceFunction.

The match parameter to replaceFunction is the same as searchValue, offset is the index in this where searchValue was found, and string is this.

Example:

var x = 'abcba';
var replaced = 'abcba'.replace('b', function(match, offset, string) {
  console.log('found match of "' + match + '"');
  console.log('  at offset ' + offset);
  console.log('  of string "' + string + '"');

  return match.toUpperCase();
});

console.log('replaced=' + replaced);
console.log('x=' + x); // x is unchanged

Run

Results:

Spec

replace(searchValue : RegExp, replaceFunction : Function) : String

replaceFunction(match : String, capture1 : String, capture2 : String, ..., offset : Number, string : String) : String

Returns a new String where searchValue matches in this is replaced with the value returned from calling replaceFunction. If searchValue is a global RegExp, each match in this will be replaced. Otherwise, just the first match will be replaced.

The match parameter to replaceFunction is the same as searchValue, the capture parameters are the values of the capture groups in searchValue (if any), offset is the index in this where searchValue was found, and string is this.

Example:

var x = 'abcba';
var replaced = 'abcba'.replace(/b/g, function(match, offset, string) {
  console.log('found match of "' + match + '"');
  console.log('  at offset ' + offset);
  console.log('  of string "' + string + '"');

  return match.toUpperCase();
});

console.log('replaced=' + replaced);
console.log('x=' + x); // x is unchanged

Run

Results:

Spec

replace(searchValue : String, replaceValue : String) : String

Returns a new String where the first occurrence of searchValue in this is replaced with replaceValue.

Example:

var x = 'abcba'
console.log(x.replace('b', 'Z'));
console.log(x); // x is unchanged

Run

Results:

Spec

replace(searchValue : RegExp, replaceValue : String) : String

Returns a new String where searchValue is replaced with replaceValue. If searchValue is a global RegExp, each match in this will be replaced. Otherwise, just the first match will be replaced.

Example:

var x = 'abcba';
console.log(x.replace(/b/, 'Z'));
console.log(x.replace(/b/g, 'Z')); // global RegExp
console.log(x); // x is unchanged

Run

Results:

Spec

replaceAll 4 variants

replaceAll(searchValue : String, replaceFunction : Function) : String

replaceFunction(match : String, offset : Number, string : String) : String

Returns a new String where all occurrences of searchValue in this are replaced with the value returned from calling replaceFunction.

The match parameter to replaceFunction is the same as searchValue, offset is the index in this where searchValue was found, and string is this.

Example:

var x = 'abcba';
var replaced = 'abcba'.replaceAll('b', function(match, offset, string) {
  console.log('found match of "' + match + '"');
  console.log('  at offset ' + offset);
  console.log('  of string "' + string + '"');

  return match.toUpperCase();
});

console.log('replaced=' + replaced);
console.log('x=' + x); // x is unchanged

Run

Results:

replaceAll(searchValue : RegExp, replaceFunction : Function) : String

replaceFunction(match : String, capture1 : String, capture2 : String, ..., offset : Number, string : String) : String

Returns a new String where all matches of searchValue in this are replaced with the value returned from calling replaceFunction. searchValue must be a global RegExp.

Example:

var x = 'abcba';
var replaced = 'abcba'.replaceAll(/b/g, function(match, offset, string) {
  console.log('found match of "' + match + '"');
  console.log('  at offset ' + offset);
  console.log('  of string "' + string + '"');

  return match.toUpperCase();
});

console.log('replaced=' + replaced);
console.log('x=' + x); // x is unchanged

Run

Results:

replaceAll(searchValue : String, replaceValue : String) : String

Returns a new String where all occurrences of searchValue in this are replaced with replaceValue.

Example:

var x = 'abcba'
console.log(x.replaceAll('b', 'Z'));
console.log(x); // x is unchanged

Run

Results:

replaceAll(searchValue : RegExp, replaceValue : String) : String

Returns a new String where all matches of searchValue are replaced with replaceValue. searchValue must be a global RegExp.

Example:

var x = 'abcba';
console.log(x.replaceAll(/b/g, 'Z'));
console.log(x); // x is unchanged

Run

Results:

search(regexp : RegExp) : Number

Executes regexp on this and returns the index of the first match. Returns -1 if regexp does not match this.

Example:

console.log('abcba'.search(/b/));
console.log('abcba'.search(/e/));

Run

Results:

Spec

slice(startIndex : Number, [endIndex : Number]) : String

Returns a new string composed of the section of this between start and end-1. If endIndex is not specified, this.length is used instead. If startIndex or endIndex is negative, this.length is added to it before performing the substring. Similar to substring().

Example:

var x = 'abcde';
console.log(x.slice(2));
console.log(x.slice(-2));
console.log(x.slice(2, 4));
console.log(x.slice(2, -1));
console.log(x); // x is unchanged

Run

Results:

Spec

split 2 variants

split(separator : String, [limit : Number]) : Array<String>

Splits this at separator into an Array of Strings. If limit is specified, the returned array will contain no more than limit items.

Example:

var x = 'abcba';
console.log(x.split('b'));
console.log(x.split('b', 2));
console.log(x); // x is unchanged

Run

Results:

Spec

split(separator : RegExp, [limit : Number]) : Array<String>

Splits this into an Array of Strings. If limit is specified, the returned array will contain no more than limit items.

Example:

var x = 'abcba';
console.log(x.split(/b/));
console.log(x.split(/b/, 2));
console.log(x); // x is unchanged

Run

Results:

Spec

startsWith(searchString : String, [startingIndex = 0 : Number]) : Boolean

Returns true if searchString is at the beginning of this. If startingIndex is specified, searchString must be at startingIndex in this.

Example:

var a = 'abcxyz';
console.log(a.startsWith('abc'));
console.log(a.startsWith('bc', 1));

Run

Results:

Spec

substring(start : Number, [end : Number]) : String

Returns a new string composed of the section of this between start and end-1. Before performing the operation, substring may modifiy the effective values of start and end as follows. If both start and end are specified, and end is less than start, the values are swapped. If start is less than 0, it is replaced with 0. If end is negative, this.length is added to it before performing the substring. If end is not specified, this.length is used instead. Similar to slice().

Example:

var x = 'abcde';
console.log(x.substring(2));
console.log(x.substring(-2));
console.log(x.substring(2, 4));
console.log(x.substring(4, 2));
console.log(x.substring(2, -1));
console.log(x); // x is unchanged

Run

Results:

Spec

toLocaleLowerCase() : String

Returns a copy of this where each character is lower case.

Example:

var x = 'aBCdEf';
console.log(x.toLocaleLowerCase());
console.log(x); // x is unchanged

Run

Results:

Spec

toLocaleUpperCase() : String

Returns a copy of this where each character is upper case.

Example:

var x = 'aBCdEf';
console.log(x.toLocaleUpperCase());
console.log(x); // x is unchanged

Run

Results:

Spec

toLowerCase() : String

Returns a copy of this where each character is lower case.

Example:

var x = 'aBCdEf';
console.log(x.toLowerCase());
console.log(x); // x is unchanged

Run

Results:

Spec

toUpperCase() : String

Returns a copy of this where each character is upper case.

Example:

var x = 'aBCdEf';
console.log(x.toUpperCase());
console.log(x); // x is unchanged

Run

Results:

Spec

trim() : String

Returns a copy of this with leading and trailing whitespace removed. See also trimStart() and trimEnd().

Example:

var x = ' \t ab c ';
console.log("'" + x.trim() + "'");
console.log("'" + x + "'"); // x is unchanged

Run

Results:

Spec

trimEnd() : String

Returns a copy of this with trailing whitespace removed. See also trim() and trimStart().

Example:

var x = ' \t ab c ';
console.log("'" + x.trimEnd() + "'");

Run

Results:

ECMAScript 2019 Spec

trimStart() : String

Returns a copy of this with leading whitespace removed. See also trim() and trimEnd().

Example:

var x = ' \t ab c ';
console.log("'" + x.trimStart() + "'");

Run

Results:

ECMAScript 2019 Spec

String Methods

fromCharCode(char0 : Number, [char1 : Number, [...]]) : String

Returns a new string composed of characters from the specified UTF-16 values. Each code should be between 0 and 0xFFFF inclusive. Use charCodeAt() to retrieve character codes from strings. See also fromCodePoint().

Example:

console.log(String.fromCharCode(97, 98, 99));

Run

Results:

Spec

fromCodePoint(codePoint0 : Number, [codePoint1 : Number, [...]]) : String

Returns a new string composed of characters from the specified UTF-32 code points. Each code point should be between 0 and 0x10FFFF inclusive. Use codePointAt() to retrievecodes from strings. See also fromCharCode().

Example:

console.log(String.fromCharCode(0xD83D, 0xDE00));
console.log(String.fromCodePoint(0xD83D, 0xDE00));
console.log(String.fromCodePoint(0x1F600));

Run

Results:

Spec

home license contribute feedback