kotlin-stdlib/kotlin.io.path

Package-level declarations

Convenient extensions for working with file system using java.nio.file.Path.

Types

CopyActionContext

@ExperimentalPathApi

interface CopyActionContext

Context for the copyAction function passed to Path.copyToRecursively.

Since Kotlin 1.8

CopyActionResult

@ExperimentalPathApi

enum CopyActionResult : Enum<CopyActionResult>

The result of the copyAction function passed to Path.copyToRecursively that specifies further actions when copying an entry.

Since Kotlin 1.8

ExperimentalPathApi

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPEALIAS])

annotation class ExperimentalPathApi

This annotation marks the extensions and top-level functions for working with java.nio.file.Path considered experimental.

Since Kotlin 1.4

FileVisitorBuilder

@ExperimentalPathApi

sealed interface FileVisitorBuilder

The builder to provide implementation of the file visitor that fileVisitor builds.

Since Kotlin 1.7

OnErrorResult

@ExperimentalPathApi

enum OnErrorResult : Enum<OnErrorResult>

The result of the onError function passed to Path.copyToRecursively that specifies further actions when an exception occurs.

Since Kotlin 1.8

PathWalkOption

@ExperimentalPathApi

enum PathWalkOption : Enum<PathWalkOption>

An enumeration to provide walk options for Path.walk function. The options can be combined to form the walk order and behavior needed.

Since Kotlin 1.7

Properties

extension

val Path.extension: String

Returns the extension of this path (not including the dot), or an empty string if it doesn't have one.

Since Kotlin 1.5

invariantSeparatorsPath

@ExperimentalPathApi

val Path.~~invariantSeparatorsPath~~: String

Since Kotlin 1.4

invariantSeparatorsPathString

val Path.invariantSeparatorsPathString: String

Returns the string representation of this path using the invariant separator '/' to separate names in the path.

Since Kotlin 1.5

name

val Path.name: String

Returns the name of the file or directory denoted by this path as a string, or an empty string if this path has zero path elements.

Since Kotlin 1.5

nameWithoutExtension

val Path.nameWithoutExtension: String

Returns the name of this file or directory without an extension, or an empty string if this path has zero path elements.

Since Kotlin 1.5

pathString

val Path.pathString: String

Returns the string representation of this path.

Since Kotlin 1.5

Functions

absolute

inline fun Path.absolute(): Path

Converts this possibly relative path to an absolute path.

Since Kotlin 1.5

absolutePathString

inline fun Path.absolutePathString(): String

Converts this possibly relative path to an absolute path and returns its string representation.

Since Kotlin 1.5

appendBytes

inline fun Path.appendBytes(array: ByteArray)

Appends an array of bytes to the content of this file.

Since Kotlin 1.5

appendLines

inline fun Path.appendLines(lines: Iterable<CharSequence>, charset: Charset = Charsets.UTF_8): Path

Appends the specified collection of char sequences lines to a file terminating each one with the platform's line separator.

Since Kotlin 1.5

inline fun Path.appendLines(lines: Sequence<CharSequence>, charset: Charset = Charsets.UTF_8): Path

Appends the specified sequence of char sequences lines to a file terminating each one with the platform's line separator.

Since Kotlin 1.5

appendText

fun Path.appendText(text: CharSequence, charset: Charset = Charsets.UTF_8)

Appends text to the content of this file using UTF-8 or the specified charset.

Since Kotlin 1.5

bufferedReader

inline fun Path.bufferedReader(charset: Charset = Charsets.UTF_8, bufferSize: Int = DEFAULT_BUFFER_SIZE, vararg options: OpenOption): BufferedReader

Returns a new BufferedReader for reading the content of this file.

Since Kotlin 1.5

bufferedWriter

inline fun Path.bufferedWriter(charset: Charset = Charsets.UTF_8, bufferSize: Int = DEFAULT_BUFFER_SIZE, vararg options: OpenOption): BufferedWriter

Returns a new BufferedWriter for writing the content of this file.

Since Kotlin 1.5

copyTo

inline fun Path.copyTo(target: Path, vararg options: CopyOption): Path

inline fun Path.copyTo(target: Path, overwrite: Boolean = false): Path

Copies a file or directory located by this path to the given target path.

Since Kotlin 1.5

copyToRecursively

@ExperimentalPathApi

fun Path.copyToRecursively(target: Path, onError: (source: Path, target: Path, Exception) -> OnErrorResult = { _, _, exception -> throw exception }, followLinks: Boolean, overwrite: Boolean): Path

