/********************************************************************
 * @author:      Kaven
 * @email:       kaven@wuwenkai.com
 * @website:     http://blog.kaven.xyz
 * @file:        [Kaven-Basic] /src/libs/class/BitString.ts
 * @create:      2018-08-30 16:07:15.084
 * @modify:      2025-07-08 17:09:49.280
 * @version:     6.0.0
 * @times:       117
 * @lines:       607
 * @copyright:   Copyright © 2018-2025 Kaven. All Rights Reserved.
 * @description: [description]
 * @license:
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 ********************************************************************/
import { TBitStringType } from "../type/advanced";
/**
 * Represents a string of bits and provides various bitwise operations and utilities.
 *
 * The `BitString` class allows for the creation, manipulation, and conversion of bit strings.
 * It supports initialization from numbers, strings (binary or hexadecimal), and provides methods
 * for bitwise operations (AND, OR, XOR, NOT), shifting, rotating, reflecting, and conversion to numbers or byte arrays.
 *
 * @example
 * ```typescript
 * const bits = new BitString(10); // "1010"
 * bits.SetBit(1, true); // Set the least significant bit
 * const sum = bits.Add(new BitString(5));
 * ```
 *
 * @remarks
 * - Bit offsets are counted from right to left, starting at 1.
 * - Supports both binary and hexadecimal string initialization.
 * - Provides static helpers for 2D array initialization and byte conversion.
 *
 * @public
 *
 * @version 1.0.0
 * @since 1.0.5
 */
