[stdlib] KT-55619 provide samples and extend documentation for String.format

libraries/stdlib/jvm/src/kotlin/text/StringsJVM.kt

@@ -325,30 +325,54 @@ public actual inline fun String.toCharArray(
 }
 
 /**
- * Uses this string as a format string and returns a string obtained by substituting the specified arguments,
+ * Uses this string as a format string and returns a string obtained
+ * by substituting format specifiers in the format string with the provided arguments,
  * using the default locale.
+ *
+ * See [java.util.Formatter] class documentation
+ * for the syntax of format specifiers for the format string.
+ *
+ * @sample samples.text.Strings.formatExtension
  */
 @kotlin.internal.InlineOnly
 public inline fun String.format(vararg args: Any?): String = java.lang.String.format(this, *args)
 
 /**
- * Uses the provided [format] as a format string and returns a string obtained by substituting the specified arguments,
+ * Uses the provided [format] as a format string and returns a string obtained
+ * by substituting format specifiers in the format string with the provided arguments,
  * using the default locale.
+ *
+ * See [java.util.Formatter] class documentation
+ * for the syntax of format specifiers for the format string.
+ *
+ * @sample samples.text.Strings.formatStatic
  */
 @kotlin.internal.InlineOnly
 public inline fun String.Companion.format(format: String, vararg args: Any?): String = java.lang.String.format(format, *args)
 
 /**
- * Uses this string as a format string and returns a string obtained by substituting the specified arguments,
+ * Uses this string as a format string and returns a string obtained
+ * by substituting format specifiers in the format string with the provided arguments,
  * using the specified locale. If [locale] is `null` then no localization is applied.
+ *
+ * See [java.util.Formatter] class documentation
+ * for the syntax of format specifiers for the format string.
+ *
+ * @sample samples.text.Strings.formatWithLocaleExtension
  */
 @SinceKotlin("1.4")
 @kotlin.internal.InlineOnly
 public inline fun String.format(locale: Locale?, vararg args: Any?): String = java.lang.String.format(locale, this, *args)
 
 /**
- * Uses the provided [format] as a format string and returns a string obtained by substituting the specified arguments,
+ * Uses the provided [format] as a format string and returns a string obtained
+ * by substituting format specifiers in the format string with the provided arguments,
  * using the specified locale. If [locale] is `null` then no localization is applied.
+ *
+ * See [java.util.Formatter] class documentation
+ * for the syntax of format specifiers for the format string.
+ *
+ * @sample samples.text.Strings.formatWithLocaleStatic
  */
 @SinceKotlin("1.4")
 @kotlin.internal.InlineOnly

libraries/stdlib/samples/test/samples/text/strings.kt

@@ -507,4 +507,42 @@ class Strings {
 
         assertPrints(mixedColor, "brown&blue")
     }
+
+    @Sample
+    fun formatStatic() {
+        // format negative number in parentheses
+        val negativeNumberInParentheses = String.format("%(d means %1\$d", -31416)
+        assertPrints(negativeNumberInParentheses, "(31416) means -31416")
+    }
+
+    @Sample
+    fun formatExtension() {
+        // format negative number in parentheses
+        val negativeNumberInParentheses = "%(d means %1\$d".format(-31416)
+        assertPrints(negativeNumberInParentheses, "(31416) means -31416")
+    }
+
+    @Sample
+    fun formatWithLocaleStatic() {
+        // format with German conventions
+        val withGermanThousandsSeparator = String.format(Locale.GERMANY, "%,d", 12345)
+        assertPrints(withGermanThousandsSeparator, "12.345")
+
+        // format with US conventions
+        val withUSThousandsSeparator = String.format(Locale.US, "%,d", 12345)
+        assertPrints(withUSThousandsSeparator, "12,345")
+    }
+
+    @Sample
+    fun formatWithLocaleExtension() {
+        // format with German conventions
+        val withGermanThousandsSeparator = "%,d".format(Locale.GERMANY, 12345)
+        assertPrints(withGermanThousandsSeparator, "12.345")
+        // 12.345
+
+        // format with US conventions
+        val withUSThousandsSeparator = "%,d".format(Locale.US, 12345)
+        assertPrints(withUSThousandsSeparator, "12,345")
+    }
+
 }