Package kotlin.io

IO API for working with files and streams.

Types

AccessDeniedException

class AccessDeniedException(file: File, other: File?, reason: String?) : FileSystemException

An exception class which is used when we have not enough access for some operation.

FileAlreadyExistsException

class FileAlreadyExistsException(file: File, other: File?, reason: String?) : FileSystemException

An exception class which is used when some file to create or copy to already exists.

FileSystemException

open class FileSystemException(file: File, other: File?, reason: String?) : IOException

A base exception class for file system exceptions.

FileTreeWalk

class FileTreeWalk : Sequence<File>

This class is intended to implement different file traversal methods. It allows to iterate through all files inside a given directory.

FileWalkDirection

enum FileWalkDirection : Enum<FileWalkDirection>

An enumeration to describe possible walk directions. There are two of them: beginning from parents, ending with children, and beginning from children, ending with parents. Both use depth-first search.

NoSuchFileException

class NoSuchFileException(file: File, other: File?, reason: String?) : FileSystemException

An exception class which is used when file to copy does not exist.

OnErrorAction

enum OnErrorAction : Enum<OnErrorAction>

Enum that can be used to specify behaviour of the copyRecursively() function in exceptional conditions.

Functions

appendBytes

fun File.appendBytes(array: ByteArray)

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

appendText

fun File.appendText(text: String, charset: Charset = Charsets.UTF_8)

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

buffered

