Add SystemUtils.getUserHomePath()

Author: garydgregory

src/changes/changes.xml

@@ -107,6 +107,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemUtils.getJavaIoTmpDirPath().</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemUtils.getJavaHomePath().</action>
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemUtils.getUserDirPath().</action>
+    <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add SystemUtils.getUserHomePath().</action>
     <!-- UPDATE -->
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 73 to 81 #1267, #1277, #1283, #1288, #1302.</action>
     <action                   type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">[site] Bump org.codehaus.mojo:taglist-maven-plugin from 3.1.0 to 3.2.1 #1300.</action>

src/main/java/org/apache/commons/lang3/SystemUtils.java

@@ -2190,6 +2190,21 @@ public static File getUserHome() {
         return new File(SystemProperties.getUserHome());
     }
 
+    /**
+     * Gets the current user home directory as a {@link Path}.
+     * <p>
+     * The result is based on the system property {@value SystemProperties#USER_HOME}.
+     * </p>
+     *
+     * @return a directory
+     * @throws SecurityException if a security manager exists and its {@code checkPropertyAccess} method doesn't allow access to the specified system property.
+     * @see SystemProperties#getUserHome()
+     * @since 3.18.0
+     */
+    public static Path getUserHomePath() {
+        return Paths.get(SystemProperties.getUserHome());
+    }
+
     /**
      * Gets the current user name.
      * <p>

src/test/java/org/apache/commons/lang3/SystemUtilsTest.java

@@ -342,6 +342,16 @@ public void testGetUserHome() {
         assertTrue(dir.exists());
     }
 
+    /**
+     * Assumes no security manager exists.
+     */
+    @Test
+    public void testGetUserHomePath() {
+        final Path dir = SystemUtils.getUserHomePath();
+        assertNotNull(dir);
+        assertTrue(Files.exists(dir));
+    }
+
     /**
      * Assumes no security manager exists.
      */