The String object's substring() method

The String object's substring() method extracts characters from a string between two specified indices and returns them as a new string.

Syntax

string.substring(startIndex[, endIndex])

Parameters

startIndex:

• The index where to start the extraction. The first character is at index 0.

• If greater than endIndex, substring() swaps the two arguments.

• If negative or NaN, treated as 0.

endIndex (optional):

• The index where to end the extraction (character at this index is not included).

• If omitted, extracts characters to the end of the string.

• If negative or NaN, treated as 0.

Return value

The substring() method returns a new string containing the extracted characters.

Examples

Example 1: Basic substring extraction

In the code below, the function substringEx1() shows basic usage of the substring() method.

function substringEx1() {
  let str = "Hello World!";
  
  // Extract "Hello" (characters from index 0 to 4)
  Logger.log(str.substring(0, 5));
  
  // Extract "World" (characters from index 6 to 10)
  Logger.log(str.substring(6, 11));
  
  // Extract from index 6 to the end
  Logger.log(str.substring(6));
}

Output

Hello

World

World!

Example 2: Demonstrating parameter swapping

In the code below, the function substringEx2() shows how substring() handles when startIndex is greater than endIndex.

function substringEx2() {
  let str = "Hello World!";
  
  // These two lines produce the same result
  Logger.log(str.substring(0, 5));  // Normal order
  Logger.log(str.substring(5, 0));  // Swapped order
  
  // These also produce the same result
  Logger.log(str.substring(6, 11));  // Normal order
  Logger.log(str.substring(11, 6));  // Swapped order
}

Output

Hello

Hello

World

World

Example 3: Handling negative indices and NaN

In the code below, the function substringEx3() demonstrates how substring() handles negative numbers and NaN values.

function substringEx3() {
  let str = "Hello World!";
  
  // Negative numbers are treated as 0
  Logger.log(str.substring(-3));  // Same as substring(0)
  Logger.log(str.substring(0, -3));  // Same as substring(0, 0)
  
  // NaN is treated as 0
  Logger.log(str.substring(NaN, 5));  // Same as substring(0, 5)
  Logger.log(str.substring('invalid', 5));  // Same as substring(0, 5)
}

Output

Hello World!

Hello

Hello

Example 4: Demonstrating immutability

In the code below, the function substringEx4() shows that substring() creates a new string without modifying the original.

function substringEx4() {
  let originalStr = "Hello World!";
  
  // Create a new string using substring()
  let extractedStr = originalStr.substring(0, 5);
  
  // Show that original string is unchanged
  Logger.log("Original string: " + originalStr);
  Logger.log("Extracted string: " + extractedStr);
  
  // Modify the extracted string
  let modifiedStr = extractedStr.toUpperCase();
  Logger.log("Modified extracted string: " + modifiedStr);
  Logger.log("Original string still unchanged: " + originalStr);
}

Output

Original string: Hello World!

Extracted string: Hello

Modified extracted string: HELLO

Original string still unchanged: Hello World!

Conclusion

In this tutorial, you learned how to use the substring() method to extract characters from strings in Apps Script. The substring() method is useful for text processing tasks, but remember its unique handling of negative indices and argument swapping compared to slice(). Like other string methods, substring() returns a new string and doesn't modify the original string.