Add Add org.apache.commons.io.Charsets.isAlias(Charset, String)

- Add org.apache.commons.io.Charsets.isUTF8(Charset)
- Add org.apache.commons.io.Charsets.toCharsetDefault(String, Charset)

Author: garydgregory

src/changes/changes.xml

@@ -67,7 +67,10 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="fix"                due-to="Gary Gregory">Fix SpotBugs [ERROR] Medium: Shared primitive variable "closed" in one thread may not yield the value of the most recent write from another thread [org.apache.commons.io.input.ProxyInputStream] At ProxyInputStream.java:[line 233] AT_STALE_THREAD_WRITE_OF_PRIMITIVE.</action>
       <action dev="ggregory" type="fix"                due-to="Gary Gregory">Fix SpotBugs [ERROR] Medium: Shared primitive variable "propagateClose" in one thread may not yield the value of the most recent write from another thread [org.apache.commons.io.input.BoundedInputStream] At BoundedInputStream.java:[line 555] AT_STALE_THREAD_WRITE_OF_PRIMITIVE.</action>
       <!-- ADD -->
-      <action dev="ggregory" type="add" issue="IO-875" due-to="Pierre Baumard, Gary Gregory">Add and use org.apache.commons.io.file.CountingPathVisitor.accept(Path, BasicFileAttributes) #743.</action> 
+      <action dev="ggregory" type="add" issue="IO-875" due-to="Pierre Baumard, Gary Gregory">Add and use org.apache.commons.io.file.CountingPathVisitor.accept(Path, BasicFileAttributes) #743.</action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">Add org.apache.commons.io.Charsets.isAlias(Charset, String).</action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">Add org.apache.commons.io.Charsets.isUTF8(Charset).</action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">Add org.apache.commons.io.Charsets.toCharsetDefault(String, Charset).</action>
       <!-- UPDATE -->
     </release>
     <release version="2.19.0" date="2025-04-08" description="Version 2.19.0: Java 8 or later is required.">

src/main/java/org/apache/commons/io/Charsets.java