inline fun InputStream.buffered(bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedInputStream

Creates a buffered input stream wrapping this stream.

inline fun OutputStream.buffered(bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedOutputStream

Creates a buffered output stream wrapping this stream.

inline fun Reader.buffered(bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedReader

Returns a buffered reader wrapping this Reader, or this Reader itself if it is already buffered.

inline fun Writer.buffered(bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedWriter

Returns a buffered writer wrapping this Writer, or this Writer itself if it is already buffered.

bufferedReader

inline fun InputStream.bufferedReader(charset: Charset = Charsets.UTF_8): BufferedReader

Creates a buffered reader on this input stream using UTF-8 or the specified charset.

inline fun File.bufferedReader(charset: Charset = Charsets.UTF_8, bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedReader

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

bufferedWriter

inline fun OutputStream.bufferedWriter(charset: Charset = Charsets.UTF_8): BufferedWriter

Creates a buffered writer on this output stream using UTF-8 or the specified charset.

inline fun File.bufferedWriter(charset: Charset = Charsets.UTF_8, bufferSize: Int = DEFAULT_BUFFER_SIZE): BufferedWriter

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

byteInputStream

inline fun String.byteInputStream(charset: Charset = Charsets.UTF_8): ByteArrayInputStream

Creates a new byte input stream for the string.

copyRecursively

fun File.copyRecursively(target: File, overwrite: Boolean = false, onError: (File, IOException) -> OnErrorAction = { _, exception -> throw exception }): Boolean

Copies this file with all its children to the specified destination target path. If some directories on the way to the destination are missing, then they will be created.

copyTo

fun InputStream.copyTo(out: OutputStream, bufferSize: Int = DEFAULT_BUFFER_SIZE): Long

Copies this stream to the given output stream, returning the number of bytes copied

fun Reader.copyTo(out: Writer, bufferSize: Int = DEFAULT_BUFFER_SIZE): Long

Copies this reader to the given out writer, returning the number of characters copied.

fun File.copyTo(target: File, overwrite: Boolean = false, bufferSize: Int = DEFAULT_BUFFER_SIZE): File

Copies this file to the given target file.

createTempDir

~~fun~~ ~~createTempDir~~(~~prefix~~: String = ~~"tmp"~~, ~~suffix~~: String? = ~~null~~, ~~directory~~: File? = ~~null~~): File

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

createTempFile

~~fun~~ ~~createTempFile~~(~~prefix~~: String = ~~"tmp"~~, ~~suffix~~: String? = ~~null~~, ~~directory~~: File? = ~~null~~): File

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

deleteRecursively

fun File.deleteRecursively(): Boolean

Delete this file with all its children. Note that if this operation fails then partial deletion may have taken place.

endsWith

fun File.endsWith(other: File): Boolean

Determines whether this file path ends with the path of other file.

fun File.endsWith(other: String): Boolean

Determines whether this file belongs to the same root as other and ends with all components of other in the same order. So if other has N components, last N components of this must be the same as in other. For relative other, this can belong to any root.

forEachBlock

fun File.forEachBlock(action: (buffer: ByteArray, bytesRead: Int) -> Unit)

Reads file by byte blocks and calls action for each block read. Block has default size which is implementation-dependent. This functions passes the byte array and amount of bytes in the array to the action function.

fun File.forEachBlock(blockSize: Int, action: (buffer: ByteArray, bytesRead: Int) -> Unit)

Reads file by byte blocks and calls action for each block read. This functions passes the byte array and amount of bytes in the array to the action function.

forEachLine

fun Reader.forEachLine(action: (String) -> Unit)

Iterates through each line of this reader, calls action for each line read and closes the Reader when it's completed.

fun File.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.

inputStream

inline fun File.inputStream(): FileInputStream

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

inline fun ByteArray.inputStream(): ByteArrayInputStream

Creates an input stream for reading data from this byte array.

inline fun ByteArray.inputStream(offset: Int, length: Int): ByteArrayInputStream

Creates an input stream for reading data from the specified portion of this byte array.

iterator

operator fun BufferedInputStream.iterator(): ByteIterator

Returns an Iterator of bytes read from this input stream.

lineSequence

fun BufferedReader.lineSequence(): Sequence<String>

Returns a sequence of corresponding file lines.

normalize

fun File.normalize(): File

Removes all . and resolves all possible .. in this file name. For instance, File("/foo/./bar/gav/../baaz").normalize() is File("/foo/bar/baaz").

outputStream

inline fun File.outputStream(): FileOutputStream

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

expect fun print(message: Any?)

Prints the given message to the standard output stream.

actual inline fun print(message: Any?)

inline fun print(message: Boolean)

inline fun print(message: Byte)

inline fun print(message: Char)

inline fun print(message: CharArray)

inline fun print(message: Double)

inline fun print(message: Float)

inline fun print(message: Int)

inline fun print(message: Long)

inline fun print(message: Short)

Prints the given message to the standard output stream.

actual fun print(message: Any?)

Prints the given message to the standard output stream.

actual fun print(message: Any?)

external fun print(message: String)

Prints the given message to the standard output stream.

println

expect fun println()

Prints the line separator to the standard output stream.

expect fun println(message: Any?)

Prints the given message and the line separator to the standard output stream.

actual inline fun println()

Prints the line separator to the standard output stream.

actual inline fun println(message: Any?)

inline fun println(message: Boolean)

inline fun println(message: Byte)

inline fun println(message: Char)

inline fun println(message: CharArray)

inline fun println(message: Double)

inline fun println(message: Float)

inline fun println(message: Int)

inline fun println(message: Long)

inline fun println(message: Short)

Prints the given message and the line separator to the standard output stream.

actual fun println()

Prints the line separator to the standard output stream.

actual fun println(message: Any?)

Prints the given message and the line separator to the standard output stream.

actual external fun println()

Prints the line separator to the standard output stream.

actual fun println(message: Any?)

external fun println(message: String)

Prints the given message and the line separator to the standard output stream.

printWriter

inline fun File.printWriter(charset: Charset = Charsets.UTF_8): PrintWriter

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

readBytes

fun File.readBytes(): ByteArray

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

fun InputStream.readBytes(): ByteArray

Reads this stream completely into a byte array.

Since Kotlin

1.3

fun URL.readBytes(): ByteArray

Reads the entire content of the URL as byte array.

@DeprecatedSinceKotlin(warningSince = "1.3", errorSince = "1.5")

~~fun~~ InputStream.~~readBytes~~(~~estimatedSize~~: Int = ~~DEFAULT_BUFFER_SIZE~~): ByteArray

Reads this stream completely into a byte array.

reader

inline fun String.reader(): StringReader

Creates a new reader for the string.

inline fun File.reader(charset: Charset = Charsets.UTF_8): InputStreamReader

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

inline fun InputStream.reader(charset: Charset = Charsets.UTF_8): InputStreamReader

Creates a reader on this input stream using UTF-8 or the specified charset.

readLine

fun readLine(): String?

Reads a line of input from the standard input stream.

external fun readLine(): String?

Reads a line of input from the standard input stream.

readLines

fun Reader.readLines(): List<String>

Reads this reader content as a list of lines.

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

Reads the file content as a list of lines.

readText

fun Reader.readText(): String

Reads this reader completely as a String.

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

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

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

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

relativeTo

fun File.relativeTo(base: File): File

Calculates the relative path for this file from base file. Note that the base file is treated as a directory. If this file matches the base file, then a File with empty path will be returned.

relativeToOrNull

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

Calculates the relative path for this file from base file. Note that the base file is treated as a directory. If this file matches the base file, then a File with empty path will be returned.

relativeToOrSelf

fun File.relativeToOrSelf(base: File): File

Calculates the relative path for this file from base file. Note that the base file is treated as a directory. If this file matches the base file, then a File with empty path will be returned.

resolve

fun File.resolve(relative: File): File

Adds relative file to this, considering this as a directory. If relative has a root, relative is returned back. For instance, File("/foo/bar").resolve(File("gav")) is File("/foo/bar/gav"). This function is complementary with relativeTo, so f.resolve(g.relativeTo(f)) == g should be always true except for different roots case.

fun File.resolve(relative: String): File

Adds relative name to this, considering this as a directory. If relative has a root, relative is returned back. For instance, File("/foo/bar").resolve("gav") is File("/foo/bar/gav").

resolveSibling

fun File.resolveSibling(relative: File): File

Adds relative file to this parent directory. If relative has a root or this has no parent directory, relative is returned back. For instance, File("/foo/bar").resolveSibling(File("gav")) is File("/foo/gav").

fun File.resolveSibling(relative: String): File

Adds relative name to this parent directory. If relative has a root or this has no parent directory, relative is returned back. For instance, File("/foo/bar").resolveSibling("gav") is File("/foo/gav").

startsWith

fun File.startsWith(other: File): Boolean

fun File.startsWith(other: String): Boolean

Determines whether this file belongs to the same root as other and starts with all components of other in the same order. So if other has N components, first N components of this must be the same as in other.

toRelativeString

fun File.toRelativeString(base: File): String

Calculates the relative path for this file from base file. Note that the base file is treated as a directory. If this file matches the base file, then an empty string will be returned.

use

inline fun <T : Closeable?, R> T.use(block: (T) -> R): R

Executes the given block function on this resource and then closes it down correctly whether an exception is thrown or not.

useLines

inline fun <T> Reader.useLines(block: (Sequence<String>) -> T): T

inline fun <T> File.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.

walk

fun File.walk(direction: FileWalkDirection = FileWalkDirection.TOP_DOWN): FileTreeWalk

Gets a sequence for visiting this directory and all its content.

walkBottomUp

fun File.walkBottomUp(): FileTreeWalk

Gets a sequence for visiting this directory and all its content in bottom-up order. Depth-first search is used and directories are visited after all their files.

walkTopDown

fun File.walkTopDown(): FileTreeWalk

Gets a sequence for visiting this directory and all its content in top-down order. Depth-first search is used and directories are visited before all their files.

writeBytes

fun File.writeBytes(array: ByteArray)

Sets the content of this file as an array of bytes. If this file already exists, it becomes overwritten.

writer

inline fun File.writer(charset: Charset = Charsets.UTF_8): OutputStreamWriter

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

inline fun OutputStream.writer(charset: Charset = Charsets.UTF_8): OutputStreamWriter

Creates a writer on this output stream using UTF-8 or the specified charset.

writeText

fun File.writeText(text: String, charset: Charset = Charsets.UTF_8)

Sets the content of this file as text encoded using UTF-8 or specified charset. If this file exists, it becomes overwritten.

Properties

DEFAULT_BUFFER_SIZE

const val DEFAULT_BUFFER_SIZE: Int

Returns the default buffer size when working with buffered streams.

extension

val File.extension: String

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

invariantSeparatorsPath

val File.invariantSeparatorsPath: String

Returns path of this File using the invariant separator '/' to separate the names in the name sequence.

isRooted

val File.isRooted: Boolean

Determines whether this file has a root or it represents a relative path.

nameWithoutExtension

val File.nameWithoutExtension: String

Returns file's name without an extension.