> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 位函数文档

# 位函数

位函数适用于 `UInt8`、`UInt16`、`UInt32`、`UInt64`、`Int8`、`Int16`、`Int32`、`Int64`、`Float32` 或 `Float64` 中任意一对类型。某些函数还支持 `String` 和 `FixedString` 类型。

结果类型为整数，其位数等于各参数中的最大位数。如果参数中至少有一个是有符号类型，则结果为有符号整数。如果参数是浮点数，则会将其转换为 Int64。

{/*AUTOGENERATED_START*/}

<div id="bitAnd">
  ## bitAnd
</div>

引入版本：v1.1.0

对两个值执行按位与运算。

**语法**

```sql theme={null}
bitAnd(a, b)
```

**参数**

* `a` — 第一个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `b` — 第二个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回按位运算 `a AND b` 的结果。

**示例**

**使用示例**

```sql title=Query theme={null}
CREATE TABLE bits
(
    `a` UInt8,
    `b` UInt8
)
ENGINE = Memory;

INSERT INTO bits VALUES (0, 0), (0, 1), (1, 0), (1, 1);

SELECT
    a,
    b,
    bitAnd(a, b)
FROM bits
```

```response title=Response theme={null}
┌─a─┬─b─┬─bitAnd(a, b)─┐
│ 0 │ 0 │            0 │
│ 0 │ 1 │            0 │
│ 1 │ 0 │            0 │
│ 1 │ 1 │            1 │
└───┴───┴──────────────┘
```

<div id="bitCount">
  ## bitCount
</div>

引入版本：v20.3.0

计算一个数字的二进制表示中值为 1 的位数。

**语法**

```sql theme={null}
bitCount(x)
```

**参数**

* `x` — 整数或浮点数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 `x` 中值为 1 的位数。[`UInt8`](/zh/reference/data-types/int-uint)。

