Add constant-time operation examples

Author: 05nelsonm

library/base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Builders.kt

@@ -84,6 +84,25 @@ public class Base16ConfigBuilder {
      * (such as private key material).
      *
      * If false, will not use constant time operations.
+     *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
      * */
     @JvmField
     public var isConstantTime: Boolean = false

library/base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Builders.kt

@@ -161,6 +161,25 @@ public class Base32CrockfordConfigBuilder {
      * (such as private key material).
      *
      * If false, will not use constant time operations.
+     *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
      * */
     @JvmField
     public var isConstantTime: Boolean = false
@@ -336,6 +355,25 @@ public class Base32DefaultConfigBuilder {
      * (such as private key material).
      *
      * If false, will not use constant time operations.
+     *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
      * */
     @JvmField
     public var isConstantTime: Boolean = false
@@ -443,6 +481,25 @@ public class Base32HexConfigBuilder {
      * (such as private key material).
      *
      * If false, will not use constant time operations.
+     *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
      * */
     @JvmField
     public var isConstantTime: Boolean = false

library/base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Builders.kt

@@ -81,6 +81,25 @@ public class Base64ConfigBuilder {
      * (such as private key material).
      *
      * If false, will not use constant time operations.
+     *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
      * */
     @JvmField
     public var isConstantTime: Boolean = false

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/util/CTCase.kt

@@ -28,6 +28,25 @@ import kotlin.jvm.JvmField
  * **NOTE:** Only characters where [Char.isLetter] is true are taken from
  * the provided table.
  *
+ * e.g. (NOT constant-time operation)
+ *
+ *     fun String.containsChar(char: Char): Boolean {
+ *         for (c in this) {
+ *             if (c == char) return true
+ *         }
+ *         return false
+ *     }
+ *
+ * e.g. (YES constant-time operation)
+ *
+ *     fun String.containsChar(char: Char): Boolean {
+ *         var result = false
+ *         for (c in this) {
+ *             result = if (c == char) true else result
+ *         }
+ *         return result
+ *     }
+ *
  * @param [table] The decoding table (e.g. `ABCDEFGHIJKLMNOPQRSTUVWXYZ234567`)
  * @throws [IllegalArgumentException] if table contains a letter that has no
  *   corresponding lowercase value.

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/util/DecoderAction.kt

@@ -36,6 +36,25 @@ public fun interface DecoderAction {
      * with support for constant-time operations (in terms of work performed
      * for provided input).
      *
+     * e.g. (NOT constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         for (c in this) {
+     *             if (c == char) return true
+     *         }
+     *         return false
+     *     }
+     *
+     * e.g. (YES constant-time operation)
+     *
+     *     fun String.containsChar(char: Char): Boolean {
+     *         var result = false
+     *         for (c in this) {
+     *             result = if (c == char) true else result
+     *         }
+     *         return result
+     *     }
+     *
      * e.g. (Base16)
      *
      *     val parser = DecoderAction.Parser(
@@ -65,7 +84,7 @@ public fun interface DecoderAction {
          *
          * @param [input] the character to parse [actions] with
          * @param [isConstantTime] If `true`, will **not** jump out of
-         *   loops early in the event a hit occurs.
+         *   loops early in the event a match is found.
          * @return The result of [DecoderAction.convert], or `null` if no
          *   match was found.
          * */