Skip to content

Commit e46dbd5

Browse files
BlargianBlargian
authored
Merge pull request ClickHouse#80836 from Blargian/bit_functions_part_2
Docs: move bit functions documentation to source. Part 2.
2 parents 190fdf4 + aa9d7f2 commit e46dbd5

File tree

7 files changed

+123
-15
lines changed

7 files changed

+123
-15
lines changed

‎src/Functions/bitCount.cpp‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,31 @@ template <> struct FunctionUnaryArithmeticMonotonicity<NameBitCount>
5757

5858
REGISTER_FUNCTION(BitCount)
5959
{
60-
factory.registerFunction<FunctionBitCount>();
60+
FunctionDocumentation::Description description = "Calculates the number of bits set to one in the binary representation of a number.";
61+
FunctionDocumentation::Syntax syntax = "bitCount(x)";
62+
FunctionDocumentation::Arguments arguments = {
63+
{"x", "An integer or float value. [`(U)Int*`](/sql-reference/data-types/int-uint)/[`Float32/64`](/sql-reference/data-types/float)."},
64+
};
65+
FunctionDocumentation::ReturnedValue returned_value = R"(
66+
Returns the number of bits set to one in `x`. [`UInt8`](../data-types/int-uint.md).
67+
68+
:::note
69+
The function does not convert the input value to a larger type ([sign extension](https://en.wikipedia.org/wiki/Sign_extension)).
70+
For example: `bitCount(toUInt8(-1)) = 8`.
71+
:::
72+
)";
73+
FunctionDocumentation::Examples examples = {{"Usage example", "SELECT bin(333), bitCount(333);",
74+
R"(
75+
┌─bin(333)─────────┬─bitCount(333)─┐
76+
│ 0000000101001101 │ 5 │
77+
└──────────────────┴───────────────┘
78+
)"}
79+
};
80+
FunctionDocumentation::IntroducedIn introduced_in = {20, 3};
81+
FunctionDocumentation::Category category = FunctionDocumentation::Category::Bit;
82+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
83+
84+
factory.registerFunction<FunctionBitCount>(documentation);
6185
}
6286

6387
}

‎src/Functions/bitHammingDistance.cpp‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,28 @@ using FunctionBitHammingDistance = BinaryArithmeticOverloadResolver<BitHammingDi
5555

5656
REGISTER_FUNCTION(BitHammingDistance)
5757
{
58-
factory.registerFunction<FunctionBitHammingDistance>();
58+
FunctionDocumentation::Description description = R"(
59+
Returns the [Hamming Distance](https://en.wikipedia.org/wiki/Hamming_distance) between the bit representations of two numbers.
60+
Can be used with [`SimHash`](../../sql-reference/functions/hash-functions.md#ngramsimhash) functions for detection of semi-duplicate strings.
61+
The smaller the distance, the more similar the strings are.
62+
)";
63+
FunctionDocumentation::Syntax syntax = "bitHammingDistance(x, y)";
64+
FunctionDocumentation::Arguments arguments = {
65+
{"x", "First number for Hamming distance calculation. [`(U)Int*`](/sql-reference/data-types/int-uint)/[`Float32/64`](/sql-reference/data-types/float)."},
66+
{"y", "Second number for Hamming distance calculation. [`(U)Int*`](/sql-reference/data-types/int-uint)/[`Float32/64`](/sql-reference/data-types/float)."},
67+
};
68+
FunctionDocumentation::ReturnedValue returned_value = "Returns the hamming distance between `x` and `y`. [`UInt8`](../data-types/int-uint.md).";
69+
FunctionDocumentation::Examples examples = {{"Usage example", "SELECT bitHammingDistance(111, 121);",
70+
R"(
71+
┌─bitHammingDistance(111, 121)─┐
72+
│ 3 │
73+
└──────────────────────────────┘
74+
)"}
75+
};
76+
FunctionDocumentation::IntroducedIn introduced_in = {21, 1};
77+
FunctionDocumentation::Category category = FunctionDocumentation::Category::Bit;
78+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
79+
80+
factory.registerFunction<FunctionBitHammingDistance>(documentation);
5981
}
6082
}

‎src/Functions/bitTest.cpp‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,24 @@ using FunctionBitTest = BinaryArithmeticOverloadResolver<BitTestImpl, NameBitTes
5151

5252
REGISTER_FUNCTION(BitTest)
5353
{
54+
FunctionDocumentation::Description description = "Takes any number and converts it into [binary form](https://en.wikipedia.org/wiki/Binary_number), then returns the value of the bit at a specified position. Counting is done right-to-left, starting at 0.";
55+
FunctionDocumentation::Syntax syntax = "bitTest(a, i)";
56+
FunctionDocumentation::Arguments arguments = {
57+
{"a", "Number to convert. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)/[`Float32/64`](/sql-reference/data-types/float)."},
58+
{"i", "Position of the bit to return. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)/[`Float32/64`](/sql-reference/data-types/float)."},
59+
};
60+
FunctionDocumentation::ReturnedValue returned_value = "Returns the value of the bit at position `i` in the binary representation of `a`. [`UInt8`](../data-types/int-uint.md).";
61+
FunctionDocumentation::Examples examples = {{"Usage example", "SELECT bin(2), bitTest(2, 1);",
62+
R"(
63+
┌─bin(2)───┬─bitTest(2, 1)─┐
64+
│ 00000010 │ 1 │
65+
└──────────┴───────────────┘
66+
)"}};
67+
FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
68+
FunctionDocumentation::Category category = FunctionDocumentation::Category::Bit;
69+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
5470

55-
factory.registerFunction<FunctionBitTest>();
71+
factory.registerFunction<FunctionBitTest>(documentation);
5672
}
5773

5874
}