export declare class BitString {
    /**
     * Gets the length of the binary string.
     * @returns The number of characters in the binary string.
     */
    get Length(): number;
    /**
     * Gets the hexadecimal string representation of the bit string.
     *
     * @returns {string} The hexadecimal representation of the current bit string.
     */
    get HEX(): string;
    /**
     * Creates a new `BitString` instance from one or more byte values.
     *
     * Each byte is converted to its 8-bit binary representation and concatenated
     * to form the complete bit string.
     *
     * @param bytes - One or more numbers representing bytes (0-255) to convert.
     * @returns A new `BitString` instance representing the concatenated bits of the input bytes.
     */
    static FromBytes(...bytes: number[]): BitString;
    /**
     * Initializes a 2D array of `BitString` instances with the specified dimensions.
     *
     * @param x - The number of rows in the 2D array.
     * @param y - The number of columns in each row of the 2D array.
     * @returns A 2D array (`BitString[][]`) where each element is a new instance of `BitString`.
     */
    static Initialize2d(x: number, y: number): BitString[][];
    private binStr;
    constructor();
    constructor(initialValue: number);
    constructor(initialValue: number, type: TBitStringType);
    constructor(initialValue: string);
    constructor(initialValue: string, radix: number);
    constructor(initialValue: string, type: TBitStringType);
    /**
     * Sets the bit at the specified offset to the given boolean value.
     *
     * The offset is 1-based, where 1 refers to the least significant bit (rightmost).
     * If the offset exceeds the current length, the bit string is left-padded with zeros as needed.
     *
     * @param offset - The 1-based position of the bit to set. Must be greater than or equal to 1.
     * @param val - The boolean value to set the bit to (`true` for '1', `false` for '0').
     * @returns The updated BitString instance.
     * @throws {Error} If the offset is less than 1.
     */
    SetBit(offset: number, val: boolean): this;
    /**
     * Retrieves the value of the bit at the specified offset from the end of the bit string.
     *
     * @param offset - The 1-based position from the end of the bit string to retrieve the bit from. Must be greater than or equal to 1.
     * @param defaultVal - The value to return if the offset is out of bounds. Defaults to `false`.
     * @returns `true` if the bit at the specified offset is '1', `false` if it is '0', or `defaultVal` if the offset is out of bounds.
     * @throws {Error} If the provided offset is less than 1.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    GetBit(offset: number, defaultVal?: boolean): boolean;
    /**
     * Checks if any bit in the binary string is set to '1'.
     *
     * @returns {boolean} `true` if at least one bit is '1'; otherwise, `false`.
     */
    AnyBit(): boolean;
    /**
     * Converts the bit string to its string representation in the specified format.
     *
     * @param type - The output format for the bit string. Can be `BitStringType.BIN` for binary or `BitStringType.HEX` for hexadecimal. Defaults to `BitStringType.HEX`.
     * @param trim - If `true`, leading zeros are trimmed from the hexadecimal output. Defaults to `false`.
     * @returns The string representation of the bit string in the specified format. Returns `"0"` if the bit string is empty or consists only of zeros.
     * @throws {Error} If an invalid `BitStringType` is provided.
     */
    toString(type?: TBitStringType, trim?: boolean): string;
    /**
     * Adds the current BitString to another BitString and returns the result as a new BitString.
     * The addition is performed bit by bit, starting from the least significant bit (rightmost),
     * and handles carry-over similar to binary addition.
     *
     * @param val - The BitString to add to the current BitString.
     * @returns A new BitString representing the sum of the two BitStrings.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    Add(val: BitString): BitString;
    /**
     * Performs a bitwise AND operation between this BitString and another BitString or number.
     *
     * If the input is a number, it is first converted to a BitString. The lengths of both BitStrings
     * are adjusted to match the longer one by padding with zeros if necessary. The result is a new
     * BitString where each bit is the logical AND of the corresponding bits in the two operands.
     *
     * @param val - The BitString or number to perform the AND operation with.
     * @returns A new BitString representing the result of the bitwise AND operation.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    AND(val: BitString | number): BitString;
    /**
     * Performs a bitwise OR operation between this BitString and another BitString or number.
     *
     * If a number is provided, it is first converted to a BitString. The operation is performed
     * bit by bit, starting from the least significant bit. The resulting BitString will have a length
     * equal to the longer of the two operands.
     *
     * @param val - The BitString or number to OR with this BitString.
     * @returns A new BitString representing the result of the bitwise OR operation.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    OR(val: BitString | number): BitString;
    /**
     * Returns a new BitString instance with each bit inverted.
     *
     * Iterates through the current binary string and flips each bit:
     * - '0' becomes '1'
     * - '1' becomes '0'
     *
     * @returns {BitString} A new BitString with all bits inverted.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    NOT(): BitString;
    /**
     * Performs a bitwise XOR operation between this BitString and another BitString or number.
     *
     * If the input value is a number, it is first converted to a BitString.
     * The lengths of both BitStrings are adjusted to match by padding with leading zeros if necessary.
     * Returns a new BitString representing the result of the XOR operation.
     *
     * @param val - The BitString or number to XOR with this BitString.
     * @returns A new BitString containing the result of the XOR operation.
     *
     * @since 1.1.20
     * @version 2019-04-01
     */
    XOR(val: BitString | number): BitString;
    /**
     * Shifts the current bit string to the left by the specified number of positions.
     * This operation appends `n` zeros to the right end of the bit string.
     *
     * @param n - The number of positions to shift left (number of zeros to append).
     * @returns A new `BitString` instance with the bits shifted left by `n` positions.
     */
    LeftShift(n: number): BitString;
    /**
     * Performs a right shift operation on the current BitString by the specified number of bits.
     * Pads the left side with zeros and truncates bits from the right.
     *
     * @param n - The number of bits to shift to the right.
     * @returns A new BitString instance representing the shifted value.
     */
    RightShift(n: number): BitString;
    /**
     * Performs a left rotation (circular shift) of the bit string by the specified number of positions.
     *
     * @param n - The number of positions to rotate the bit string to the left.
     * @param bits - The total number of bits to consider for the rotation. Defaults to 64.
     * @returns A new `BitString` instance with the bits rotated to the left by `n` positions.
     *
     * @version 1.0.0
     * @version 2025-06-27
     */
    LeftRotate(n: number, bits?: number): BitString;
    /**
     * Rotates the bits of the current BitString instance to the right by the specified number of positions.
     *
     * @param n - The number of positions to rotate the bits to the right.
     * @param bits - The total number of bits to consider for the rotation. Defaults to 64.
     * @returns The BitString instance after performing the right rotation.
     *
     * @version 1.0.0
     * @version 2025-06-27
     */
    RightRotate(n: number, bits?: number): BitString;
    /**
     * Converts the internal binary string representation (`binStr`) to a number.
     *
     * @returns The numeric value of the binary string.
     */
    ToNumber(): number;
    /**
     * Converts the bit string to an array of bytes.
     *
     * @param bits - Optional. If provided, sets the length of the bit string to the specified number of bits before conversion.
     * @returns An array of numbers, where each number represents a byte from the bit string.
     */
    ToBytes(bits?: number): number[];
    /**
     * Returns a new `BitString` instance with the bits in reverse order.
     * Optionally sets the length of the bit string before reflecting.
     *
     * @param bits - Optional. If provided, sets the length of the bit string before reflecting.
     * @returns A new `BitString` with the bits reversed.
     */
    Reflect(bits?: number): BitString;
    /**
     * Sets the length of the bit string to the specified number of bits.
     *
     * If the current length is greater than the specified length, the bit string is truncated from the left.
     * If the current length is less than the specified length, the bit string is left-padded with zeros.
     *
     * @param bits - The desired length of the bit string in bits.
     * @returns The current instance for method chaining.
     */
    SetLength(bits: number): this;
    /**
     * Creates and returns a new `BitString` instance that is a copy of the current object.
     *
     * @returns {BitString} A new `BitString` object with the same binary string as the original.
     */
    Clone(): BitString;
    /**
     * Reverses the order of bytes in the current bit string.
     *
     * @param bytes - The number of bytes to consider for swapping. Defaults to 8.
     * @returns A new `BitString` instance with the byte order reversed.
     *
     * @remarks
     * This method sets the bit string length to `bytes * 8`, splits the string into 8-bit chunks (bytes),
     * reverses their order, and joins them back together. The result is returned as a new `BitString`.
     */
    Swap(bytes?: number): BitString;
    /**
     * Determines whether this BitString is equal to another BitString,
     * ignoring leading zeros in their binary string representations.
     *
     * @param another - The BitString instance to compare with.
     * @returns `true` if the normalized binary strings are equal; otherwise, `false`.
     */
    Equals(another: BitString): boolean;
}
//# sourceMappingURL=BitString.d.ts.map