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.

libraries/stdlib/jvm/test/ExceptionJVMTest.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
@@ -7,6 +7,7 @@ package test.exceptions
 
 import kotlin.test.*
 import test.collections.assertArrayNotSameButEquals
+import test.testOnJvm7AndAbove
 
 import java.io.PrintWriter
 import java.io.*
@@ -17,11 +18,13 @@ class ExceptionJVMTest {
     @Test fun printStackTraceOnRuntimeException() {
         assertPrintStackTrace(RuntimeException("Crikey!"))
         assertPrintStackTraceStream(RuntimeException("Crikey2"))
+        assertToStringWithTrace(RuntimeException("ToString"))
     }
 
     @Test fun printStackTraceOnError() {
         assertPrintStackTrace(Error("Oh dear"))
         assertPrintStackTraceStream(Error("Oh dear2"))
+        assertToStringWithTrace(Error("ToString"))
     }
 
 
@@ -49,6 +52,11 @@ class ExceptionJVMTest {
         comparePrintedThrowableResult(t, content)
     }
 
+    fun assertToStringWithTrace(t: Throwable) {
+        val content = t.toStringWithTrace()
+        comparePrintedThrowableResult(t, content)
+    }
+
     private fun comparePrintedThrowableResult(throwable: Throwable, printedThrowable: CharSequence) {
         val stackTrace = throwable.stackTrace
         val lines = printedThrowable.lines()
@@ -72,4 +80,16 @@ class ExceptionJVMTest {
 
         e1.addSuppressed(e2)
     }
+
+    @Test fun circularCauseStackTrace() {
+        val e1 = Exception("cause")
+        val e2 = Error("induced", e1)
+        e1.initCause(e2)
+        assertSame(e1, e2.cause)
+        assertSame(e2, e1.cause)
+        testOnJvm7AndAbove {
+            val trace = e2.toStringWithTrace()
+            assertTrue("CIRCULAR REFERENCE" in trace, trace)
+        }
+    }
 }

libraries/stdlib/jvm/test/testUtilsJVM.kt

@@ -26,6 +26,11 @@ internal actual inline fun testOnNonJvm6And7(f: () -> Unit) {
         f()
     }
 }
+internal inline fun testOnJvm7AndAbove(f: () -> Unit) {
+    if (!isJava6) {
+        f()
+    }
+}
 public actual fun testOnJvm(action: () -> Unit) = action()
 public actual fun testOnJs(action: () -> Unit) {}