Introduce Throwable.toStringWithTrace

#KT-37603

libraries/stdlib/jvm/src/kotlin/util/Exceptions.kt

@@ -10,24 +10,25 @@ package kotlin
 
 import java.io.PrintStream
 import java.io.PrintWriter
+import java.io.StringWriter
 import kotlin.internal.*
 
 /**
- * Prints the stack trace of this throwable to the standard output.
+ * Prints the [detailed description][Throwable.toStringWithTrace] of this throwable to the standard error output.
  */
 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") // to be used when no member available
 @kotlin.internal.InlineOnly
 public inline fun Throwable.printStackTrace(): Unit = (this as java.lang.Throwable).printStackTrace()
 
 /**
- * Prints the stack trace of this throwable to the specified [writer].
+ * Prints the [detailed description][Throwable.toStringWithTrace] of this throwable to the specified [writer].
  */
 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") // to be used when no member available
 @kotlin.internal.InlineOnly
 public inline fun Throwable.printStackTrace(writer: PrintWriter): Unit = (this as java.lang.Throwable).printStackTrace(writer)
 
 /**
- * Prints the stack trace of this throwable to the specified [stream].
+ * Prints the [detailed description][Throwable.toStringWithTrace] of this throwable to the specified [stream].
  */
 @Suppress("EXTENSION_SHADOWED_BY_MEMBER") // to be used when no member available
 @kotlin.internal.InlineOnly
@@ -41,6 +42,24 @@ public inline fun Throwable.printStackTrace(stream: PrintStream): Unit = (this a
 public val Throwable.stackTrace: Array<StackTraceElement>
     get() = (this as java.lang.Throwable).stackTrace!!
 
+/**
+ * Returns the detailed description of this throwable with its stack trace.
+ *
+ * The detailed description includes:
+ * - the short description (see [Throwable.toString]) of this throwable;
+ * - the complete stack trace;
+ * - detailed descriptions of the exceptions that were [suppressed][suppressedExceptions] in order to deliver this exception;
+ * - the detailed description of each throwable in the [Throwable.cause] chain.
+ */
+@SinceKotlin("1.4")
+public actual fun Throwable.toStringWithTrace(): String {
+    val sw = StringWriter()
+    val pw = PrintWriter(sw)
+    printStackTrace(pw)
+    pw.flush()
+    return sw.toString()
+}
+
 /**
  * When supported by the platform, adds the specified exception to the list of exceptions that were
  * suppressed in order to deliver this exception.