@@ -156,6 +156,39 @@ public class Charsets {
     @Deprecated
     public static final Charset UTF_8 = StandardCharsets.UTF_8;
 
+    /**
+     * Tests whether the given non-null Charset has an alias of the given name.
+     *
+     * @param charset a non-null Charset.
+     * @param charsetName The name to test.
+     * @return whether the given non-null charset name is a UTF-8 alias.
+     * @since 2.20.0
+     */
+    public static boolean isAlias(final Charset charset, final String charsetName) {
+        return charsetName != null && (charset.name().equalsIgnoreCase(charsetName) || charset.aliases().stream().anyMatch(charsetName::equalsIgnoreCase));
+    }
+
+    /**
+     * Tests whether a given encoding is UTF-8. If the given charset is null, then check the platform's default encoding.
+     *
+     * @param charset If the given charset is null, then check the platform's default encoding.
+     * @return whether a given encoding is UTF-8.
+     * @since 2.20.0
+     */
+    public static boolean isUTF8(final Charset charset) {
+        return isUTF8Alias(toCharset(charset).name());
+    }
+
+    /**
+     * Tests whether the given non-null charset name is a UTF-8 alias.
+     *
+     * @param charsetName a non-null charset name.
+     * @return whether the given non-null charset name is a UTF-8 alias.
+     */
+    private static boolean isUTF8Alias(final String charsetName) {
+        return isAlias(StandardCharsets.UTF_8, charsetName);
+    }
+
     /**
      * Constructs a sorted map from canonical charset names to charset objects required of every implementation of the
      * Java platform.
@@ -212,7 +245,7 @@ public static Charset toCharset(final String charsetName) throws UnsupportedChar
      * Returns a Charset for the named charset. If the name is null, return the given default Charset.
      *
      * @param charsetName The name of the requested charset, may be null.
-     * @param defaultCharset The name charset to return if charsetName is null, may be null.
+     * @param defaultCharset The charset to return if charsetName is null, may be null.
      * @return a Charset for the named charset.
      * @throws UnsupportedCharsetException If the named charset is unavailable (unchecked exception).
      * @since 2.12.0
@@ -221,6 +254,26 @@ public static Charset toCharset(final String charsetName, final Charset defaultC
         return charsetName == null ? defaultCharset : Charset.forName(charsetName);
     }
 
+    /**
+     * Returns a Charset for the named charset or the {@code defaultCharset}.
+     * <p>
+     * If {@code charsetName} cannot load a charset, return {@code defaultCharset}. Therefore, this method should never fail and always return a Charset.
+     * </p>
+     *
+     * @param charsetName    The name of the requested charset, may be null.
+     * @param defaultCharset The charset to return if charsetName is null or there is a problem, may be null which returns {@link Charset#defaultCharset()}.
+     * @return a Charset for the named charset or {@code defaultCharset} if any errors occur.
+     * @see Charset#defaultCharset()
+     * @since 2.20.0
+     */
+    public static Charset toCharsetDefault(final String charsetName, final Charset defaultCharset) {
+        try {
+            return toCharset(charsetName);
+        } catch (final RuntimeException ignored) {
+            return toCharset(defaultCharset);
+        }
+    }
+
     /**
      * Construct a new instance.
      *

src/test/java/org/apache/commons/io/CharsetsTest.java

@@ -18,14 +18,23 @@
 package org.apache.commons.io;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeFalse;
 
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
+import java.util.Collection;
 import java.util.Set;
 import java.util.SortedMap;
+import java.util.stream.Stream;
 
+import org.apache.commons.lang3.StringUtils;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
 /**
  * Tests {@link Charsets}.
@@ -51,6 +60,20 @@ public static Set<String> availableCharsetsKeySet() {
         return Charset.availableCharsets().keySet();
     }
 
+    /**
+     * For parameterized tests.
+     *
+     * @return {@code Charset.availableCharsets().values()}.
+     */
+    public static Collection<Charset> availableCharsetsValues() {
+        return Charset.availableCharsets().values();
+    }
+
+    static Stream<Arguments> charsetAliasProvider() {
+        return Charset.availableCharsets().entrySet().stream()
+                .flatMap(entry -> entry.getValue().aliases().stream().map(a -> Arguments.of(entry.getValue(), a)));
+    }
+
     /**
      * For parameterized tests.
      *
@@ -60,11 +83,33 @@ public static Set<String> getRequiredCharsetNames() {
         return Charsets.requiredCharsets().keySet();
     }
 
+    @ParameterizedTest
+    @MethodSource("charsetAliasProvider")
+    public void testIsAlias(final Charset charset, final String charsetAlias) {
+        assertTrue(Charsets.isAlias(charset, charsetAlias));
+        assertTrue(Charsets.isAlias(charset, charsetAlias.toLowerCase()));
+        assertTrue(Charsets.isAlias(charset, charsetAlias.toUpperCase()));
+        assertTrue(Charsets.isAlias(charset, charset.name()));
+        assertFalse(Charsets.isAlias(charset, null));
+    }
+
     @Test
     public void testIso8859_1() {
         assertEquals("ISO-8859-1", Charsets.ISO_8859_1.name());
     }
 
+    @ParameterizedTest
+    @MethodSource("availableCharsetsValues")
+    public void testIsUTF8Charset(final Charset charset) {
+        assumeFalse(StandardCharsets.UTF_8.equals(charset));
+        charset.aliases().forEach(n -> assertFalse(Charsets.isUTF8(Charset.forName(n))));
+    }
+
+    public void testIsUTF8CharsetUTF8() {
+        assertTrue(Charsets.isUTF8(StandardCharsets.UTF_8));
+        StandardCharsets.UTF_8.aliases().forEach(n -> assertTrue(Charsets.isUTF8(Charset.forName(n))));
+    }
+
     @Test
     public void testRequiredCharsets() {
         final SortedMap<String, Charset> requiredCharsets = Charsets.requiredCharsets();
@@ -87,7 +132,18 @@ public void testToCharset_String() {
     }
 
     @Test
-    public void testToCharset_String_Charset() {
+    public void testToCharsetDefault() {
+        assertEquals(StandardCharsets.UTF_8, Charsets.toCharsetDefault((String) null, null));
+        assertEquals(StandardCharsets.UTF_8, Charsets.toCharsetDefault(StringUtils.EMPTY, null));
+        assertEquals(StandardCharsets.UTF_8, Charsets.toCharsetDefault(".", null));
+        assertEquals(Charset.defaultCharset(), Charsets.toCharsetDefault(null, Charset.defaultCharset()));
+        assertEquals(Charset.defaultCharset(), Charsets.toCharsetDefault(Charset.defaultCharset().name(), Charset.defaultCharset()));
+        assertEquals(StandardCharsets.UTF_8, Charsets.toCharsetDefault(StandardCharsets.UTF_8.name(), Charset.defaultCharset()));
+        assertEquals(StandardCharsets.UTF_8, Charsets.toCharsetDefault(StandardCharsets.UTF_8.name(), null));
+    }
+
+    @Test
+    public void testToCharsetWithStringCharset() {
         assertNull(Charsets.toCharset((String) null, null));
         assertEquals(Charset.defaultCharset(), Charsets.toCharset((String) null, Charset.defaultCharset()));
         assertEquals(Charset.defaultCharset(), Charsets.toCharset((Charset) null, Charset.defaultCharset()));