String.raw()

The static String.raw() method is a tag function of template literals. This is similar to the r prefix in Python, or the @ prefix in C# for string literals. It's used to get the raw string form of template literals — that is, substitutions (e.g. ${foo}) are processed, but escape sequences (e.g. \n) are not.

Syntax

String.raw(strings, ...substitutions)

String.raw`templateString`

Parameters

• strings
  • : Well-formed template literal array object, like { raw: ['foo', 'bar', 'baz'] }. Should be an object with a raw property whose value is an array-like object of strings.
• ...substitutions
  • : Contains substitution values.
• templateString
  • : A template literal, optionally with substitutions (${...}).

Return value

The raw string form of a given template literal.

Exceptions

• TypeError
  • : Thrown if the first argument doesn't have a raw property, or the raw property is undefined or null.

Description

In most cases, String.raw() is used with template literals. The first syntax mentioned above is only rarely used, because the JavaScript engine will call this with proper arguments for you, (just like with other tag functions).

String.raw() is the only built-in template literal tag. It has close semantics to an untagged literal since it concatenates all arguments and returns a string. You can even re-implement it with normal JavaScript code.

Warning: You should not use String.raw directly as an "identity" tag. See Building an identity tag for how to implement this.

If String.raw() is called with an object whose raw property doesn't have a length property or a non-positive length, it returns an empty string "". If substitutions.length < strings.raw.length - 1 (i.e. there are not enough substitutions to fill the placeholders — which can't happen in a well-formed tagged template literal), the rest of the placeholders are filled with empty strings.