From 0634351fbcb93b238a0a37569adff309107fcd23 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Fri, 20 Nov 2020 05:54:36 +0300 Subject: [PATCH] Introduce pathString/absolute/absolutePathString Rename invariantSeparatorsPath to invariantSeparatorsPathString to have more consistent names of methods returning path strings. KT-19192 --- .../jdk7/src/kotlin/io/path/PathUtils.kt | 55 ++++++++++++++++++- .../stdlib/jdk7/test/PathExtensionsTest.kt | 15 +++-- .../kotlin-stdlib-jdk7.txt | 1 + 3 files changed, 64 insertions(+), 7 deletions(-) diff --git a/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt b/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt index 17536f48ebc..1ee2f7c19fb 100644 --- a/libraries/stdlib/jdk7/src/kotlin/io/path/PathUtils.kt +++ b/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. diff --git a/libraries/stdlib/jdk7/test/PathExtensionsTest.kt b/libraries/stdlib/jdk7/test/PathExtensionsTest.kt index 7c14e214b03..c4d875c2da1 100644 --- a/libraries/stdlib/jdk7/test/PathExtensionsTest.kt +++ b/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()) + } } diff --git a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-jdk7.txt b/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-jdk7.txt index e05528a7486..024e3f41c31 100644 --- a/libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-jdk7.txt +++ b/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;