Merge pull request #13807 from grails/add-trimToNull-GrailsStringUtils

add trimToNull method on GrailsStringUtils

Author: jamesfredley

grails-core/src/main/groovy/grails/util/GrailsStringUtils.groovy

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012 the original author or authors.
+ * Copyright 2012-2025 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.
@@ -191,4 +191,30 @@ abstract class GrailsStringUtils extends StringUtils{
         stripFilenameExtension( getFilename(path) )
     }
 
+    /**
+     * Removes all space from both ends of this String returning
+     * {@code null} if the String is empty ("") after the trim
+     * or if it is {@code null}.
+     *
+     * <p>The String is trimmed using {@link String#trim()}.
+     *
+     * <pre>
+     * GrailsStringUtils.trimToNull(null)          = null
+     * GrailsStringUtils.trimToNull("")            = null
+     * GrailsStringUtils.trimToNull("     ")       = null
+     * GrailsStringUtils.trimToNull("xyz")         = "xyz"
+     * GrailsStringUtils.trimToNull("    xyz    ") = "xyz"
+     * </pre>
+     * 
+     *  based on https://github.com/apache/commons-lang/blob/master/src/main/java/org/apache/commons/lang3/StringUtils.java#L8838
+     *
+     * @param str  the String to be trimmed, may be null
+     * @return the trimmed String,
+     *  {@code null} if only containing space, empty or null String input
+     * @since 7.0.0
+     */
+    static String trimToNull(String str) {
+        String trimmed = str?.trim()
+        return hasLength(trimmed) ? trimmed : null
+    }
 }

grails-core/src/test/groovy/grails/util/GrailsStringUtilsSpec.groovy

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012 the original author or authors.
+ * Copyright 2012-2025 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.
@@ -23,6 +23,26 @@ import spock.lang.Specification
  */
 class GrailsStringUtilsSpec extends Specification{
 
+    static final String FOO = 'foo'
+    static final String TRIMMABLE
+    static final String NON_TRIMMABLE
+
+    static {
+        def trimmable = new StringBuilder()
+        def nonTrimmable = new StringBuilder()
+        (0..<Character.MAX_VALUE).each { i ->
+            char ch = (char) i
+            if (Character.isWhitespace(ch) && i > 32) {
+                nonTrimmable.append(ch)
+            }
+        }
+        (0..32).each { int i ->
+            trimmable.append((char) i)
+        }
+        TRIMMABLE = trimmable.toString()
+        NON_TRIMMABLE = nonTrimmable.toString()
+    }
+
     void "Test toBoolean"() {
         expect:
             GrailsStringUtils.toBoolean("on") == true
@@ -63,4 +83,17 @@ class GrailsStringUtilsSpec extends Specification{
             GrailsStringUtils.trimStart("abc", "ab") == 'c'
             GrailsStringUtils.trimStart("abc", "c") == 'abc'
     }
+
+    void "Test trimToNull method"() {
+        expect:
+            GrailsStringUtils.trimToNull(FOO + "  ") == FOO
+            GrailsStringUtils.trimToNull(" " + FOO + "  ") == FOO
+            GrailsStringUtils.trimToNull(" " + FOO) == FOO
+            GrailsStringUtils.trimToNull(FOO + "") == FOO
+            GrailsStringUtils.trimToNull(" \t\r\n\b ") == null
+            GrailsStringUtils.trimToNull(TRIMMABLE) == null
+            GrailsStringUtils.trimToNull(NON_TRIMMABLE) == NON_TRIMMABLE
+            GrailsStringUtils.trimToNull("") == null
+            GrailsStringUtils.trimToNull(null) == null
+    }
 }