From 802ca5476d3255a2a7e412272a0270e6f38467ce Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Wed, 27 May 2015 23:28:06 +0300
Subject: [PATCH] Clarify requirements for limit parameter in split method.
 Provide replacement for deprecated split(regex: String).

---
 libraries/stdlib/src/kotlin/text/Strings.kt        | 3 +++
 libraries/stdlib/src/kotlin/text/StringsJVM.kt     | 7 ++++---
 libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt | 5 +++--
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/text/Strings.kt b/libraries/stdlib/src/kotlin/text/Strings.kt
index cda0138110e..da432ddd0a9 100644
--- a/libraries/stdlib/src/kotlin/text/Strings.kt
+++ b/libraries/stdlib/src/kotlin/text/Strings.kt
@@ -947,6 +947,9 @@ public fun String.split(vararg delimiters: Char, ignoreCase: Boolean = false, li
 
 /**
  * Splits this string around matches of the given regular expression.
+ *
+ * @param limit Non-negative value specifying the maximum number of substrings to return.
+ * Zero by default means no limit is set.
  */
 public fun String.split(pattern: Regex, limit: Int = 0): List<String> = pattern.split(this, limit)
 
diff --git a/libraries/stdlib/src/kotlin/text/StringsJVM.kt b/libraries/stdlib/src/kotlin/text/StringsJVM.kt
index 030c12497b4..8031059ffcd 100644
--- a/libraries/stdlib/src/kotlin/text/StringsJVM.kt
+++ b/libraries/stdlib/src/kotlin/text/StringsJVM.kt
@@ -120,7 +120,8 @@ public fun String.format(locale: Locale, vararg args : Any?) : String = java.lan
 /**
  * Splits this string around matches of the given regular expression.
 
- * @param limit The maximum number of substrings to return. Zero by default means no limit is set.
+ * @param limit Non-negative value specifying the maximum number of substrings to return.
+ * Zero by default means no limit is set.
  */
 public fun String.split(regex: Pattern, limit: Int = 0): List<String>
 {
@@ -130,13 +131,13 @@ public fun String.split(regex: Pattern, limit: Int = 0): List<String>
 /**
  * Splits this string around matches of the given regular expression.
  */
-deprecated("Convert String argument to regex with toRegex or use splitBy instead. Please note the change of return type and empty elements handling.")
+deprecated("Convert String argument to regex with toRegex or use splitBy instead for literal delimiters. Please note the change of return type.", ReplaceWith("split(regex.toRegex()).toTypedArray()"))
 public fun String.split(regex: String): Array<String> = (this as java.lang.String).split(regex)
 
 /**
  * Splits this string into at most [limit] chunks around matches of the given regular expression.
  */
-deprecated("Convert String argument to regex with toRegex or use splitBy instead. Please note the change of return type and limit parameter restrictions.")
+deprecated("Convert String argument to regex with toRegex or use splitBy instead for literal delimiters. Please note the change of return type and the restriction of limit to be non-negative.", ReplaceWith("split(regex.toRegex(), limit.coerceAtLeast(0)).toTypedArray()"))
 public fun String.split(regex: String, limit: Int): Array<String> = (this as java.lang.String).split(regex, limit)
 
 /**
diff --git a/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt b/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt
index 57784c56d2f..594aaa23a48 100644
--- a/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt
+++ b/libraries/stdlib/src/kotlin/text/regex/RegexJVM.kt
@@ -173,9 +173,10 @@ public class Regex internal (private val nativePattern: Pattern) {
 
 
     /**
-     * Splits this string around matches of the given regular expression.
+     * Splits the [input] CharSequence around matches of this regular expression.
      *
-     * @param limit The maximum number of times the split can occur.
+     * @param limit Non-negative value specifying the maximum number of substrings the string can be split to.
+     * Zero by default means no limit is set.
      */
     public fun split(input: CharSequence, limit: Int = 0): List<String> {
         require(limit >= 0, { "Limit must be non-negative, but was $limit" } )