<Note>
  该函数不会将输入值转换为更大的类型 ([符号扩展](https://en.wikipedia.org/wiki/Sign_extension)) 。
  例如：`bitCount(toUInt8(-1)) = 8`。
</Note>

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bin(333), bitCount(333);
```

```response title=Response theme={null}
┌─bin(333)─────────┬─bitCount(333)─┐
│ 0000000101001101 │             5 │
└──────────────────┴───────────────┘
```

<div id="bitHammingDistance">
  ## bitHammingDistance
</div>

引入版本：v21.1.0

返回两个数字的位表示之间的 [Hamming 距离](https://en.wikipedia.org/wiki/Hamming_distance)。
可与 [`SimHash`](/zh/reference/functions/regular-functions/hash-functions#ngramSimHash) 函数结合使用，以检测近似重复字符串。
距离越小，字符串越相似。

**语法**

```sql theme={null}
bitHammingDistance(x, y)
```

**参数**

* `x` — 用于计算 Hamming 距离的第一个数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `y` — 用于计算 Hamming 距离的第二个数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 `x` 和 `y` 之间的 Hamming 距离。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitHammingDistance(111, 121);
```

```response title=Response theme={null}
┌─bitHammingDistance(111, 121)─┐
│                            3 │
└──────────────────────────────┘
```

<div id="bitNot">
  ## bitNot
</div>

引入版本：v1.1.0

执行按位取反运算。

**语法**

```sql theme={null}
bitNot(a)
```

**参数**

* `a` — 要对其执行按位取反运算的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)

**返回值**

返回 `~a` 的结果，即将 `a` 的各个位取反后的值。

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT
    CAST('5', 'UInt8') AS original,
    bin(original) AS original_binary,
    bitNot(original) AS result,
    bin(bitNot(original)) AS result_binary;
```

```response title=Response theme={null}
┌─original─┬─original_binary─┬─result─┬─result_binary─┐
│        5 │ 00000101        │    250 │ 11111010      │
└──────────┴─────────────────┴────────┴───────────────┘
```

<div id="bitOr">
  ## bitOr
</div>

引入版本：v1.1.0

对两个值执行按位或运算。

**语法**

```sql theme={null}
bitOr(a, b)
```

**参数**

* `a` — 第一个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `b` — 第二个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回按位运算 `a 或 b` 的结果

**示例**

**使用示例**

```sql title=Query theme={null}
CREATE TABLE bits
(
    `a` UInt8,
    `b` UInt8
)
ENGINE = Memory;

INSERT INTO bits VALUES (0, 0), (0, 1), (1, 0), (1, 1);

SELECT
    a,
    b,
    bitOr(a, b)
FROM bits;
```

```response title=Response theme={null}
┌─a─┬─b─┬─bitOr(a, b)─┐
│ 0 │ 0 │           0 │
│ 0 │ 1 │           1 │
│ 1 │ 0 │           1 │
│ 1 │ 1 │           1 │
└───┴───┴─────────────┘
```

<div id="bitRotateLeft">
  ## bitRotateLeft
</div>

引入于：v1.1.0

将位向左旋转若干位。超出的位会回绕到右侧。

**语法**

```sql theme={null}
bitRotateLeft(a, N)
```

**参数**

* `a` — 要旋转的值。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)
* `N` — 左旋的位数。[`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回旋转后的值，其类型与 `a` 相同。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 99 AS a, bin(a), bitRotateLeft(a, 2) AS a_rotated, bin(a_rotated);
```

```response title=Response theme={null}
┌──a─┬─bin(a)───┬─a_rotated─┬─bin(a_rotated)─┐
│ 99 │ 01100011 │       141 │ 10001101       │
└────┴──────────┴───────────┴────────────────┘
```

<div id="bitRotateRight">
  ## bitRotateRight
</div>

引入版本：v1.1.0

将位向右旋转若干位。移出的位会回绕到左侧。

**语法**

```sql theme={null}
bitRotateRight(a, N)
```

**参数**

* `a` — 要旋转的值。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)
* `N` — 向右旋转的位置数。[`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回旋转后的值，其类型与 `a` 相同。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 99 AS a, bin(a), bitRotateRight(a, 2) AS a_rotated, bin(a_rotated);
```

```response title=Response theme={null}
┌──a─┬─bin(a)───┬─a_rotated─┬─bin(a_rotated)─┐
│ 99 │ 01100011 │       216 │ 11011000       │
└────┴──────────┴───────────┴────────────────┘
```

<div id="bitShiftLeft">
  ## bitShiftLeft
</div>

引入版本：v1.1.0

将某个值的二进制表示按指定的位数向左移位。

`FixedString` 或 `String` 会被视为一个单一的多字节值。

`FixedString` 值在移出时，移出的位会丢失。
相反，`String` 值会扩展额外的字节，因此不会丢失任何位。

**语法**

```sql theme={null}
bitShiftLeft(a, N)
```

**参数**

* `a` — 要移位的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `N` — 移位的位数。[`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回移位后的值，其类型与 `a` 相同。

**示例**

**二进制编码的用法示例**

```sql title=Query theme={null}
SELECT 99 AS a, bin(a), bitShiftLeft(a, 2) AS a_shifted, bin(a_shifted);
```

```response title=Response theme={null}
┌──a─┬─bin(99)──┬─a_shifted─┬─bin(bitShiftLeft(99, 2))─┐
│ 99 │ 01100011 │       140 │ 10001100                 │
└────┴──────────┴───────────┴──────────────────────────┘
```

**十六进制编码使用示例**

```sql title=Query theme={null}
SELECT 'abc' AS a, hex(a), bitShiftLeft(a, 4) AS a_shifted, hex(a_shifted);
```

```response title=Response theme={null}
┌─a───┬─hex('abc')─┬─a_shifted─┬─hex(bitShiftLeft('abc', 4))─┐
│ abc │ 616263     │ &0        │ 06162630                    │
└─────┴────────────┴───────────┴─────────────────────────────┘
```

**Fixed String 编码使用示例**

```sql title=Query theme={null}
SELECT toFixedString('abc', 3) AS a, hex(a), bitShiftLeft(a, 4) AS a_shifted, hex(a_shifted);
```

```response title=Response theme={null}
┌─a───┬─hex(toFixedString('abc', 3))─┬─a_shifted─┬─hex(bitShiftLeft(toFixedString('abc', 3), 4))─┐
│ abc │ 616263                       │ &0        │ 162630                                        │
└─────┴──────────────────────────────┴───────────┴───────────────────────────────────────────────┘
```

<div id="bitShiftRight">
  ## bitShiftRight
</div>

引入版本：v1.1.0

将某个值的二进制表示按指定位数向右移位。

`FixedString` 或 `String` 会被视为一个多字节值。

`FixedString` 值在移出后，其位会丢失。
相反，`String` 值会通过附加额外字节进行扩展，因此不会丢失任何位。

**语法**

```sql theme={null}
bitShiftRight(a, N)
```

**参数**

* `a` — 要移位的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `N` — 移位的位数。[`UInt8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回移位后的值，其类型与 `a` 相同。

**示例**

**二进制编码用法示例**

```sql title=Query theme={null}
SELECT 101 AS a, bin(a), bitShiftRight(a, 2) AS a_shifted, bin(a_shifted);
```

```response title=Response theme={null}
┌───a─┬─bin(101)─┬─a_shifted─┬─bin(bitShiftRight(101, 2))─┐
│ 101 │ 01100101 │        25 │ 00011001                   │
└─────┴──────────┴───────────┴────────────────────────────┘
```

**十六进制编码的使用示例**

```sql title=Query theme={null}
SELECT 'abc' AS a, hex(a), bitShiftLeft(a, 4) AS a_shifted, hex(a_shifted);
```

```response title=Response theme={null}
┌─a───┬─hex('abc')─┬─a_shifted─┬─hex(bitShiftRight('abc', 12))─┐
│ abc │ 616263     │           │ 0616                          │
└─────┴────────────┴───────────┴───────────────────────────────┘
```

**Fixed String 编码用法示例**

```sql title=Query theme={null}
SELECT toFixedString('abc', 3) AS a, hex(a), bitShiftRight(a, 12) AS a_shifted, hex(a_shifted);
```

```response title=Response theme={null}
┌─a───┬─hex(toFixedString('abc', 3))─┬─a_shifted─┬─hex(bitShiftRight(toFixedString('abc', 3), 12))─┐
│ abc │ 616263                       │           │ 000616                                          │
└─────┴──────────────────────────────┴───────────┴─────────────────────────────────────────────────┘
```

<div id="bitSlice">
  ## bitSlice
</div>

引入版本：v22.2.0

返回一个子串，从 'offset' 索引对应的位开始，长度为 'length' 位。

**语法**

```sql theme={null}
bitSlice(s, offset[, length])
```

**参数**

* `s` — 要截取的 `String` 或 `FixedString`。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `offset` —
  起始位位置 (从 1 开始计数) 。
* 正值：从字符串开头开始计数。
* 负值：从字符串末尾开始计数。

  [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `length` —
  可选。要提取的位数。
* 正值：提取 `length` 位。
* 负值：从 `offset` 提取到 `(string_length - |length|)`。
* 省略时：从 `offset` 提取到字符串末尾。
* 如果 `length` 不是 8 的倍数，结果会在右侧用零填充。
  [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回一个包含提取后位的字符串，并以二进制序列表示。结果始终会填充到字节边界 (8 位的倍数) 。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bin('Hello'), bin(bitSlice('Hello', 1, 8));
SELECT bin('Hello'), bin(bitSlice('Hello', 1, 2));
SELECT bin('Hello'), bin(bitSlice('Hello', 1, 9));
SELECT bin('Hello'), bin(bitSlice('Hello', -4, 8));
```

```response title=Response theme={null}
┌─bin('Hello')─────────────────────────────┬─bin(bitSlice('Hello', 1, 8))─┐
│ 0100100001100101011011000110110001101111 │ 01001000                     │
└──────────────────────────────────────────┴──────────────────────────────┘
┌─bin('Hello')─────────────────────────────┬─bin(bitSlice('Hello', 1, 2))─┐
│ 0100100001100101011011000110110001101111 │ 01000000                     │
└──────────────────────────────────────────┴──────────────────────────────┘
┌─bin('Hello')─────────────────────────────┬─bin(bitSlice('Hello', 1, 9))─┐
│ 0100100001100101011011000110110001101111 │ 0100100000000000             │
└──────────────────────────────────────────┴──────────────────────────────┘
┌─bin('Hello')─────────────────────────────┬─bin(bitSlice('Hello', -4, 8))─┐
│ 0100100001100101011011000110110001101111 │ 11110000                      │
└──────────────────────────────────────────┴───────────────────────────────┘
```

<div id="bitTest">
  ## bitTest
</div>

引入版本：v1.1.0

接受任意数值，并将其转换为[二进制形式](https://en.wikipedia.org/wiki/Binary_number)，然后返回指定位置上该位的值。位序从右向左计数，从 0 开始。

**语法**

```sql theme={null}
bitTest(a, i)
```

**参数**

* `a` — 要转换的数值。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `i` — 要返回的位的位置。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回 `a` 的二进制表示中第 `i` 位的值 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bin(2), bitTest(2, 1);
```

```response title=Response theme={null}
┌─bin(2)───┬─bitTest(2, 1)─┐
│ 00000010 │             1 │
└──────────┴───────────────┘
```

<div id="bitTestAll">
  ## bitTestAll
</div>

引入版本：v1.1.0

返回给定位置上所有位进行[逻辑合取](https://en.wikipedia.org/wiki/Logical_conjunction) (AND 运算) 后的结果。
按从右到左的顺序计数，从 0 开始。

两个位进行逻辑 AND 运算时，当且仅当两个输入位都为真，结果才为真。

**语法**

```sql theme={null}
bitTestAll(a, index1[, index2, ... , indexN])
```

**参数**

* `a` — 整数值。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)
* `index1, ...` — 一个或多个位的位置。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回逻辑合取的结果 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例 1**

```sql title=Query theme={null}
SELECT bitTestAll(43, 0, 1, 3, 5);
```

```response title=Response theme={null}
┌─bin(43)──┬─bitTestAll(43, 0, 1, 3, 5)─┐
│ 00101011 │                          1 │
└──────────┴────────────────────────────┘
```

**使用示例 2**

```sql title=Query theme={null}
SELECT bitTestAll(43, 0, 1, 3, 5, 2);
```

```response title=Response theme={null}
┌─bin(43)──┬─bitTestAll(4⋯1, 3, 5, 2)─┐
│ 00101011 │                        0 │
└──────────┴──────────────────────────┘
```

<div id="bitTestAny">
  ## bitTestAny
</div>

引入版本：v1.1.0

返回一个数中指定位置上所有位进行[逻辑析取](https://en.wikipedia.org/wiki/Logical_disjunction) (或运算) 后的结果。
按从右到左的顺序计数，从 0 开始。

如果两个输入位中至少有一个为真，这两个位之间的逻辑或就为真。

**语法**

```sql theme={null}
bitTestAny(a, index1[, index2, ... , indexN])
```

**参数**

* `a` — 整数值。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)
* `index1, ...` — 一个或多个位的位置。[`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回逻辑析取的结果 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例 1**

```sql title=Query theme={null}
SELECT bitTestAny(43, 0, 2);
```

```response title=Response theme={null}
┌─bin(43)──┬─bitTestAny(43, 0, 2)─┐
│ 00101011 │                    1 │
└──────────┴──────────────────────┘
```

**用法示例 2**

```sql title=Query theme={null}
SELECT bitTestAny(43, 4, 2);
```

```response title=Response theme={null}
┌─bin(43)──┬─bitTestAny(43, 4, 2)─┐
│ 00101011 │                    0 │
└──────────┴──────────────────────┘
```

<div id="bitXor">
  ## bitXor
</div>

引入版本：v1.1.0

对两个值执行按位异或 (XOR) 运算。

**语法**

```sql theme={null}
bitXor(a, b)
```

**参数**

* `a` — 第一个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `b` — 第二个值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)

**返回值**

返回按位异或运算 `a XOR b` 的结果

**示例**

**用法示例**

```sql title=Query theme={null}
CREATE TABLE bits
(
    `a` UInt8,
    `b` UInt8
)
ENGINE = Memory;

INSERT INTO bits VALUES (0, 0), (0, 1), (1, 0), (1, 1);

SELECT
    a,
    b,
    bitXor(a, b)
FROM bits;
```

```response title=Response theme={null}
┌─a─┬─b─┬─bitXor(a, b)─┐
│ 0 │ 0 │            0 │
│ 0 │ 1 │            1 │
│ 1 │ 0 │            1 │
│ 1 │ 1 │            0 │
└───┴───┴──────────────┘
```