@ExperimentalPathApi

fun Path.copyToRecursively(target: Path, onError: (source: Path, target: Path, Exception) -> OnErrorResult = { _, _, exception -> throw exception }, followLinks: Boolean, copyAction: CopyActionContext.(source: Path, target: Path) -> CopyActionResult = { src, dst -> src.copyToIgnoringExistingDirectory(dst, followLinks) }): Path

Recursively copies this directory and its content to the specified destination target path. Note that if this function throws, partial copying may have taken place.

Since Kotlin 1.8

createDirectories

inline fun Path.createDirectories(vararg attributes: FileAttribute<*>): Path

Creates a directory ensuring that all nonexistent parent directories exist by creating them first.

Since Kotlin 1.5

createDirectory

inline fun Path.createDirectory(vararg attributes: FileAttribute<*>): Path

Creates a new directory or throws an exception if there is already a file or directory located by this path.

Since Kotlin 1.5

createFile

inline fun Path.createFile(vararg attributes: FileAttribute<*>): Path

Creates a new and empty file specified by this path, failing if the file already exists.

Since Kotlin 1.5

createLinkPointingTo

inline fun Path.createLinkPointingTo(target: Path): Path

Creates a new link (directory entry) located by this path for the existing file target.

Since Kotlin 1.5

createParentDirectories

fun Path.createParentDirectories(vararg attributes: FileAttribute<*>): Path

Ensures that all parent directories of this path exist, creating them if required.

Since Kotlin 1.9

createSymbolicLinkPointingTo

inline fun Path.createSymbolicLinkPointingTo(target: Path, vararg attributes: FileAttribute<*>): Path

Creates a new symbolic link located by this path to the given target.

Since Kotlin 1.5

createTempDirectory

inline fun createTempDirectory(prefix: String? = null, vararg attributes: FileAttribute<*>): Path

Creates a new directory in the default temp directory, using the given prefix to generate its name.

Since Kotlin 1.5

fun createTempDirectory(directory: Path?, prefix: String? = null, vararg attributes: FileAttribute<*>): Path

Creates a new directory in the specified directory, using the given prefix to generate its name.

Since Kotlin 1.5

createTempFile

inline fun createTempFile(prefix: String? = null, suffix: String? = null, vararg attributes: FileAttribute<*>): Path

Creates an empty file in the default temp directory, using the given prefix and suffix to generate its name.

Since Kotlin 1.5

fun createTempFile(directory: Path?, prefix: String? = null, suffix: String? = null, vararg attributes: FileAttribute<*>): Path

Creates an empty file in the specified directory, using the given prefix and suffix to generate its name.

Since Kotlin 1.5

deleteExisting

inline fun Path.deleteExisting()

Deletes the existing file or empty directory specified by this path.

Since Kotlin 1.5

deleteIfExists

inline fun Path.deleteIfExists(): Boolean

Deletes the file or empty directory specified by this path if it exists.

Since Kotlin 1.5

deleteRecursively

@ExperimentalPathApi

fun Path.deleteRecursively()

Recursively deletes this directory and its content. Note that if this function throws, partial deletion may have taken place.

Since Kotlin 1.8

div

inline operator fun Path.div(other: Path): Path

Resolves the given other path against this path.

Since Kotlin 1.5

inline operator fun Path.div(other: String): Path

Resolves the given other path string against this path.

Since Kotlin 1.5

exists

inline fun Path.exists(vararg options: LinkOption): Boolean

Checks if the file located by this path exists.

Since Kotlin 1.5

fileAttributesView

inline fun <V : FileAttributeView> Path.fileAttributesView(vararg options: LinkOption): V

Returns a file attributes view of a given type V or throws an UnsupportedOperationException if the requested attribute view type is not available..

Since Kotlin 1.5

fileAttributesViewOrNull

inline fun <V : FileAttributeView> Path.fileAttributesViewOrNull(vararg options: LinkOption): V?

Returns a file attributes view of a given type V or null if the requested attribute view type is not available.

Since Kotlin 1.5

fileSize

inline fun Path.fileSize(): Long

Returns the size of a regular file as a Long value of bytes or throws an exception if the file doesn't exist.

Since Kotlin 1.5

fileStore

inline fun Path.fileStore(): FileStore

Returns the FileStore representing the file store where a file is located.

Since Kotlin 1.5

fileVisitor

@ExperimentalPathApi

fun fileVisitor(builderAction: FileVisitorBuilder.() -> Unit): FileVisitor<Path>

Builds a FileVisitor whose implementation is defined in builderAction.

Since Kotlin 1.7

forEachDirectoryEntry

inline fun Path.forEachDirectoryEntry(glob: String = "*", action: (Path) -> Unit)

Performs the given action on each entry in this directory optionally filtered by matching against the specified glob pattern.

Since Kotlin 1.5

forEachLine

inline fun Path.forEachLine(charset: Charset = Charsets.UTF_8, action: (line: String) -> Unit)

Reads this file line by line using the specified charset and calls action for each line. Default charset is UTF-8.

Since Kotlin 1.5

getAttribute

inline fun Path.getAttribute(attribute: String, vararg options: LinkOption): Any?

Reads the value of a file attribute.

Since Kotlin 1.5

getLastModifiedTime

inline fun Path.getLastModifiedTime(vararg options: LinkOption): FileTime

Returns the last modified time of the file located by this path.

Since Kotlin 1.5

getOwner

inline fun Path.getOwner(vararg options: LinkOption): UserPrincipal?

Returns the owner of a file.

Since Kotlin 1.5

getPosixFilePermissions

inline fun Path.getPosixFilePermissions(vararg options: LinkOption): Set<PosixFilePermission>

Returns the POSIX file permissions of the file located by this path.

Since Kotlin 1.5

inputStream

inline fun Path.inputStream(vararg options: OpenOption): InputStream

Constructs a new InputStream of this file and returns it as a result.

Since Kotlin 1.5

isDirectory

inline fun Path.isDirectory(vararg options: LinkOption): Boolean

Checks if the file located by this path is a directory.

Since Kotlin 1.5

isExecutable

inline fun Path.isExecutable(): Boolean

Checks if the file located by this path exists and is executable.

Since Kotlin 1.5

isHidden

inline fun Path.isHidden(): Boolean

Checks if the file located by this path is considered hidden.

Since Kotlin 1.5

isReadable

inline fun Path.isReadable(): Boolean

Checks if the file located by this path exists and is readable.

Since Kotlin 1.5

isRegularFile

inline fun Path.isRegularFile(vararg options: LinkOption): Boolean

Checks if the file located by this path is a regular file.

Since Kotlin 1.5

isSameFileAs

inline fun Path.isSameFileAs(other: Path): Boolean

Checks if the file located by this path points to the same file or directory as other.

Since Kotlin 1.5

isSymbolicLink

inline fun Path.isSymbolicLink(): Boolean

Checks if the file located by this path exists and is a symbolic link.

Since Kotlin 1.5

isWritable

inline fun Path.isWritable(): Boolean

Checks if the file located by this path exists and is writable.

Since Kotlin 1.5

listDirectoryEntries

fun Path.listDirectoryEntries(glob: String = "*"): List<Path>

Returns a list of the entries in this directory optionally filtered by matching against the specified glob pattern.

Since Kotlin 1.5

moveTo

inline fun Path.moveTo(target: Path, vararg options: CopyOption): Path

inline fun Path.moveTo(target: Path, overwrite: Boolean = false): Path

Moves or renames the file located by this path to the target path.

Since Kotlin 1.5

notExists

inline fun Path.notExists(vararg options: LinkOption): Boolean

Checks if the file located by this path does not exist.

Since Kotlin 1.5

outputStream

inline fun Path.outputStream(vararg options: OpenOption): OutputStream

Constructs a new OutputStream of this file and returns it as a result.

Since Kotlin 1.5

Path

inline fun Path(path: String): Path

Converts the provided path string to a Path object of the default filesystem.

Since Kotlin 1.5

inline fun Path(base: String, vararg subpaths: String): Path

Converts the name sequence specified with the base path string and a number of subpaths additional names to a Path object of the default filesystem.

Since Kotlin 1.5

readAttributes

inline fun <A : BasicFileAttributes> Path.readAttributes(vararg options: LinkOption): A

Reads a file's attributes of the specified type A in bulk.

Since Kotlin 1.5

inline fun Path.readAttributes(attributes: String, vararg options: LinkOption): Map<String, Any?>

Reads the specified list of attributes of a file in bulk.

Since Kotlin 1.5

readBytes

inline fun Path.readBytes(): ByteArray

Gets the entire content of this file as a byte array.

Since Kotlin 1.5

reader