‎src/Functions/bitTestAll.cpp‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,35 @@ using FunctionBitTestAll = FunctionBitTestMany<BitTestAllImpl, NameBitTestAll>;
1919

2020
REGISTER_FUNCTION(BitTestAll)
2121
{
22-
factory.registerFunction<FunctionBitTestAll>();
22+
FunctionDocumentation::Description description = R"(
23+
Returns result of the [logical conjunction](https://en.wikipedia.org/wiki/Logical_conjunction) (AND operator) of all bits at the given positions.
24+
Counts right-to-left, starting at 0.
25+
26+
The logical AND between two bits is true if and only if both input bits are true.
27+
)";
28+
FunctionDocumentation::Syntax syntax = "bitTestAll(a, index1[, index2, ... , indexN])";
29+
FunctionDocumentation::Arguments arguments = {
30+
{"a", "An integer value. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)."},
31+
{"index1[, index2, ... , indexN]", "One or multiple positions of bits. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)."},
32+
};
33+
FunctionDocumentation::ReturnedValue returned_value = "Returns the result of the logical conjunction. [`UInt8`](../data-types/int-uint.md).";
34+
FunctionDocumentation::Examples examples = {{"Usage example 1", "SELECT bitTestAll(43, 0, 1, 3, 5);",
35+
R"(
36+
┌─bin(43)──┬─bitTestAll(43, 0, 1, 3, 5)─┐
37+
│ 00101011 │ 1 │
38+
└──────────┴────────────────────────────┘
39+
)"}, {"Usage example 2", "SELECT bitTestAll(43, 0, 1, 3, 5, 2);",
40+
R"(
41+
┌─bin(43)──┬─bitTestAll(4⋯1, 3, 5, 2)─┐
42+
│ 00101011 │ 0 │
43+
└──────────┴──────────────────────────┘
44+
)"}
45+
};
46+
FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
47+
FunctionDocumentation::Category category = FunctionDocumentation::Category::Bit;
48+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
49+
50+
factory.registerFunction<FunctionBitTestAll>(documentation);
2351
}
2452

2553
}

‎src/Functions/bitTestAny.cpp‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,35 @@ using FunctionBitTestAny = FunctionBitTestMany<BitTestAnyImpl, NameBitTestAny>;
1919

2020
REGISTER_FUNCTION(BitTestAny)
2121
{
22-
factory.registerFunction<FunctionBitTestAny>();
22+
FunctionDocumentation::Description description = R"(
23+
Returns result of the [logical disjunction](https://en.wikipedia.org/wiki/Logical_disjunction) (OR operator) of all bits at the given positions in a number.
24+
Counts right-to-left, starting at 0.
25+
26+
The logical OR between two bits is true if at least one of the input bits is true.
27+
)";
28+
FunctionDocumentation::Syntax syntax = "bitTestAny(a, index1[, index2, ... , indexN])";
29+
FunctionDocumentation::Arguments arguments = {
30+
{"a", "An integer value. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)."},
31+
{"index1[, index2, ... , indexN]", "One or multiple positions of bits. [`(U)Int8/16/32/64`](/sql-reference/data-types/int-uint)."},
32+
};
33+
FunctionDocumentation::ReturnedValue returned_value = "Returns the result of the logical disjunction. [`UInt8`](../data-types/int-uint.md).";
34+
FunctionDocumentation::Examples examples = {{"Usage example 1", "SELECT bitTestAny(43, 0, 2);",
35+
R"(
36+
┌─bin(43)──┬─bitTestAny(43, 0, 2)─┐
37+
│ 00101011 │ 1 │
38+
└──────────┴──────────────────────┘
39+
)"}, {"Usage example 2", "SELECT bitTestAny(43, 4, 2);",
40+
R"(
41+
┌─bin(43)──┬─bitTestAny(43, 4, 2)─┐
42+
│ 00101011 │ 0 │
43+
└──────────┴──────────────────────┘
44+
)"}
45+
};
46+
FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
47+
FunctionDocumentation::Category category = FunctionDocumentation::Category::Bit;
48+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, introduced_in, category};
49+
50+
factory.registerFunction<FunctionBitTestAny>(documentation);
2351
}
2452

2553
}

‎tests/queries/0_stateless/02415_all_new_functions_must_be_documented.reference‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -98,12 +98,7 @@ base58Decode
9898
base58Encode
9999
basename
100100
bin
101-
bitCount
102-
bitHammingDistance
103101
bitPositionsToArray
104-
bitTest
105-
bitTestAll
106-
bitTestAny
107102
bitmapAnd
108103
bitmapAndCardinality
109104
bitmapAndnot

‎tests/queries/0_stateless/02415_all_new_functions_must_have_version_information.reference‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -116,12 +116,7 @@ base58Decode
116116
base58Encode
117117
basename
118118
bin
119-
bitCount
120-
bitHammingDistance
121119
bitPositionsToArray
122-
bitTest
123-
bitTestAll
124-
bitTestAny
125120
bitmapAnd
126121
bitmapAndCardinality
127122
bitmapAndnot

0 commit comments

Comments
 (0)