1

src/main/kotlin/cn/qqck/kotlin/tools/Pack.kt

@@ -0,0 +1,456 @@
+package cn.qqck.kotlin.tools
+
+class Pack(size: Int = 32) {
+    /**
+     * 存储数据的缓冲区。
+     */
+    private var buf: ByteArray = ByteArray(if (size < 0) 32 else size)
+
+    /**
+     * 缓冲区中的有效字节数。
+     */
+    private var buf_size = 0
+
+    /**
+     * 每次扩容的字节数，默认：512 字节
+     */
+    private var grow_size = 512
+
+    /**
+     * 设置扩展缓冲区的增长大小。
+     * 如果传入的值小于 1，则设置为默认值 512；否则使用传入的值。
+     *
+     * @param value 扩展缓冲区的增长大小。小于 0 时会被重置为 512。
+     * @return 返回当前对象自身，以支持链式调用。
+     */
+    fun grow_size(value: Int): Pack {
+        this.grow_size = if (value < 1) 512 else value
+        return this
+    }
+
+    /**
+     * 扩展当前缓冲区的容量，以确保可以容纳指定的大小。
+     *
+     * @param size 需要扩展的大小。如果当前缓冲区不足以容纳新增内容，则进行扩容。
+     * @return 返回当前对象自身，以支持链式调用。
+     */
+    private fun grow(size: Int): Pack {
+        if (this.buf_size + size > this.buf.size) this.buf = this.buf.copyOf(this.buf.size + size + this.grow_size)
+        return this
+    }
+
+    //-----------------------------------------------------------------------------------------------------基础
+
+    /**
+     * 根据指定索引从缓冲区中获取对应的字节。如果索引超出缓冲区大小，则返回零。
+     *
+     * @param i 缓冲区中的索引。
+     * @return 指定索引对应的字节数据；如果索引超出范围，返回 0。
+     */
+    operator fun get(i: Int): Byte {
+        if (i < this.buf_size) return this.buf[i]
+        return 0
+    }
+
+    /**
+     * 替换当前缓冲区为指定的字节数组，并调整内部状态。
+     *
+     * @param buf 新的字节缓冲区内容。
+     * @return 返回当前对象自身，以支持链式调用。
+     */
+    fun bytes(buf: ByteArray): Pack {
+        this.buf = buf.copyOf(buf.size + this.grow_size)
+        this.buf_size = buf.size
+        this.pop_i = 0
+        return this
+    }
+
+    /**
+     * 返回包含当前缓冲区内容的字节数组。
+     *
+     * @return 一个新的字节数组，包含当前缓冲区（buf）的副本，其长度为缓冲区大小（buf_size）。
+     */
+    fun bytes(): ByteArray = this.buf.copyOf(this.buf_size)
+
+    /**
+     * 将当前缓冲区中的有效数据转换为字符串。
+     *
+     * @return 当前缓冲区中的数据内容作为字符串返回。
+     */
+    fun string(): String {
+        return String(this.buf, 0, this.buf_size)
+    }
+
+    /**
+     * 获取当前对象的大小。
+     *
+     * @return 返回表示当前对象大小的整数值。
+     */
+    fun size(): Int = this.buf_size
+
+    /**
+     * 调整当前对象的大小。
+     *
+     * @param size 期望设置的大小值。如果该值大于当前对象的大小，则不会进行调整。
+     * @return 调整后的对象自身。
+     */
+    fun size(size: Int): Pack {
+        if (size > this.size()) return this
+        this.buf_size = size
+        return this
+    }
+
+    /**
+     * 返回缓冲区的大小。
+     *
+     * @return 缓冲区的大小，以整型值表示。
+     */
+    fun cap(): Int = this.buf.size
+
+    /**
+     * 重置当前对象的状态，将缓冲区大小设置为增长大小，清除相关属性的值。
+     *
+     * @return 返回当前重置后的对象实例。
+     */
+    fun reset(): Pack {
+        this.buf = ByteArray(this.grow_size)
+        this.buf_size = 0
+        this.pop_i = 0
+        return this
+    }
+
+    //-----------------------------------------------------------------------------------------------------Push
+
+    /**
+     * 将一个或多个字节值添加到缓冲区中。
+     *
+     * @param vals 要添加的字节值，可变参数。
+     * @return 返回当前对象以支持链式调用。
+     */
+    fun push_byte(vararg vals: Byte): Pack {
+        this.grow(vals.size)
+        System.arraycopy(vals, 0, this.buf, this.buf_size, vals.size)
+        this.buf_size += vals.size
+        return this
+    }
+
+    /**
+     * 将多个Short值推入缓冲区，并根据指定的字节序进行写入操作。
+     *
+     * @param vals 需要推入的Short值，可变参数形式。
+     * @param big 指定字节序，true表示大端字节序，false表示小端字节序，默认为false。
+     * @return 当前对象实例，便于链式调用。
+     */
+    fun push_short(vararg vals: Short, big: Boolean = false): Pack {
+        this.grow(vals.size * 2)
+        if (big) {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = (vals[j_i].toInt() shr 8).toByte()
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+            }
+        } else {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+                this.buf[this.buf_size++] = (vals[j_i].toInt() shr 8).toByte()
+            }
+        }
+        return this
+    }
+
+    /**
+     * 将多个整数值按照指定字节顺序写入缓冲区，并返回当前对象。
+     *
+     * @param vals 要写入的整数值，可变参数。
+     * @param big 是否采用大端字节序。如果为 true，则使用大端字节序；否则使用小端字节序。默认为 false。
+     * @return 当前对象，用于支持链式调用。
+     */
+    fun push(vararg vals: Int, big: Boolean = false): Pack {
+        this.grow(vals.size * 4)
+        if (big) {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = (vals[j_i] shr 24).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 16).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 8).toByte()
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+            }
+        } else {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 8).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 16).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 24).toByte()
+            }
+        }
+        return this
+    }
+
+    /**
+     * 将一个或多个长整型值写入缓冲区，并根据指定模式(big/little-endian)调节写入顺序。
+     *
+     * @param vals 多个需要写入的长整型值。
+     * @param big 是否以大端模式写入，如果为`true`按大端顺序写入，否则按小端顺序写入，默认值为`false`（小端模式）。
+     * @return 返回当前对象，支持链式调用。
+     */
+    fun push(vararg vals: Long, big: Boolean = false): Pack {
+        this.grow(vals.size * 8)
+        if (big) {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = (vals[j_i] shr 56).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 48).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 40).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 32).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 24).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 16).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 8).toByte()
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+            }
+        } else {
+            for (j_i in vals.indices) {
+                this.buf[this.buf_size++] = vals[j_i].toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 8).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 16).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 24).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 32).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 40).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 48).toByte()
+                this.buf[this.buf_size++] = (vals[j_i] shr 56).toByte()
+            }
+        }
+        return this
+    }
+
+    /**
+     * 将一个或多个字节数组追加到当前缓冲区，并返回自身。
+     *
+     * @param vals 可变参数，表示需要追加的字节数组。
+     * @return 返回修改后的当前对象。
+     */
+    fun push(vararg vals: ByteArray): Pack {
+        var j_size = 0
+        for (j_i in vals.indices) {
+            j_size += vals[j_i].size
+        }
+        this.grow(j_size)
+        for (j_i in vals.indices) {
+            System.arraycopy(vals[j_i], 0, this.buf, this.buf_size, vals[j_i].size)
+            this.buf_size += vals[j_i].size
+        }
+        return this
+    }
+
+    /**
+     * 将指定的字节数组的一部分内容添加到缓冲区中。
+     *
+     * @param buf 要添加的字节数组。
+     * @param offset 起始偏移量，表示从字节数组中读取数据的开始位置。
+     * @param length 要添加的字节数。
+     * @return 返回当前的 `Pack` 对象实例，用于链式调用。
+     */
+    fun push(buf: ByteArray, offset: Int, length: Int): Pack {
+        if (offset + length > buf.size) return this
+        this.grow(length)
+        System.arraycopy(buf, offset, this.buf, this.buf_size, length)
+        this.buf_size += length
+        return this
+    }
+
+    /**
+     * 将多个字符串参数追加到当前的缓冲区中，扩展缓冲区并更新缓冲区大小。
+     *
+     * @param vals 可变参数，表示需要追加到缓冲区的字符串集合。
+     * @return 返回当前对象，包含追加后的缓冲区数据。
+     */
+    fun push(vararg vals: String): Pack {
+        var j_size = 0
+        for (j_i in vals.indices) {
+            j_size += vals[j_i].length
+        }
+        this.grow(j_size)
+        for (j_i in vals.indices) {
+            System.arraycopy(vals[j_i].toByteArray(), 0, this.buf, this.buf_size, vals[j_i].length)
+            this.buf_size += vals[j_i].length
+        }
+        return this
+    }
+
+    //-----------------------------------------------------------------------------------------------------Pop
+
+    private var pop_i = 0
+
+    /**
+     * 返回 `pop_i` 的值。
+     *
+     * @return 当前对象的 `pop_i` 值。
+     */
+    fun pop_i(): Int = this.pop_i
+
+    /**
+     * 计算并返回当前可弹出元素的数量。
+     *
+     * 此方法使用内部的 `buf_size` 和 `pop_i` 变量进行计算。
+     *
+     * @return 可弹出元素的数量，类型为 Int。
+     */
+    fun pop_size(): Int = this.buf_size - this.pop_i
+
+    /**
+     * 从缓冲区中弹出一个字节。
+     *
+     * 此方法会检查当前的索引是否已经超出了缓冲区的大小。
+     * 如果索引超过了缓冲区大小，则返回null。
+     * 否则，返回缓冲区当前索引处的字节，并将索引自增。
+     *
+     * @return 弹出的字节，或者在索引超出范围时返回null。
+     */
+    fun pop_byte(): Byte? = if (this.pop_i >= this.buf_size) null else this.buf[this.pop_i++]
+
+    /**
+     * 从缓冲区中弹出一个Short类型的值。
+     *
+     * @param big 指定字节序是否为大端字节序。如果为true，则采用大端字节序；否则采用小端字节序。
+     * @return 如果缓冲区中有足够的数据可供弹出，则返回一个Short类型的值；否则返回null。
+     */
+    fun pop_short(big: Boolean = false): Short? = if (this.pop_i + 1 >= this.buf_size) null else if (big) {
+        ((this.buf[this.pop_i++].toUByte().toInt() shl 8) or
+                this.buf[this.pop_i++].toUByte().toInt()).toShort()
+    } else {
+        (this.buf[this.pop_i++].toUByte().toInt() or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 8)).toShort()
+    }
+
+    /**
+     * 从缓冲区中弹出一个整数值，并根据指定的大端或小端字节序解码。
+     *
+     * @param big 指定字节序是否为大端字节序。如果为 true，则按照大端字节序解析；否则按照小端字节序解析。
+     * 默认为 false，即小端字节序。
+     * @return 返回解码后的整数值。如果缓冲区没有足够的字节进行解析，则返回 null。
+     */
+    fun pop_int(big: Boolean = false): Int? = if (this.pop_i + 3 >= this.buf_size) null else if (big) {
+        (this.buf[this.pop_i++].toUByte().toInt() shl 24) or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 16) or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 8) or
+                this.buf[this.pop_i++].toUByte().toInt()
+    } else {
+        this.buf[this.pop_i++].toUByte().toInt() or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 8) or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 16) or
+                (this.buf[this.pop_i++].toUByte().toInt() shl 24)
+    }
+
+    /**
+     * 从缓冲区中提取一个长整型（Long）值。
+     *
+     * @param big 表示是否以大端字节序读取。当值为true时，按大端字节序解析；否则，按小端字节序解析。默认为false。
+     * @return 提取的长整型（Long）值，如果缓冲区长度不足以提取8个字节，则返回null。
+     */
+    fun pop_long(big: Boolean = false): Long? = if (this.pop_i + 7 >= this.buf_size) null else if (big) {
+        (this.buf[this.pop_i++].toUByte().toLong() shl 56) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 48) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 40) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 32) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 24) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 16) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 8) or
+                this.buf[this.pop_i++].toUByte().toLong()
+    } else {
+        this.buf[this.pop_i++].toUByte().toLong() or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 8) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 16) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 24) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 32) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 40) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 48) or
+                (this.buf[this.pop_i++].toUByte().toLong() shl 56)
+    }
+
+    /**
+     * 从缓冲区中弹出指定大小的数据，并返回一个新的字节数组。
+     * 如果请求的大小超出了当前缓冲区的剩余容量，则返回 null。
+     *
+     * @param size 要弹出的字节数，默认为调用 `pop_size` 方法的返回值。
+     * @return 包含弹出数据的新字节数组，如果缓冲区剩余数据不足则返回 null。
+     */
+    fun pop_bytes(size: Int = this.pop_size()): ByteArray? {
+        if (this.pop_i + size - 1 >= this.buf_size) {
+            return null
+        }
+        val j_result = this.buf.copyOf(this.pop_i, size)
+        this.pop_i += size
+        return j_result
+    }
+
+    /**
+     * 从当前对象中提取指定大小的字节数组。
+     * 根据内部逻辑首先获取所需的字节大小，然后根据此大小提取对应数量的字节。
+     * 如果大小不可用或超出范围，则返回null。
+     *
+     * @return 提取的字节数组，如果无法提取则返回null。
+     */
+    fun pop_bytes_byte(): ByteArray? {
+        val j_size = this.pop_byte()
+        if (j_size == null || j_size > this.pop_size()) {
+            this.pop_i -= 1
+            return null
+        }
+        return this.pop_bytes(j_size.toInt())
+    }
+
+    /**
+     * 从数据源中提取一定数量的字节数组，长度由前置的短整型值指定。
+     *
+     * @param big 指定是否以大端字节顺序读取短整型值，默认为小端字节顺序（false）。
+     * @return 返回提取的字节数组，如果长度信息无效或超出剩余有效数据范围，则返回null。
+     */
+    fun pop_bytes_short(big: Boolean = false): ByteArray? {
+        val j_size = this.pop_short(big)
+        if (j_size == null || j_size > this.pop_size()) {
+            this.pop_i -= 2
+            return null
+        }
+        return this.pop_bytes(j_size.toInt())
+    }
+
+    /**
+     * 从缓冲区中弹出一个指定大小的字节数组。
+     *
+     * @param big 指定是否以大端字节序解码，默认为小端字节序。
+     * @return 返回弹出的字节数组，如果数据不足或解析失败则返回null。
+     */
+    fun pop_bytes_int(big: Boolean = false): ByteArray? {
+        val j_size = this.pop_int(big)
+        if (j_size == null || j_size > this.pop_size()) {
+            this.pop_i -= 4
+            return null
+        }
+        return this.pop_bytes(j_size)
+    }
+
+    /**
+     * 从字节缓冲区中取出指定长度的字节数据，并将其转换为字符串返回。
+     *
+     * @param size 要提取的字节数，默认为调用 `pop_size` 方法返回的值。
+     * @return 从字节缓冲区转换得到的字符串，如果字节缓冲区为空或提取失败，则返回 null。
+     */
+    fun pop_string(size: Int = this.pop_size()): String? = this.pop_bytes(size)?.string()
+
+    /**
+     * 弹出 size=Byte 的 String 类型数据
+     */
+    fun pop_string_byte(): String? = this.pop_bytes_byte()?.string()
+
+    /**
+     * 从内部缓冲区中读取一个短字节数组并将其转换为字符串。
+     *
+     * @param big 表示是否以大端字节顺序解析短字节数组。默认为false，即小端字节顺序。
+     * @return 返回转换后的字符串。如果缓冲区中没有足够的字节可供读取，则返回null。
+     */
+    fun pop_string_short(big: Boolean = false): String? = this.pop_bytes_short(big)?.string()
+
+    /**
+     * 从某个数据结构中提取并转换一个整数为字符串。
+     *
+     * @param big 如果为 true，则以大端字节序解析整数；如果为 false，则以小端字节序解析整数，默认为 false。
+     * @return 返回提取的整数转换为字符串的结果，如果没有可提取的内容则返回 null。
+     */
+    fun pop_string_int(big: Boolean = false): String? = this.pop_bytes_int(big)?.string()
+}