inline fun Path.reader(charset: Charset = Charsets.UTF_8, vararg options: OpenOption): InputStreamReader

Returns a new InputStreamReader for reading the content of this file.

Since Kotlin 1.5

readLines

inline fun Path.readLines(charset: Charset = Charsets.UTF_8): List<String>

Reads the file content as a list of lines.

Since Kotlin 1.5

readSymbolicLink

inline fun Path.readSymbolicLink(): Path

Reads the target of a symbolic link located by this path.

Since Kotlin 1.5

readText

fun Path.readText(charset: Charset = Charsets.UTF_8): String

Gets the entire content of this file as a String using UTF-8 or the specified charset.

Since Kotlin 1.5

relativeTo

fun Path.relativeTo(base: Path): Path

Calculates the relative path for this path from a base path.

Since Kotlin 1.5

relativeToOrNull

fun Path.relativeToOrNull(base: Path): Path?

Calculates the relative path for this path from a base path.

Since Kotlin 1.5

relativeToOrSelf

fun Path.relativeToOrSelf(base: Path): Path

Calculates the relative path for this path from a base path.

Since Kotlin 1.5

setAttribute

inline fun Path.setAttribute(attribute: String, value: Any?, vararg options: LinkOption): Path

Sets the value of a file attribute.

Since Kotlin 1.5

setLastModifiedTime

inline fun Path.setLastModifiedTime(value: FileTime): Path

Sets the last modified time attribute for the file located by this path.

Since Kotlin 1.5

setOwner

inline fun Path.setOwner(value: UserPrincipal): Path

Sets the file owner to the specified value.

Since Kotlin 1.5

setPosixFilePermissions

inline fun Path.setPosixFilePermissions(value: Set<PosixFilePermission>): Path

Sets the POSIX file permissions for the file located by this path.

Since Kotlin 1.5

toPath

inline fun URI.toPath(): Path

Converts this URI to a Path object.

Since Kotlin 1.5

useDirectoryEntries

inline fun <T> Path.useDirectoryEntries(glob: String = "*", block: (Sequence<Path>) -> T): T

Calls the block callback with a sequence of all entries in this directory optionally filtered by matching against the specified glob pattern.

Since Kotlin 1.5

useLines

inline fun <T> Path.useLines(charset: Charset = Charsets.UTF_8, block: (Sequence<String>) -> T): T

Calls the block callback giving it a sequence of all the lines in this file and closes the reader once the processing is complete.

Since Kotlin 1.5

visitFileTree

@ExperimentalPathApi

fun Path.visitFileTree(visitor: FileVisitor<Path>, maxDepth: Int = Int.MAX_VALUE, followLinks: Boolean = false)

Visits this directory and all its content with the specified visitor.

Since Kotlin 1.7

@ExperimentalPathApi

fun Path.visitFileTree(maxDepth: Int = Int.MAX_VALUE, followLinks: Boolean = false, builderAction: FileVisitorBuilder.() -> Unit)

Visits this directory and all its content with the FileVisitor defined in builderAction.

Since Kotlin 1.7

walk

@ExperimentalPathApi

fun Path.walk(vararg options: PathWalkOption): Sequence<Path>

Returns a sequence of paths for visiting this directory and all its content.

Since Kotlin 1.7

writeBytes

inline fun Path.writeBytes(array: ByteArray, vararg options: OpenOption)

Writes an array of bytes to this file.

Since Kotlin 1.5

writeLines

inline fun Path.writeLines(lines: Iterable<CharSequence>, charset: Charset = Charsets.UTF_8, vararg options: OpenOption): Path

Write the specified collection of char sequences lines to a file terminating each one with the platform's line separator.

Since Kotlin 1.5

inline fun Path.writeLines(lines: Sequence<CharSequence>, charset: Charset = Charsets.UTF_8, vararg options: OpenOption): Path

Write the specified sequence of char sequences lines to a file terminating each one with the platform's line separator.

Since Kotlin 1.5

writer

inline fun Path.writer(charset: Charset = Charsets.UTF_8, vararg options: OpenOption): OutputStreamWriter

Returns a new OutputStreamWriter for writing the content of this file.

Since Kotlin 1.5

writeText

fun Path.writeText(text: CharSequence, charset: Charset = Charsets.UTF_8, vararg options: OpenOption)

Sets the content of this file as text encoded using UTF-8 or the specified charset.

Since Kotlin 1.5

Thanks for your feedback!

Was this page helpful?