Merge pull request #28194 from ka1bi4/romanzhukov-DOCSUP-12543-bin-unbin-functions

This commit is contained in:
Vladimir C 2021-09-11 10:47:17 +03:00 committed by GitHub
commit aee967de3d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 224 additions and 95 deletions

View File

@ -87,7 +87,23 @@ The function is using uppercase letters `A-F` and not using any prefixes (like `
For integer arguments, it prints hex digits (“nibbles”) from the most significant to least significant (big-endian or “human-readable” order). It starts with the most significant non-zero byte (leading zero bytes are omitted) but always prints both digits of every byte even if the leading digit is zero.
**Example**
Values of type [Date](../../sql-reference/data-types/date.md) and [DateTime](../../sql-reference/data-types/datetime.md) are formatted as corresponding integers (the number of days since Epoch for Date and the value of Unix Timestamp for DateTime).
For [String](../../sql-reference/data-types/string.md) and [FixedString](../../sql-reference/data-types/fixedstring.md), all bytes are simply encoded as two hexadecimal numbers. Zero bytes are not omitted.
Values of [Float](../../sql-reference/data-types/float.md) and [Decimal](../../sql-reference/data-types/decimal.md) types are encoded as their representation in memory. As we support little-endian architecture, they are encoded in little-endian. Zero leading/trailing bytes are not omitted.
**Arguments**
- `arg` — A value to convert to hexadecimal. Types: [String](../../sql-reference/data-types/string.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
**Returned value**
- A string with the hexadecimal representation of the argument.
Type: [String](../../sql-reference/data-types/string.md).
**Examples**
Query:
@ -101,28 +117,10 @@ Result:
01
```
Values of type `Date` and `DateTime` are formatted as corresponding integers (the number of days since Epoch for Date and the value of Unix Timestamp for DateTime).
For `String` and `FixedString`, all bytes are simply encoded as two hexadecimal numbers. Zero bytes are not omitted.
Values of floating point and Decimal types are encoded as their representation in memory. As we support little-endian architecture, they are encoded in little-endian. Zero leading/trailing bytes are not omitted.
**Arguments**
- `arg` — A value to convert to hexadecimal. Types: [String](../../sql-reference/data-types/string.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
**Returned value**
- A string with the hexadecimal representation of the argument.
Type: `String`.
**Example**
Query:
``` sql
SELECT hex(toFloat32(number)) as hex_presentation FROM numbers(15, 2);
SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2);
```
Result:
@ -137,7 +135,7 @@ Result:
Query:
``` sql
SELECT hex(toFloat64(number)) as hex_presentation FROM numbers(15, 2);
SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2);
```
Result:
@ -210,52 +208,52 @@ Result:
Returns a string containing the arguments binary representation.
Alias: `BIN`.
**Syntax**
``` sql
bin(arg)
```
Alias: `BIN`.
For integer arguments, it prints bin digits from the most significant to least significant (big-endian or “human-readable” order). It starts with the most significant non-zero byte (leading zero bytes are omitted) but always prints eight digits of every byte if the leading digit is zero.
**Example**
Values of type [Date](../../sql-reference/data-types/date.md) and [DateTime](../../sql-reference/data-types/datetime.md) are formatted as corresponding integers (the number of days since Epoch for `Date` and the value of Unix Timestamp for `DateTime`).
Query:
For [String](../../sql-reference/data-types/string.md) and [FixedString](../../sql-reference/data-types/fixedstring.md), all bytes are simply encoded as eight binary numbers. Zero bytes are not omitted.
``` sql
SELECT bin(1);
```
Result:
``` text
00000001
```
Values of type `Date` and `DateTime` are formatted as corresponding integers (the number of days since Epoch for Date and the value of Unix Timestamp for DateTime).
For `String` and `FixedString`, all bytes are simply encoded as eight binary numbers. Zero bytes are not omitted.
Values of floating-point and Decimal types are encoded as their representation in memory. As we support little-endian architecture, they are encoded in little-endian. Zero leading/trailing bytes are not omitted.
Values of [Float](../../sql-reference/data-types/float.md) and [Decimal](../../sql-reference/data-types/decimal.md) types are encoded as their representation in memory. As we support little-endian architecture, they are encoded in little-endian. Zero leading/trailing bytes are not omitted.
**Arguments**
- `arg` — A value to convert to binary. Types: [String](../../sql-reference/data-types/string.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md) or [DateTime](../../sql-reference/data-types/datetime.md).
- `arg` — A value to convert to binary. [String](../../sql-reference/data-types/string.md), [FixedString](../../sql-reference/data-types/fixedstring.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md), or [DateTime](../../sql-reference/data-types/datetime.md).
**Returned value**
- A string with the binary representation of the argument.
Type: `String`.
Type: [String](../../sql-reference/data-types/string.md).
**Example**
**Examples**
Query:
``` sql
SELECT bin(toFloat32(number)) as bin_presentation FROM numbers(15, 2);
SELECT bin(14);
```
Result:
``` text
┌─bin(14)──┐
│ 00001110 │
└──────────┘
```
Query:
``` sql
SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2);
```
Result:
@ -270,7 +268,7 @@ Result:
Query:
``` sql
SELECT bin(toFloat64(number)) as bin_presentation FROM numbers(15, 2);
SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2);
```
Result:
@ -284,14 +282,7 @@ Result:
## unbin {#unbinstr}
Performs the opposite operation of [bin](#bin). It interprets each pair of binary digits (in the argument) as a number and converts it to the byte represented by the number. The return value is a binary string (BLOB).
If you want to convert the result to a number, you can use the [reverse](../../sql-reference/functions/string-functions.md#reverse) and [reinterpretAs<Type>](../../sql-reference/functions/type-conversion-functions.md#type-conversion-functions) functions.
!!! note "Note"
If `unbin` is invoked from within the `clickhouse-client`, binary strings display using UTF-8.
Alias: `UNBIN`.
Interprets each pair of binary digits (in the argument) as a number and converts it to the byte represented by the number. The functions performs the opposite operation to [bin](#bin).
**Syntax**
@ -299,11 +290,18 @@ Alias: `UNBIN`.
unbin(arg)
```
Alias: `UNBIN`.
For a numeric argument `unbin()` does not return the inverse of `bin()`. If you want to convert the result to a number, you can use the [reverse](../../sql-reference/functions/string-functions.md#reverse) and [reinterpretAs<Type>](../../sql-reference/functions/type-conversion-functions.md#reinterpretasuint8163264) functions.
!!! note "Note"
If `unbin` is invoked from within the `clickhouse-client`, binary strings are displayed using UTF-8.
Supports binary digits `0` and `1`. The number of binary digits does not have to be multiples of eight. If the argument string contains anything other than binary digits, some implementation-defined result is returned (an exception isnt thrown).
**Arguments**
- `arg` — A string containing any number of binary digits. Type: [String](../../sql-reference/data-types/string.md).
Supports binary digits `0-1`. The number of binary digits does not have to be multiples of eight. If the argument string contains anything other than binary digits, some implementation-defined result is returned (an exception isnt thrown). For a numeric argument the inverse of bin(N) is not performed by unbin().
- `arg` — A string containing any number of binary digits. [String](../../sql-reference/data-types/string.md).
**Returned value**
@ -311,7 +309,7 @@ Supports binary digits `0-1`. The number of binary digits does not have to be mu
Type: [String](../../sql-reference/data-types/string.md).
**Example**
**Examples**
Query:
@ -330,14 +328,14 @@ Result:
Query:
``` sql
SELECT reinterpretAsUInt64(reverse(unbin('1010'))) AS num;
SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num;
```
Result:
``` text
┌─num─┐
│ 10
│ 14
└─────┘
```
@ -396,7 +394,7 @@ Result:
Query:
``` sql
select bitPositionsToArray(toInt8(-1)) as bit_positions;
SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions;
```
Result:

View File

@ -17,13 +17,13 @@ char(number_1, [number_2, ..., number_n]);
**Аргументы**
- `number_1, number_2, ..., number_n` — числовые аргументы, которые интерпретируются как целые числа. Типы: [Int](../../sql-reference/functions/encoding-functions.md), [Float](../../sql-reference/functions/encoding-functions.md).
- `number_1, number_2, ..., number_n` — числовые аргументы, которые интерпретируются как целые числа. Типы: [Int](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md).
**Возвращаемое значение**
- Строка из соответствующих байт.
Тип: `String`.
Тип: [String](../../sql-reference/data-types/string.md).
**Пример**
@ -73,61 +73,57 @@ SELECT char(0xE4, 0xBD, 0xA0, 0xE5, 0xA5, 0xBD) AS hello;
## hex {#hex}
Returns a string containing the arguments hexadecimal representation.
Возвращает строку, содержащую шестнадцатеричное представление аргумента.
Синоним: `HEX`.
**Syntax**
**Синтаксис**
``` sql
hex(arg)
```
The function is using uppercase letters `A-F` and not using any prefixes (like `0x`) or suffixes (like `h`).
Функция использует прописные буквы `A-F` и не использует никаких префиксов (например, `0x`) или суффиксов (например, `h`).
For integer arguments, it prints hex digits («nibbles») from the most significant to least significant (big endian or «human readable» order). It starts with the most significant non-zero byte (leading zero bytes are omitted) but always prints both digits of every byte even if leading digit is zero.
Для целочисленных аргументов возвращает шестнадцатеричные цифры от наиболее до наименее значимых (`big endian`, человекочитаемый порядок).Он начинается с самого значимого ненулевого байта (начальные нулевые байты опущены), но всегда выводит обе цифры каждого байта, даже если начальная цифра равна нулю.
Example:
Значения типа [Date](../../sql-reference/data-types/date.md) и [DateTime](../../sql-reference/data-types/datetime.md) формируются как соответствующие целые числа (количество дней с момента Unix-эпохи для `Date` и значение Unix Timestamp для `DateTime`).
**Example**
Для [String](../../sql-reference/data-types/string.md) и [FixedString](../../sql-reference/data-types/fixedstring.md), все байты просто кодируются как два шестнадцатеричных числа. Нулевые байты не опущены.
Query:
Значения [Float](../../sql-reference/data-types/float.md) и [Decimal](../../sql-reference/data-types/decimal.md) кодируются как их представление в памяти. Поскольку ClickHouse поддерживает архитектуру `little-endian`, они кодируются от младшего к старшему байту. Нулевые начальные/конечные байты не опущены.
**Аргументы**
- `arg` — значение для преобразования в шестнадцатеричное. [String](../../sql-reference/data-types/string.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md) или [DateTime](../../sql-reference/data-types/datetime.md).
**Возвращаемое значение**
- Строка — шестнадцатеричное представление аргумента.
Тип: [String](../../sql-reference/data-types/string.md).
**Примеры**
Запрос:
``` sql
SELECT hex(1);
```
Result:
Результат:
``` text
01
```
Values of type `Date` and `DateTime` are formatted as corresponding integers (the number of days since Epoch for Date and the value of Unix Timestamp for DateTime).
For `String` and `FixedString`, all bytes are simply encoded as two hexadecimal numbers. Zero bytes are not omitted.
Values of floating point and Decimal types are encoded as their representation in memory. As we support little endian architecture, they are encoded in little endian. Zero leading/trailing bytes are not omitted.
**Parameters**
- `arg` — A value to convert to hexadecimal. Types: [String](../../sql-reference/functions/encoding-functions.md), [UInt](../../sql-reference/functions/encoding-functions.md), [Float](../../sql-reference/functions/encoding-functions.md), [Decimal](../../sql-reference/functions/encoding-functions.md), [Date](../../sql-reference/functions/encoding-functions.md) or [DateTime](../../sql-reference/functions/encoding-functions.md).
**Returned value**
- A string with the hexadecimal representation of the argument.
Type: `String`.
**Example**
Query:
Запрос:
``` sql
SELECT hex(toFloat32(number)) as hex_presentation FROM numbers(15, 2);
SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2);
```
Result:
Результат:
``` text
┌─hex_presentation─┐
@ -136,13 +132,13 @@ Result:
└──────────────────┘
```
Query:
Запрос:
``` sql
SELECT hex(toFloat64(number)) as hex_presentation FROM numbers(15, 2);
SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2);
```
Result:
Результат:
``` text
┌─hex_presentation─┐
@ -208,6 +204,141 @@ SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num;
└──────┘
```
## bin {#bin}
Возвращает строку, содержащую бинарное представление аргумента.
**Синтаксис**
``` sql
bin(arg)
```
Синоним: `BIN`.
Для целочисленных аргументов возвращаются двоичные числа от наиболее значимого до наименее значимого (`big-endian`, человекочитаемый порядок). Порядок начинается с самого значимого ненулевого байта (начальные нулевые байты опущены), но всегда возвращает восемь цифр каждого байта, если начальная цифра равна нулю.
Значения типа [Date](../../sql-reference/data-types/date.md) и [DateTime](../../sql-reference/data-types/datetime.md) формируются как соответствующие целые числа (количество дней с момента Unix-эпохи для `Date` и значение Unix Timestamp для `DateTime`).
Для [String](../../sql-reference/data-types/string.md) и [FixedString](../../sql-reference/data-types/fixedstring.md) все байты кодируются как восемь двоичных чисел. Нулевые байты не опущены.
Значения [Float](../../sql-reference/data-types/float.md) и [Decimal](../../sql-reference/data-types/decimal.md) кодируются как их представление в памяти. Поскольку ClickHouse поддерживает архитектуру `little-endian`, они кодируются от младшего к старшему байту. Нулевые начальные/конечные байты не опущены.
**Аргументы**
- `arg` — значение для преобразования в двоичный код. [String](../../sql-reference/data-types/string.md), [FixedString](../../sql-reference/data-types/fixedstring.md), [UInt](../../sql-reference/data-types/int-uint.md), [Float](../../sql-reference/data-types/float.md), [Decimal](../../sql-reference/data-types/decimal.md), [Date](../../sql-reference/data-types/date.md) или [DateTime](../../sql-reference/data-types/datetime.md).
**Возвращаемое значение**
- Бинарная строка (BLOB) — двоичное представление аргумента.
Тип: [String](../../sql-reference/data-types/string.md).
**Примеры**
Запрос:
``` sql
SELECT bin(14);
```
Результат:
``` text
┌─bin(14)──┐
│ 00001110 │
└──────────┘
```
Запрос:
``` sql
SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2);
```
Результат:
``` text
┌─bin_presentation─────────────────┐
│ 00000000000000000111000001000001 │
│ 00000000000000001000000001000001 │
└──────────────────────────────────┘
```
Запрос:
``` sql
SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2);
```
Результат:
``` text
┌─bin_presentation─────────────────────────────────────────────────┐
│ 0000000000000000000000000000000000000000000000000010111001000000 │
│ 0000000000000000000000000000000000000000000000000011000001000000 │
└──────────────────────────────────────────────────────────────────┘
```
## unbin {#unbinstr}
Интерпретирует каждую пару двоичных цифр аргумента как число и преобразует его в байт, представленный числом. Функция выполняет операцию, противоположную [bin](#bin).
**Синтаксис**
``` sql
unbin(arg)
```
Синоним: `UNBIN`.
Для числового аргумента `unbin()` не возвращает значение, обратное результату `bin()`. Чтобы преобразовать результат в число, используйте функции [reverse](../../sql-reference/functions/string-functions.md#reverse) и [reinterpretAs<Type>](../../sql-reference/functions/type-conversion-functions.md#reinterpretasuint8163264).
!!! note "Примечание"
Если `unbin` вызывается из клиента `clickhouse-client`, бинарная строка возвращается в кодировке UTF-8.
Поддерживает двоичные цифры `0` и `1`. Количество двоичных цифр не обязательно должно быть кратно восьми. Если строка аргумента содержит что-либо, кроме двоичных цифр, возвращается некоторый результат, определенный реализацией (ошибки не возникает).
**Аргументы**
- `arg` — строка, содержащая любое количество двоичных цифр. [String](../../sql-reference/data-types/string.md).
**Возвращаемое значение**
- Бинарная строка (BLOB).
Тип: [String](../../sql-reference/data-types/string.md).
**Примеры**
Запрос:
``` sql
SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100');
```
Результат:
``` text
┌─unbin('001100000011000100110010')─┬─unbin('0100110101111001010100110101000101001100')─┐
│ 012 │ MySQL │
└───────────────────────────────────┴───────────────────────────────────────────────────┘
```
Запрос:
``` sql
SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num;
```
Результат:
``` text
┌─num─┐
│ 14 │
└─────┘
```
## UUIDStringToNum(str) {#uuidstringtonumstr}
Принимает строку, содержащую 36 символов в формате `123e4567-e89b-12d3-a456-426655440000`, и возвращает в виде набора байт в FixedString(16).
@ -263,7 +394,7 @@ SELECT bitPositionsToArray(toInt8(1)) AS bit_positions;
Запрос:
``` sql
select bitPositionsToArray(toInt8(-1)) as bit_positions;
SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions;
```
Результат: