The String object's toUpperCase() and toLowerCase() methods

The String object's toUpperCase() and toLowerCase() methods convert the character casing of a string, returning a new string with all characters converted to uppercase or lowercase respectively.

Syntax

string.toUpperCase()
string.toLowerCase()

Parameters

Not applicable. Neither method accepts any parameters.

Return value

Both methods return a new string with the case converted. The original string remains unchanged.

Examples

Example 1: Basic case conversion

In the code below, the function caseEx1() demonstrates basic uppercase and lowercase conversions.

function caseEx1() {
  let str = "Hello World!";
  
  // Convert to uppercase
  Logger.log(str.toUpperCase());
  
  // Convert to lowercase
  Logger.log(str.toLowerCase());
  
  // Show original remains unchanged
  Logger.log("Original string: " + str);
}

Output

HELLO WORLD!

hello world!

Original string: Hello World!

Example 2: Working with mixed case strings

In the code below, the function caseEx2() shows how these methods handle strings with mixed case and special characters.

function caseEx2() {
  let mixedStr = "MiXeD cAsE 123 !@#";
  let email = "User.Name@EXAMPLE.com";
  
  // Convert mixed case string
  Logger.log(mixedStr.toUpperCase());
  Logger.log(mixedStr.toLowerCase());
  
  // Normalize email address
  Logger.log(email.toLowerCase());
}

Output

MIXED CASE 123 !@#

mixed case 123 !@#

user.name@example.com

Example 3: Case manipulation for formatting

In the code below, the function caseEx3() demonstrates practical applications of case conversion.

function caseEx3() {
  let name = "john smith";
  
  // Create title case (first letter of each word uppercase)
  let words = name.toLowerCase().split(' ');
  let titleCase = words.map(function(word) {
    return word.charAt(0).toUpperCase() + word.slice(1);
  }).join(' ');
  
  Logger.log(titleCase);
}

Output

John Smith

Example 4: Demonstrating immutability

In the code below, the function caseEx4() shows that both methods return new strings without modifying the original.

function caseEx4() {
  let originalStr = "Mixed Case String";
  
  // Create new strings with case conversion
  let upperStr = originalStr.toUpperCase();
  let lowerStr = originalStr.toLowerCase();
  
  // Show all three strings
  Logger.log("Original: " + originalStr);
  Logger.log("Uppercase: " + upperStr);
  Logger.log("Lowercase: " + lowerStr);
  
  // Demonstrate chaining of methods
  Logger.log(originalStr.toUpperCase().toLowerCase());
}

Output

Original: Mixed Case String

Uppercase: MIXED CASE STRING

Lowercase: mixed case string

mixed case string

Common Use Cases

Case conversion methods are useful in many text processing scenarios. Here are some common applications:

• Data normalization: Convert text to a consistent case before comparison or storage. For example, converting email addresses to lowercase for consistent matching.

• User interface formatting: Format text for display in different UI contexts, such as headers in uppercase or menu items in title case.

• Search functionality: Convert both search terms and searchable content to the same case for case-insensitive searching.

• Input validation: Normalize user input regardless of how it was typed, ensuring consistent data handling.

• Style compliance: Ensure text follows specific style guidelines, such as lowercase URLs or uppercase abbreviations.

Conclusion

In this tutorial, you learned how to use the toUpperCase() and toLowerCase() methods to convert string cases in Apps Script. These methods are useful for text processing tasks, data normalization, and maintaining consistent text formatting. Remember that both methods return new strings and don't modify the original string.