Introduce pathString/absolute/absolutePathString

Rename invariantSeparatorsPath to invariantSeparatorsPathString
to have more consistent names of methods returning path strings.

KT-19192

libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt

@@ -44,17 +44,66 @@ public val Path.extension: String
     get() = fileName?.toString()?.substringAfterLast('.', "") ?: ""
 
 /**
- * Returns this path as a [String] using the invariant separator '/' to
- * separate the names in the name sequence.
+ * Returns the string representation of this path.
+ *
+ * The returned path string uses the default name [separator][FileSystem.getSeparator]
+ * to separate names in the path.
+ *
+ * This property is a synonym to [Path.toString] function.
  */
 @SinceKotlin("1.4")
 @ExperimentalPathApi
-public val Path.invariantSeparatorsPath: String
+@kotlin.internal.InlineOnly
+public inline val Path.pathString: String
+    get() = toString()
+
+/**
+ * Returns the string representation of this path using the invariant separator '/'
+ * to separate names in the path.
+ */
+@SinceKotlin("1.4")
+@ExperimentalPathApi
+public val Path.invariantSeparatorsPathString: String
     get() {
         val separator = fileSystem.separator
         return if (separator != "/") toString().replace(separator, "/") else toString()
     }
 
+// TODO: raise deprecation level and make inline-only
+@SinceKotlin("1.4")
+@ExperimentalPathApi
+@Deprecated("Use invariantSeparatorsPathString property instead.", ReplaceWith("invariantSeparatorsPathString"))
+public inline val Path.invariantSeparatorsPath: String
+    get() = invariantSeparatorsPathString
+
+/**
+ * Converts this possibly relative path to an absolute path.
+ *
+ * If this path is already [absolute][Path.isAbsolute], returns this path unchanged.
+ * Otherwise, resolves this path, usually against the default directory of the file system.
+ *
+ * May throw an exception if the file system is inaccessible or getting the default directory path is prohibited.
+ *
+ * See [Path.toAbsolutePath] for further details about the function contract and possible exceptions.
+ */
+@SinceKotlin("1.4")
+@ExperimentalPathApi
+@kotlin.internal.InlineOnly
+public inline fun Path.absolute(): Path = toAbsolutePath()
+
+/**
+ * Converts this possibly relative path to an absolute path and returns its string representation.
+ *
+ * Basically, this method is a combination of calling [absolute] and [pathString].
+ *
+ * May throw an exception if the file system is inaccessible or getting the default directory path is prohibited.
+ *
+ * See [Path.toAbsolutePath] for further details about the function contract and possible exceptions.
+ */
+@SinceKotlin("1.4")
+@ExperimentalPathApi
+@kotlin.internal.InlineOnly
+public inline fun Path.absolutePathString(): String = toAbsolutePath().toString()
 
 /**
  * Calculates the relative path for this path from a [base] path.

libraries/stdlib/jdk7/test/PathExtensionsTest.kt

@@ -38,10 +38,10 @@ class PathExtensionsTest : AbstractPathTest() {
     @Test
     fun invariantSeparators() {
         val path = Path("base") / "nested" / "leaf"
-        assertEquals("base/nested/leaf", path.invariantSeparatorsPath)
+        assertEquals("base/nested/leaf", path.invariantSeparatorsPathString)
 
-        val path2 = Path("base", "nested", "leaf")
-        assertEquals("base/nested/leaf", path2.invariantSeparatorsPath)
+        val path2 = Path("base", "nested", "terminal")
+        assertEquals("base/nested/terminal", path2.invariantSeparatorsPathString)
     }
 
     @Test
@@ -149,7 +149,7 @@ class PathExtensionsTest : AbstractPathTest() {
 
     @Test
     fun copyToNameWithoutParent() {
-        val currentDir = Path("").toAbsolutePath()
+        val currentDir = Path("").absolute()
         val srcFile = createTempFile().cleanup()
         val dstFile = createTempFile(directory = currentDir).cleanup()
 
@@ -580,4 +580,11 @@ class PathExtensionsTest : AbstractPathTest() {
         testRelativeTo("foo/bar", "../../foo/bar", "../../sub/../.")
         testRelativeTo(null, "../../foo/bar", "../../sub/../..")
     }
+
+    @Test
+    fun absolutePaths() {
+        val relative = Path("./example")
+        assertTrue(relative.absolute().isAbsolute)
+        assertEquals(relative.absolute().pathString, relative.absolutePathString())
+    }
 }

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-jdk7.txt

@@ -11,6 +11,7 @@ public final class kotlin/io/path/PathsKt {
 	public static final fun fileAttributeViewNotAvailable (Ljava/nio/file/Path;Ljava/lang/Class;)Ljava/lang/Void;
 	public static final fun getExtension (Ljava/nio/file/Path;)Ljava/lang/String;
 	public static final fun getInvariantSeparatorsPath (Ljava/nio/file/Path;)Ljava/lang/String;
+	public static final fun getInvariantSeparatorsPathString (Ljava/nio/file/Path;)Ljava/lang/String;
 	public static final fun getName (Ljava/nio/file/Path;)Ljava/lang/String;
 	public static final fun getNameWithoutExtension (Ljava/nio/file/Path;)Ljava/lang/String;
 	public static final fun listDirectoryEntries (Ljava/nio/file/Path;Ljava/lang/String;)Ljava/util/List;