From b9bad56fc1aee966839ae3cd2ab4325b0a60ff5d Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Fri, 26 Jan 2024 17:37:32 +0100
Subject: [PATCH] Document repeat and characer subtraction String operators in
 SpEL

Closes gh-32137
---
 .../expressions/language-ref/operators.adoc   | 83 ++++++++++++++++---
 .../spel/SpelDocumentationTests.java          | 22 +++--
 2 files changed, 89 insertions(+), 16 deletions(-)

diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
index 850710c11ce7..2a09400c34e4 100644
--- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
+++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
@@ -5,6 +5,7 @@ The Spring Expression Language supports the following kinds of operators:
 
 * xref:core/expressions/language-ref/operators.adoc#expressions-operators-relational[Relational Operators]
 * xref:core/expressions/language-ref/operators.adoc#expressions-operators-logical[Logical Operators]
+* xref:core/expressions/language-ref/operators.adoc#expressions-operators-string[String Operators]
 * xref:core/expressions/language-ref/operators.adoc#expressions-operators-mathematical[Mathematical Operators]
 * xref:core/expressions/language-ref/operators.adoc#expressions-assignment[The Assignment Operator]
 
@@ -207,14 +208,80 @@ Kotlin::
 ======
 
 
+[[expressions-operators-string]]
+== String Operators
+
+You can use the following operators on strings.
+
+* concatenation (`+`)
+* subtraction (`-`)
+  - for use with a string containing a single character
+* repeat (`*`)
+
+The following example shows the `String` operators in use:
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+----
+	// -- Concatenation --
+
+	// evaluates to "hello world"
+	String helloWorld = parser.parseExpression("'hello' + ' ' + 'world'")
+			.getValue(String.class);
+
+	// -- Character Subtraction --
+
+	// evaluates to 'a'
+	char ch = parser.parseExpression("'d' - 3")
+			.getValue(char.class);
+
+	// -- Repeat --
+
+	// evaluates to "abcabc"
+	String repeated = parser.parseExpression("'abc' * 2")
+			.getValue(String.class);
+----
+
+Kotlin::
++
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+	// -- Concatenation --
+
+	// evaluates to "hello world"
+	val helloWorld = parser.parseExpression("'hello' + ' ' + 'world'")
+			.getValue(String::class.java)
+
+	// -- Character Subtraction --
+
+	// evaluates to 'a'
+	val ch = parser.parseExpression("'d' - 3")
+			.getValue(Character::class.java);
+
+	// -- Repeat --
+
+	// evaluates to "abcabc"
+	val repeated = parser.parseExpression("'abc' * 2")
+			.getValue(String::class.java);
+----
+======
+
 [[expressions-operators-mathematical]]
 == Mathematical Operators
 
-You can use the addition operator (`+`) on both numbers and strings. You can use the
-subtraction (`-`), multiplication (`*`), and division (`/`) operators only on numbers.
-You can also use the modulus (`%`) and exponential power (`^`) operators on numbers.
-Standard operator precedence is enforced. The following example shows the mathematical
-operators in use:
+You can use the following operators on numbers, and standard operator precedence is enforced.
+
+* addition (`+`)
+* subtraction (`-`)
+* multiplication (`*`)
+* division (`/`)
+* modulus (`%`)
+* exponential power (`^`)
+
+The following example shows the mathematical operators in use:
 
 [tabs]
 ======
@@ -225,9 +292,6 @@ Java::
 	// Addition
 	int two = parser.parseExpression("1 + 1").getValue(Integer.class);  // 2
 
-	String testString = parser.parseExpression(
-			"'test' + ' ' + 'string'").getValue(String.class);  // 'test string'
-
 	// Subtraction
 	int four = parser.parseExpression("1 - -3").getValue(Integer.class);  // 4
 
@@ -259,9 +323,6 @@ Kotlin::
 	// Addition
 	val two = parser.parseExpression("1 + 1").getValue(Int::class.java)  // 2
 
-	val testString = parser.parseExpression(
-			"'test' + ' ' + 'string'").getValue(String::class.java)  // 'test string'
-
 	// Subtraction
 	val four = parser.parseExpression("1 - -3").getValue(Int::class.java)  // 4
 
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java
index 3d5c7d25ac53..f97962c5e7a3 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -283,14 +283,26 @@ void logicalOperators() {
 	}
 
 	@Test
-	void numericalOperators() {
+	void stringOperators() {
+		// Concatenation
+		String helloWorld = parser.parseExpression("'hello' + ' ' + 'world'").getValue(String.class);
+		assertThat(helloWorld).isEqualTo("hello world");
+
+		// Character Subtraction
+		char ch = parser.parseExpression("'d' - 3").getValue(char.class);
+		assertThat(ch).isEqualTo('a');
+
+		// Repeat
+		String repeated = parser.parseExpression("'abc' * 2").getValue(String.class);
+		assertThat(repeated).isEqualTo("abcabc");
+	}
+
+	@Test
+	void mathematicalOperators() {
 		// Addition
 		int two = parser.parseExpression("1 + 1").getValue(Integer.class); // 2
 		assertThat(two).isEqualTo(2);
 
-		String testString = parser.parseExpression("'test' + ' ' + 'string'").getValue(String.class); // 'test string'
-		assertThat(testString).isEqualTo("test string");
-
 		// Subtraction
 		int four = parser.parseExpression("1 - -3").getValue(Integer.class); // 4
 		assertThat(four).isEqualTo(4);