Introduce Path.createParentDirectories function #KT-53263

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

@@ -19,10 +19,10 @@ import java.nio.file.attribute.BasicFileAttributes
  * Note that if this function throws, partial copying may have taken place.
  *
  * Unlike `File.copyRecursively`, if some directories on the way to the [target] are missing, then they won't be created automatically.
- * You can use the following approach to ensure that required intermediate directories are created:
+ * You can use the [createParentDirectories] function to ensure that required intermediate directories are created:
  * ```
  * sourcePath.copyToRecursively(
- *     destinationPath.apply { parent?.createDirectories() },
+ *     destinationPath.createParentDirectories(),
  *     followLinks = false
  * )
  * ```
@@ -93,10 +93,10 @@ public fun Path.copyToRecursively(
  * Note that if this function throws, partial copying may have taken place.
  *
  * Unlike `File.copyRecursively`, if some directories on the way to the [target] are missing, then they won't be created automatically.
- * You can use the following approach to ensure that required intermediate directories are created:
+ * You can use the [createParentDirectories] function to ensure that required intermediate directories are created:
  * ```
  * sourcePath.copyToRecursively(
- *     destinationPath.apply { parent?.createDirectories() },
+ *     destinationPath.createParentDirectories(),
  *     followLinks = false
  * )
  * ```

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

@@ -189,9 +189,9 @@ private object PathRelativizer {
  * Copies a file or directory located by this path to the given [target] path.
  *
  * Unlike `File.copyTo`, if some directories on the way to the [target] are missing, then they won't be created automatically.
- * You can use the following approach to ensure that required intermediate directories are created:
+ * You can use the [createParentDirectories] function to ensure that required intermediate directories are created:
  * ```
- * sourcePath.copyTo(destinationPath.apply { parent?.createDirectories() })
+ * sourcePath.copyTo(destinationPath.createParentDirectories())
  * ```
  *
  * If the [target] path already exists, this function will fail unless [overwrite] argument is set to `true`.
@@ -226,9 +226,9 @@ public inline fun Path.copyTo(target: Path, overwrite: Boolean = false): Path {
  * Copies a file or directory located by this path to the given [target] path.
  *
  * Unlike `File.copyTo`, if some directories on the way to the [target] are missing, then they won't be created automatically.
- * You can use the following approach to ensure that required intermediate directories are created:
+ * You can use the [createParentDirectories] function to ensure that required intermediate directories are created:
  * ```
- * sourcePath.copyTo(destinationPath.apply { parent?.createDirectories() })
+ * sourcePath.copyTo(destinationPath.createParentDirectories())
  * ```
  *
  * If the [target] path already exists, this function will fail unless the
@@ -500,6 +500,8 @@ public inline fun Path.deleteIfExists() =
  *   when creating the directory.
  *
  * @see Files.createDirectory
+ * @see Path.createDirectories
+ * @see Path.createParentDirectories
  */
 @SinceKotlin("1.5")
 @WasExperimental(ExperimentalPathApi::class)
@@ -513,15 +515,20 @@ public inline fun Path.createDirectory(vararg attributes: FileAttribute<*>): Pat
  *
  * If the directory already exists, this function does not throw an exception, unlike [Path.createDirectory].
  *
+ * @return the path of this directory if it already exists or has been created successfully.
+ * The returned path can be converted [Path.toAbsolutePath][to absolute path] if it was relative.
+ *
  * @param attributes an optional list of file attributes to set atomically when creating the directory.
  *
- * @throws FileAlreadyExistsException if there is already a file located by this path
+ * @throws FileAlreadyExistsException if there is already a file located by this path or one of its parent paths
  * (optional specific exception, some implementations may throw more general [IOException]).
  * @throws IOException if an I/O error occurs.
- * @throws UnsupportedOperationException if the [attributes ]array contains an attribute that cannot be set atomically
+ * @throws UnsupportedOperationException if the [attributes] array contains an attribute that cannot be set atomically
  *   when creating the directory.
  *
  * @see Files.createDirectories
+ * @see Path.createDirectory
+ * @see Path.createParentDirectories
  */
 @SinceKotlin("1.5")
 @WasExperimental(ExperimentalPathApi::class)
@@ -530,6 +537,33 @@ public inline fun Path.createDirectory(vararg attributes: FileAttribute<*>): Pat
 public inline fun Path.createDirectories(vararg attributes: FileAttribute<*>): Path =
     Files.createDirectories(this, *attributes)
 
+/**
+ * Ensures that all parent directories of this path exist, creating them if required.
+ *
+ * If the parent directory already exists, this function does nothing.
+ *
+ * Note that the [parent][Path.getParent] directory is not always the directory that contains the entry specified by this path.
+ * For example, the parent of the path `x/y/.` is `x/y`, which is logically the same directory,
+ * and the parent of `x/y/..` (which means just `x/`) is also `x/y`.
+ * Use the function [Path.normalize] to eliminate redundant name elements from the path.
+ *
+ * @param attributes an optional list of file attributes to set atomically when creating the missing parent directories.
+ *
+ * @return this path unchanged if all parent directories already exist or have been created successfully.
+ *
+ * @throws FileAlreadyExistsException if there is already a file located by the [parent][Path.getParent] path or one of its parent paths
+ * (optional specific exception, some implementations may throw more general [IOException]).
+ * @throws IOException if an I/O error occurs.
+ * @throws UnsupportedOperationException if the [attributes] array contains an attribute that cannot be set atomically
+ *   when creating the directory.
+ *
+ * @see Path.getParent
+ * @see Path.createDirectories
+ */
+@SinceKotlin("1.9")
+@Throws(IOException::class)
+public fun Path.createParentDirectories(vararg attributes: FileAttribute<*>): Path =
+    this.apply { parent?.createDirectories(*attributes) }
 
 /**
  * Moves or renames the file located by this path to the [target] path.