Add samples (#154)

Author: fzhinkin

bytestring/build.gradle.kts

@@ -76,5 +76,7 @@ tasks.withType<DokkaTaskPartial>().configureEach {
             suppress.set(true)
             matchingRegex.set(".*unsafe.*")
         }
+
+        samples.from("common/test/samples/samples.kt")
     }
 }

bytestring/common/src/ByteString.kt

@@ -28,6 +28,8 @@ import kotlin.math.min
  * Wraps given [bytes] into a byte string.
  *
  * @param bytes a sequence of bytes to be wrapped.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.constructionFromBytesSample
  */
 public fun ByteString(vararg bytes: Byte): ByteString = if (bytes.isEmpty()) {
     ByteString.EMPTY
@@ -61,6 +63,8 @@ public class ByteString private constructor(
      *
      * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of [data] array indices.
      * @throws IllegalArgumentException when `startIndex > endIndex`.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.constructionSample
      */
     public constructor(data: ByteArray, startIndex: Int = 0, endIndex: Int = data.size) :
             this(data.copyOfRange(startIndex, endIndex), null)
@@ -135,6 +139,9 @@ public class ByteString private constructor(
      *
      * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of byte string indices.
      * @throws IllegalArgumentException when `startIndex > endIndex`.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.toByteArraySample
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.toByteArrayWithIndicesSample
      */
     public fun toByteArray(startIndex: Int = 0, endIndex: Int = size): ByteArray {
         require(startIndex <= endIndex) { "startIndex ($startIndex) > endIndex ($endIndex)" }
@@ -154,6 +161,8 @@ public class ByteString private constructor(
      * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at
      * the specified [destinationOffset], or when that index is out of the [destination] array indices range.
      * @throws IllegalArgumentException when `startIndex > endIndex`.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.copyToSample
      */
     public fun copyInto(
         destination: ByteArray, destinationOffset: Int = 0,
@@ -172,6 +181,8 @@ public class ByteString private constructor(
      *
      * @throws IndexOutOfBoundsException when [startIndex] or [endIndex] is out of range of byte string indices.
      * @throws IllegalArgumentException when `startIndex > endIndex`.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.substringSample
      */
     public fun substring(startIndex: Int, endIndex: Int = size): ByteString = if (startIndex == endIndex) {
         EMPTY
@@ -187,6 +198,8 @@ public class ByteString private constructor(
      * The behavior is similar to [String.compareTo].
      *
      * @param other the byte string to compare this string to.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.compareTo
      */
     override fun compareTo(other: ByteString): Int {
         if (other === this) return 0
@@ -210,6 +223,8 @@ public class ByteString private constructor(
      * Note that a string representation includes the whole byte string content encoded.
      * Due to limitations exposed for the maximum string length, an attempt to return a string representation
      * of too long byte string may fail.
+     *
+     * @sample kotlinx.io.bytestring.samples.ByteStringSamples.toStringSample
      */
     override fun toString(): String {
         if (isEmpty()) {
@@ -257,6 +272,8 @@ public val ByteString.indices: IntRange
  *
  * @param byte the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byte] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.indexOfByteSample
  */
 public fun ByteString.indexOf(byte: Byte, startIndex: Int = 0): Int {
     val localData = getBackingArrayReference()
@@ -277,6 +294,8 @@ public fun ByteString.indexOf(byte: Byte, startIndex: Int = 0): Int {
  *
  * @param byteString the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byteString] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.indexOfByteStringSample
  */
 public fun ByteString.indexOf(byteString: ByteString, startIndex: Int = 0): Int {
     if (byteString.isEmpty()) return max(min(startIndex, size), 0)
@@ -299,6 +318,8 @@ public fun ByteString.indexOf(byteString: ByteString, startIndex: Int = 0): Int
  *
  * @param byteArray the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byteArray] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.indexOfByteArraySample
  */
 public fun ByteString.indexOf(byteArray: ByteArray, startIndex: Int = 0): Int {
     if (byteArray.isEmpty()) return max(min(startIndex, size), 0)
@@ -321,6 +342,8 @@ public fun ByteString.indexOf(byteArray: ByteArray, startIndex: Int = 0): Int {
  *
  * @param byte the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byte] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.lastIndexOfByteSample
  */
 public fun ByteString.lastIndexOf(byte: Byte, startIndex: Int = 0): Int {
     val localData = getBackingArrayReference()
@@ -341,6 +364,8 @@ public fun ByteString.lastIndexOf(byte: Byte, startIndex: Int = 0): Int {
  *
  * @param byteString the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byteString] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.lastIndexOfByteStringSample
  */
 public fun ByteString.lastIndexOf(byteString: ByteString, startIndex: Int = 0): Int {
     if (byteString.isEmpty()) return size
@@ -361,6 +386,8 @@ public fun ByteString.lastIndexOf(byteString: ByteString, startIndex: Int = 0):
  *
  * @param byteArray the value to search for.
  * @param startIndex the index (inclusive) starting from which the [byteArray] should be searched.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.lastIndexOfByteArraySample
  */
 public fun ByteString.lastIndexOf(byteArray: ByteArray, startIndex: Int = 0): Int {
     if (byteArray.isEmpty()) return size
@@ -378,6 +405,8 @@ public fun ByteString.lastIndexOf(byteArray: ByteArray, startIndex: Int = 0): In
  * Behavior of this method is compatible with [CharSequence.startsWith].
  *
  * @param byteArray the prefix to check for.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.startsWithByteArraySample
  */
 public fun ByteString.startsWith(byteArray: ByteArray): Boolean = when {
     byteArray.size > size -> false
@@ -390,6 +419,8 @@ public fun ByteString.startsWith(byteArray: ByteArray): Boolean = when {
  * Behavior of this method is compatible with [CharSequence.startsWith].
  *
  * @param byteString the prefix to check for.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.startsWithByteStringSample
  */
 public fun ByteString.startsWith(byteString: ByteString): Boolean = when {
     byteString.size > size -> false
@@ -403,6 +434,8 @@ public fun ByteString.startsWith(byteString: ByteString): Boolean = when {
  * Behavior of this method is compatible with [CharSequence.endsWith].
  *
  * @param byteArray the suffix to check for.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.endsWithByteArraySample
  */
 public fun ByteString.endsWith(byteArray: ByteArray): Boolean = when {
     byteArray.size > size -> false
@@ -415,6 +448,8 @@ public fun ByteString.endsWith(byteArray: ByteArray): Boolean = when {
  * Behavior of this method is compatible with [CharSequence.endsWith].
  *
  * @param byteString the suffix to check for.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.endsWithByteStringSample
  */
 public fun ByteString.endsWith(byteString: ByteString): Boolean = when {
     byteString.size > size -> false
@@ -461,13 +496,17 @@ public fun ByteString.isNotEmpty(): Boolean = !isEmpty()
 
 /**
  * Decodes content of a byte string into a string using UTF-8 encoding.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.encodeAndDecodeUtf8String
  */
 public fun ByteString.decodeToString(): String {
     return getBackingArrayReference().decodeToString()
 }
 
 /**
  * Encodes a string into a byte sequence using UTF8-encoding and wraps it into a byte string.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.encodeAndDecodeUtf8String
  */
 public fun String.encodeToByteString(): ByteString {
     return ByteString.wrap(encodeToByteArray())

bytestring/common/src/ByteStringBuilder.kt

@@ -21,6 +21,9 @@ import kotlin.math.max
  * will be allocated and previously written data will be copied into it.
  *
  * @param initialCapacity the initial size of an underlying byte sequence.
+ *
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.builderSample
+ * @sample kotlinx.io.bytestring.samples.ByteStringSamples.builderSampleWithoutAdditionalAllocs
  */
 public class ByteStringBuilder(initialCapacity: Int = 0) {
     private var buffer = ByteArray(initialCapacity)