diff --git a/.idea/ant.xml b/.idea/ant.xml
index c497b47b130..7a011c30abc 100644
--- a/.idea/ant.xml
+++ b/.idea/ant.xml
@@ -16,7 +16,7 @@
-
+
diff --git a/libraries/build-docs.xml b/libraries/build-docs.xml
index e5c787c6667..844fa1a71bd 100644
--- a/libraries/build-docs.xml
+++ b/libraries/build-docs.xml
@@ -2,7 +2,12 @@
-
+
+
+
+
+
+
diff --git a/libraries/stdlib/src/Module.md b/libraries/stdlib/src/Module.md
index 04a981ad1bf..a4934191cf9 100644
--- a/libraries/stdlib/src/Module.md
+++ b/libraries/stdlib/src/Module.md
@@ -60,6 +60,10 @@ Java reflection.
Functions for writing tests.
+# Package kotlin.text
+
+Functions for working with text and regular expressions.
+
# Package kotlin.util
Utility functions.
diff --git a/libraries/stdlib/src/generated/_Generators.kt b/libraries/stdlib/src/generated/_Generators.kt
index 00dc753cc9a..ab12fec0211 100644
--- a/libraries/stdlib/src/generated/_Generators.kt
+++ b/libraries/stdlib/src/generated/_Generators.kt
@@ -392,8 +392,8 @@ public fun Stream.merge(stream: Stream, transform: (T, R) -> V):
/**
* Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
*/
public inline fun Array.partition(predicate: (T) -> Boolean): Pair, List> {
val first = ArrayList()
@@ -410,8 +410,8 @@ public inline fun Array.partition(predicate: (T) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -428,8 +428,8 @@ public inline fun BooleanArray.partition(predicate: (Boolean) -> Boolean): Pair<
/**
* Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
*/
public inline fun ByteArray.partition(predicate: (Byte) -> Boolean): Pair, List> {
val first = ArrayList()
@@ -446,8 +446,8 @@ public inline fun ByteArray.partition(predicate: (Byte) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -464,8 +464,8 @@ public inline fun CharArray.partition(predicate: (Char) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -482,8 +482,8 @@ public inline fun DoubleArray.partition(predicate: (Double) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -500,8 +500,8 @@ public inline fun FloatArray.partition(predicate: (Float) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -518,8 +518,8 @@ public inline fun IntArray.partition(predicate: (Int) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -536,8 +536,8 @@ public inline fun LongArray.partition(predicate: (Long) -> Boolean): Pair Boolean): Pair, List> {
val first = ArrayList()
@@ -554,8 +554,8 @@ public inline fun ShortArray.partition(predicate: (Short) -> Boolean): Pair Iterable.partition(predicate: (T) -> Boolean): Pair, List> {
val first = ArrayList()
@@ -572,8 +572,8 @@ public inline fun Iterable.partition(predicate: (T) -> Boolean): Pair Sequence.partition(predicate: (T) -> Boolean): Pair, List> {
val first = ArrayList()
@@ -592,8 +592,8 @@ public inline fun Sequence.partition(predicate: (T) -> Boolean): Pair and respective functions")
/**
* Splits original collection into pair of collections,
- * where *first* collection contains elements for which [predicate] yielded [true],
- * while *second* collection contains elements for which [predicate] yielded [false].
+ * where *first* collection contains elements for which [predicate] yielded `true`,
+ * while *second* collection contains elements for which [predicate] yielded `false`.
*/
public inline fun Stream.partition(predicate: (T) -> Boolean): Pair, List> {
val first = ArrayList()
@@ -610,8 +610,8 @@ public inline fun Stream.partition(predicate: (T) -> Boolean): Pair Boolean): Pair {
val first = StringBuilder()
@@ -627,7 +627,7 @@ public inline fun String.partition(predicate: (Char) -> Boolean): Pair Array.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -637,7 +637,7 @@ public fun Array.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun BooleanArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -647,7 +647,7 @@ public fun BooleanArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun ByteArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -657,7 +657,7 @@ public fun ByteArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun CharArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -667,7 +667,7 @@ public fun CharArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun DoubleArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -677,7 +677,7 @@ public fun DoubleArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun FloatArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -687,7 +687,7 @@ public fun FloatArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun IntArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -697,7 +697,7 @@ public fun IntArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun LongArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -707,7 +707,7 @@ public fun LongArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun ShortArray.plus(array: Array): List {
val answer = ArrayList(size() + array.size())
@@ -717,7 +717,7 @@ public fun ShortArray.plus(array: Array): List {
}
/**
- * Returns a list containing all elements of original collection and then all elements of the given [collection].
+ * Returns a list containing all elements of original collection and then all elements of the given [array].
*/
public fun Iterable.plus(array: Array): List {
val answer = ArrayList(collectionSizeOrDefault(10) + array.size())
diff --git a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt
index 31541e22b02..729e9dddb36 100644
--- a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt
+++ b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt
@@ -9,48 +9,48 @@ import kotlin.jvm.internal.Intrinsic
/**
* Returns an array containing the specified elements.
*/
-[Intrinsic("kotlin.arrays.array")] public fun arrayOf(vararg t : T) : Array = t as Array
+@Intrinsic("kotlin.arrays.array") public fun arrayOf(vararg t : T) : Array = t as Array
// "constructors" for primitive types array
/**
* Returns an array containing the specified [Double] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun doubleArrayOf(vararg content : Double) : DoubleArray = content
+@Intrinsic("kotlin.arrays.array") public fun doubleArrayOf(vararg content : Double) : DoubleArray = content
/**
* Returns an array containing the specified [Float] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun floatArrayOf(vararg content : Float) : FloatArray = content
+@Intrinsic("kotlin.arrays.array") public fun floatArrayOf(vararg content : Float) : FloatArray = content
/**
* Returns an array containing the specified [Long] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun longArrayOf(vararg content : Long) : LongArray = content
+@Intrinsic("kotlin.arrays.array") public fun longArrayOf(vararg content : Long) : LongArray = content
/**
* Returns an array containing the specified [Int] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun intArrayOf(vararg content : Int) : IntArray = content
+@Intrinsic("kotlin.arrays.array") public fun intArrayOf(vararg content : Int) : IntArray = content
/**
* Returns an array containing the specified characters.
*/
-[Intrinsic("kotlin.arrays.array")] public fun charArrayOf(vararg content : Char) : CharArray = content
+@Intrinsic("kotlin.arrays.array") public fun charArrayOf(vararg content : Char) : CharArray = content
/**
* Returns an array containing the specified [Short] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun shortArrayOf(vararg content : Short) : ShortArray = content
+@Intrinsic("kotlin.arrays.array") public fun shortArrayOf(vararg content : Short) : ShortArray = content
/**
* Returns an array containing the specified [Byte] numbers.
*/
-[Intrinsic("kotlin.arrays.array")] public fun byteArrayOf(vararg content : Byte) : ByteArray = content
+@Intrinsic("kotlin.arrays.array") public fun byteArrayOf(vararg content : Byte) : ByteArray = content
/**
* Returns an array containing the specified boolean values.
*/
-[Intrinsic("kotlin.arrays.array")] public fun booleanArrayOf(vararg content : Boolean) : BooleanArray = content
+@Intrinsic("kotlin.arrays.array") public fun booleanArrayOf(vararg content : Boolean) : BooleanArray = content
/**
diff --git a/libraries/stdlib/src/kotlin/collections/Sequence.kt b/libraries/stdlib/src/kotlin/collections/Sequence.kt
index 7d9a1d1a6db..9326514dec7 100644
--- a/libraries/stdlib/src/kotlin/collections/Sequence.kt
+++ b/libraries/stdlib/src/kotlin/collections/Sequence.kt
@@ -19,6 +19,9 @@ public interface Stream {
*/
public interface Sequence : Stream
+/**
+ * Converts a stream to a sequence.
+ */
public fun Stream.toSequence(): Sequence = object : Sequence {
override fun iterator(): Iterator = this@toSequence.iterator()
}
diff --git a/libraries/stdlib/src/kotlin/dom/Dom.kt b/libraries/stdlib/src/kotlin/dom/Dom.kt
index aba6d55b467..3defb5fa65c 100644
--- a/libraries/stdlib/src/kotlin/dom/Dom.kt
+++ b/libraries/stdlib/src/kotlin/dom/Dom.kt
@@ -71,7 +71,7 @@ public fun Element?.childElements(name: String): List {
return children().filter{ it.nodeType == Node.ELEMENT_NODE && it.nodeName == name }.map { it as Element }
}
-/** The descendent elements of this document */
+/** The descendant elements of this document */
public val Document?.elements: List
get() = this?.getElementsByTagName("*").toElementList()
@@ -233,7 +233,7 @@ private class ElementListAsList(private val nodeList: NodeList) : AbstractList = NextSiblings(this)
private class NextSiblings(private var node: Node) : Iterable {
@@ -250,7 +250,7 @@ private class NextSiblings(private var node: Node) : Iterable {
}
}
-/** Returns an [[Iterator]] over the next siblings of this node */
+/** Returns an [Iterator] over the next siblings of this node */
public fun Node.previousSiblings(): Iterable = PreviousSiblings(this)
private class PreviousSiblings(private var node: Node) : Iterable {
diff --git a/libraries/stdlib/src/kotlin/dom/DomJVM.kt b/libraries/stdlib/src/kotlin/dom/DomJVM.kt
index 198bee65762..58ec14b78cf 100644
--- a/libraries/stdlib/src/kotlin/dom/DomJVM.kt
+++ b/libraries/stdlib/src/kotlin/dom/DomJVM.kt
@@ -123,10 +123,10 @@ public val Node.innerHTML: String
public val NodeList.outerHTML: String
get() = toList().map { it.innerHTML }.join("")
-/** Returns an [[Iterator]] of all the next [[Element]] siblings */
+/** Returns an [Iterator] of all the next [Element] siblings */
public fun Node.nextElements(): List = nextSiblings().filterIsInstance(javaClass())
-/** Returns an [[Iterator]] of all the previous [[Element]] siblings */
+/** Returns an [Iterator] of all the previous [Element] siblings */
public fun Node.previousElements(): List = previousSiblings().filterIsInstance(javaClass())
@@ -157,14 +157,14 @@ public fun createDocument(builderFactory: DocumentBuilderFactory = defaultDocume
}
/**
- * Returns the default [[DocumentBuilderFactory]]
+ * Returns the default [DocumentBuilderFactory]
*/
public fun defaultDocumentBuilderFactory(): DocumentBuilderFactory {
return DocumentBuilderFactory.newInstance()!!
}
/**
- * Returns the default [[DocumentBuilder]]
+ * Returns the default [DocumentBuilder]
*/
public fun defaultDocumentBuilder(builderFactory: DocumentBuilderFactory = defaultDocumentBuilderFactory()): DocumentBuilder {
return builderFactory.newDocumentBuilder()
@@ -219,7 +219,7 @@ public fun Node.toXmlString(xmlDeclaration: Boolean): String {
return writer.toString()
}
-/** Converts the node to an XML String and writes it to the given [[Writer]] */
+/** Converts the node to an XML String and writes it to the given [Writer] */
public fun Node.writeXmlString(writer: Writer, xmlDeclaration: Boolean): Unit {
val transformer = createTransformer()
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, if (xmlDeclaration) "no" else "yes")
diff --git a/libraries/stdlib/src/kotlin/io/Exceptions.kt b/libraries/stdlib/src/kotlin/io/Exceptions.kt
index ed6acd54da3..6b0736f0014 100644
--- a/libraries/stdlib/src/kotlin/io/Exceptions.kt
+++ b/libraries/stdlib/src/kotlin/io/Exceptions.kt
@@ -16,6 +16,9 @@ private fun constructMessage(file: File, other: File?, reason: String?): String
/**
* A base exception class for file system exceptions.
+ * @property file the file on which the failed operation was performed.
+ * @property other the second file involved in the operation, if any (for example, the target of a copy or move)
+ * @property reason the description of the error
*/
open public class FileSystemException(public val file: File,
public val other: File? = null,
diff --git a/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt b/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt
index 28df4e818a5..d10ebd405e7 100644
--- a/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt
+++ b/libraries/stdlib/src/kotlin/io/files/FilePathComponents.kt
@@ -77,9 +77,23 @@ public val File.root: File?
return if (name.length() > 0) File(name) else null
}
+/**
+ * Represents the path to a file as a collection of directories.
+ *
+ * @property rootName the name of the root of the path (for example, `/` or `C:`).
+ * @property fileList the list of [File] objects representing every directory in the path to the file,
+ * up to an including the file itself.
+ */
public data class FilePathComponents(public val rootName: String, public val fileList: List) {
+ /**
+ * Returns the number of elements in the path to the file.
+ */
public fun size(): Int = fileList.size()
+ /**
+ * Returns a sub-path of the path, starting with the directory at the specified [beginIndex] and up
+ * to the specified [endIndex].
+ */
public fun subPath(beginIndex: Int, endIndex: Int): File {
if (beginIndex < 0 || beginIndex > endIndex || endIndex > size())
throw IllegalArgumentException()
@@ -88,6 +102,10 @@ public data class FilePathComponents(public val rootName: String, public val fil
}
}
+/**
+ * Splits the file into path components (the names of containing directories and the name of the file
+ * itself) and returns the resulting collection of components.
+ */
public fun File.filePathComponents(): FilePathComponents {
val path = separatorsToSystem()
val rootName = path.getRootName()
diff --git a/libraries/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt b/libraries/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt
index 6f2378e94c5..55b19030c38 100644
--- a/libraries/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt
+++ b/libraries/stdlib/src/kotlin/jvm/internal/unsafe/monitor.kt
@@ -19,9 +19,9 @@ package kotlin.jvm.internal.unsafe
import kotlin.jvm.internal.Intrinsic
/** @suppress */
-[Intrinsic("kotlin.jvm.internal.unsafe.monitorEnter")]
+@Intrinsic("kotlin.jvm.internal.unsafe.monitorEnter")
public fun monitorEnter(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")
/** @suppress */
-[Intrinsic("kotlin.jvm.internal.unsafe.monitorExit")]
+@Intrinsic("kotlin.jvm.internal.unsafe.monitorExit")
public fun monitorExit(monitor: Any): Unit = throw UnsupportedOperationException("This function can only be used privately")
diff --git a/libraries/stdlib/src/kotlin/util/JLangJVM.kt b/libraries/stdlib/src/kotlin/util/JLangJVM.kt
index 03631ace49c..5cdc5a48d09 100644
--- a/libraries/stdlib/src/kotlin/util/JLangJVM.kt
+++ b/libraries/stdlib/src/kotlin/util/JLangJVM.kt
@@ -30,13 +30,13 @@ public annotation class throws(public vararg val exceptionClasses: KClass T.javaClass : Class
+@Intrinsic("kotlin.javaClass.property") public val T.javaClass : Class
get() = (this as java.lang.Object).getClass() as Class
/**
* Returns the Java class for the specified type.
*/
-[Intrinsic("kotlin.javaClass.function")] public fun javaClass(): Class = null as Class
+@Intrinsic("kotlin.javaClass.function") public fun javaClass(): Class = null as Class
/**
* Executes the given function [block] while holding the monitor of the given object [lock].
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
index d0ad881be7b..1a73f95f9d2 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt
@@ -60,7 +60,7 @@ fun generators(): List {
templates add f("plus(array: Array)") {
exclude(Strings, Sequences)
- doc { "Returns a list containing all elements of original collection and then all elements of the given [collection]." }
+ doc { "Returns a list containing all elements of original collection and then all elements of the given [array]." }
returns("List")
body {
"""
@@ -108,8 +108,8 @@ fun generators(): List {
doc {
"""
Splits original collection into pair of collections,
- where *first* collection contains elements for which [predicate] yielded [true],
- while *second* collection contains elements for which [predicate] yielded [false].
+ where *first* collection contains elements for which [predicate] yielded `true`,
+ while *second* collection contains elements for which [predicate] yielded `false`.
"""
}
// TODO: Sequence variant