Skip to content

Commit b735fd3

Browse files
BlargianBlargian
authored
Merge pull request ClickHouse#78875 from Blargian/move_arithmetic_documentation_to_source
Docs: move arithmetic functions documentation to source
2 parents cb4833a + 1cae48a commit b735fd3

22 files changed

+369
-155
lines changed

‎src/Functions/abs.cpp‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,15 @@ template <> struct FunctionUnaryArithmeticMonotonicity<NameAbs>
5151

5252
REGISTER_FUNCTION(Abs)
5353
{
54-
factory.registerFunction<FunctionAbs>({}, FunctionFactory::Case::Insensitive);
54+
FunctionDocumentation::Description description = "Calculates the absolute value of `x`. Has no effect if `x` is of an unsigned type. If `x` is of a signed type, it returns an unsigned number.";
55+
FunctionDocumentation::Syntax syntax = "abs(x)";
56+
FunctionDocumentation::Arguments argument = {{"x", "Value to get the absolute value of"}};
57+
FunctionDocumentation::ReturnedValue returned_value = "The absolute value of `x`";
58+
FunctionDocumentation::Examples examples = {{"", "SELECT abs(-0.5)", "0.5"}};
59+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
60+
FunctionDocumentation documentation = {description, syntax, argument, returned_value, examples, categories};
61+
62+
factory.registerFunction<FunctionAbs>(documentation, FunctionFactory::Case::Insensitive);
5563
}
5664

5765
}

‎src/Functions/byteSwap.cpp‎

Lines changed: 18 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -62,46 +62,35 @@ struct FunctionUnaryArithmeticMonotonicity<NameByteSwap>
6262

6363
REGISTER_FUNCTION(ByteSwap)
6464
{
65-
factory.registerFunction<FunctionByteSwap>(
66-
FunctionDocumentation{
67-
.description = R"(
65+
FunctionDocumentation::Description description = R"(
6866
Reverses the bytes of an integer, i.e. changes its [endianness](https://en.wikipedia.org/wiki/Endianness).
6967
70-
**Example**
68+
The below example can be worked out in the following manner:
7169
72-
```sql
73-
byteSwap(3351772109)
74-
```
75-
76-
Result:
77-
78-
```result
79-
┌─byteSwap(3351772109)─┐
80-
│ 3455829959 │
81-
└──────────────────────┘
82-
```
83-
84-
The above example can be worked out in the following manner:
8570
1. Convert the base-10 integer to its equivalent hexadecimal format in big-endian format, i.e. 3351772109 -> C7 C7 FB CD (4 bytes)
8671
2. Reverse the bytes, i.e. C7 C7 FB CD -> CD FB C7 C7
87-
3. Convert the result back to an integer assuming big-endian, i.e. CD FB C7 C7 -> 3455829959
88-
89-
One use-case of this function is reversing IPv4s:
72+
3. Convert the result back to an integer assuming big-endian, i.e. CD FB C7 C7 -> 3455829959
73+
One use case of this function is reversing IPv4s:
9074
9175
```result
9276
┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
9377
│ 199.199.251.205 │
9478
└───────────────────────────────────────────────────────┘
9579
```
96-
)",
97-
.examples{
98-
{"8-bit", "SELECT byteSwap(54)", "54"},
99-
{"16-bit", "SELECT byteSwap(4135)", "10000"},
100-
{"32-bit", "SELECT byteSwap(3351772109)", "3455829959"},
101-
{"64-bit", "SELECT byteSwap(123294967295)", "18439412204227788800"},
102-
},
103-
.category = FunctionDocumentation::Category::Arithmetic},
104-
FunctionFactory::Case::Insensitive);
80+
)";
81+
FunctionDocumentation::Syntax syntax = "byteSwap(x)";
82+
FunctionDocumentation::Argument argument1 = {"x", "An integer value."};
83+
FunctionDocumentation::Arguments arguments = {argument1};
84+
FunctionDocumentation::ReturnedValue returned_value = "x with bytes reversed";
85+
FunctionDocumentation::Example example1 = {"", "SELECT byteSwap(3351772109)", "3455829959"};
86+
FunctionDocumentation::Example example2 = {"8-bit", "SELECT byteSwap(54)", "54"};
87+
FunctionDocumentation::Example example3 = {"16-bit", "SELECT byteSwap(4135)", "10000"};
88+
FunctionDocumentation::Example example4 = {"32-bit", "SELECT byteSwap(3351772109)", "3455829959"};
89+
FunctionDocumentation::Example example5 = {"64-bit", "SELECT byteSwap(123294967295)", "18439412204227788800"};
90+
FunctionDocumentation::Examples examples = {example1, example2, example3, example4, example5};
91+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
92+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
93+
factory.registerFunction<FunctionByteSwap>(documentation,FunctionFactory::Case::Insensitive);
10594
}
10695

10796
}

‎src/Functions/divide.cpp‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,26 @@ using FunctionDivide = BinaryArithmeticOverloadResolver<DivideFloatingImpl, Name
4141

4242
REGISTER_FUNCTION(Divide)
4343
{
44-
factory.registerFunction<FunctionDivide>();
44+
FunctionDocumentation::Description description = R"(
45+
Calculates the quotient of two values `a` and `b`. The result type is always [Float64](/sql-reference/data-types/float).
46+
Integer division is provided by the `intDiv` function.
47+
48+
:::note
49+
Division by `0` returns `inf`, `-inf`, or `nan`.
50+
:::
51+
)";
52+
FunctionDocumentation::Syntax syntax = "divide(x, y)";
53+
FunctionDocumentation::Argument argument1 = {"x", "Dividend"};
54+
FunctionDocumentation::Argument argument2 = {"y", "Divisor"};
55+
FunctionDocumentation::Arguments arguments = {argument1, argument2};
56+
FunctionDocumentation::ReturnedValue returned_value = "The quotient of x and y";
57+
FunctionDocumentation::Example example1 = {"Dividing two numbers", "SELECT divide(25,5) AS quotient, toTypeName(quotient)", "5 Float64"};
58+
FunctionDocumentation::Example example2 = {"Dividing by zero", "SELECT divide(25,0)", "inf"};
59+
FunctionDocumentation::Examples examples = {example1, example2};
60+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
61+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
62+
63+
factory.registerFunction<FunctionDivide>(documentation);
4564
}
4665

4766
struct NameDivideOrNull { static constexpr auto name = "divideOrNull"; };

‎src/Functions/divideDecimal.cpp‎

Lines changed: 21 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -59,57 +59,43 @@ struct DivideDecimalsImpl
5959

6060
REGISTER_FUNCTION(DivideDecimals)
6161
{
62-
factory.registerFunction<FunctionsDecimalArithmetics<DivideDecimalsImpl>>(FunctionDocumentation{
63-
.description = R"(
64-
Performs division on two decimals. Result value will be of type [Decimal256](../../sql-reference/data-types/decimal.md).
62+
FunctionDocumentation::Description description = R"(
63+
Performs division on two decimals. Result value will be of type [Decimal256](/sql-reference/data-types/decimal).
6564
Result scale can be explicitly specified by `result_scale` argument (const Integer in range `[0, 76]`). If not specified, the result scale is the max scale of given arguments.
6665
6766
:::note
6867
These function work significantly slower than usual `divide`.
6968
In case you don't really need controlled precision and/or need fast computation, consider using [divide](#divide).
70-
:::)",
71-
.syntax = "divideDecimal(a, b[, result_scale])",
72-
.arguments = {
73-
{"a", "First value: [Decimal](../../sql-reference/data-types/decimal.md)"},
74-
{"b", "Second value: [Decimal](../../sql-reference/data-types/decimal.md)."}
75-
},
76-
.returned_value = "The result of division with given scale. Type: [Decimal256](../../sql-reference/data-types/decimal.md).",
77-
.examples = {
78-
{"", "divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)",
79-
R"(
69+
:::
70+
)";
71+
FunctionDocumentation::Syntax syntax = "divideDecimal(x, y[, result_scale])";
72+
FunctionDocumentation::Argument argument1 = {"x", "First value: [Decimal](/sql-reference/data-types/decimal)."};
73+
FunctionDocumentation::Argument argument2 = {"y", "Second value: [Decimal](/sql-reference/data-types/decimal)."};
74+
FunctionDocumentation::Argument argument3 = {"result_scale", "Scale of result. Type [Int/UInt](/sql-reference/data-types/int-uint)."};
75+
FunctionDocumentation::Arguments arguments = {argument1, argument2, argument3};
76+
FunctionDocumentation::ReturnedValue returned_value = "The result of division with given scale. Type: [Decimal256](/sql-reference/data-types/decimal.md).";
77+
FunctionDocumentation::Example example1 = {"", "divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)", R"(
8078
┌─divideDecimal(toDecimal256(-12, 0), toDecimal32(2.1, 1), 10)─┐
8179
│ -5.7142857142 │
8280
└──────────────────────────────────────────────────────────────┘
83-
)"}, {"Difference to regular division",
84-
85-
R"(
81+
)"};
82+
FunctionDocumentation::Example example2 = {"",
83+
R"(
8684
SELECT toDecimal64(-12, 1) / toDecimal32(2.1, 1);
8785
SELECT toDecimal64(-12, 1) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
88-
)",
89-
R"(
86+
)",
87+
R"(
9088
┌─divide(toDecimal64(-12, 1), toDecimal32(2.1, 1))─┐
9189
│ -5.7 │
9290
└──────────────────────────────────────────────────┘
9391
┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 1), toDecimal32(2.1, 1), 5)─┐
9492
│ -12 │ 2.1 │ -5.7 │ -5.71428 │
9593
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
96-
)"
97-
},
98-
{"",
99-
R"(
100-
SELECT toDecimal64(-12, 0) / toDecimal32(2.1, 1);
101-
SELECT toDecimal64(-12, 0) as a, toDecimal32(2.1, 1) as b, divideDecimal(a, b, 1), divideDecimal(a, b, 5);
102-
)",
103-
R"(
104-
DB::Exception: Decimal result's scale is less than argument's one: While processing toDecimal64(-12, 0) / toDecimal32(2.1, 1). (ARGUMENT_OUT_OF_BOUND)
105-
┌───a─┬───b─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 1)─┬─divideDecimal(toDecimal64(-12, 0), toDecimal32(2.1, 1), 5)─┐
106-
│ -12 │ 2.1 │ -5.7 │ -5.71428 │
107-
└─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
108-
)"}
109-
},
110-
.category = FunctionDocumentation::Category::TypeConversion
111-
}
112-
);
94+
)"};
95+
FunctionDocumentation::Examples examples = {example1, example2};
96+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
97+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
98+
factory.registerFunction<FunctionsDecimalArithmetics<DivideDecimalsImpl>>(documentation);
11399
}
114100

115101
}

‎src/Functions/gcd.cpp‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,23 @@ using FunctionGCD = BinaryArithmeticOverloadResolver<GCDImpl, NameGCD, false, fa
3131

3232
REGISTER_FUNCTION(GCD)
3333
{
34-
factory.registerFunction<FunctionGCD>();
34+
FunctionDocumentation::Description description = R"(
35+
Returns the greatest common divisor of two values a and b.
36+
37+
An exception is thrown when dividing by zero or when dividing a minimal
38+
negative number by minus one.
39+
)";
40+
FunctionDocumentation::Syntax syntax = "gcd(x, y)";
41+
FunctionDocumentation::Argument argument1 = {"x", "First integer"};
42+
FunctionDocumentation::Argument argument2 = {"y", "Second integer"};
43+
FunctionDocumentation::Arguments arguments = {argument1, argument2};
44+
FunctionDocumentation::ReturnedValue returned_value = "The greatest common divisor of `x` and `y`.";
45+
FunctionDocumentation::Example example1 = {"", "SELECT gcd(12, 18)", "6"};
46+
FunctionDocumentation::Examples examples = {example1};
47+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
48+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
49+
50+
factory.registerFunction<FunctionGCD>(documentation);
3551
}
3652

3753
}

‎src/Functions/ifNotFinite.cpp‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,24 @@ class FunctionIfNotFinite : public IFunction
6666

6767
REGISTER_FUNCTION(IfNotFinite)
6868
{
69-
factory.registerFunction<FunctionIfNotFinite>();
69+
FunctionDocumentation::Description description = R"(
70+
Checks whether a floating point value is finite.
71+
72+
You can get a similar result by using the [ternary operator](/sql-reference/functions/conditional-functions#if): `isFinite(x) ? x : y`.
73+
)";
74+
FunctionDocumentation::Syntax syntax = "ifNotFinite(x,y)";
75+
FunctionDocumentation::Argument argument1 = {"x", "Value to check if infinite. Float32/Float64"};
76+
FunctionDocumentation::Argument argument2 = {"y", "Fallback value. Float32/Float64"};
77+
FunctionDocumentation::Arguments arguments = {argument1, argument2};
78+
FunctionDocumentation::ReturnedValue returned_value = R"(
79+
- `x` if `x` is finite.
80+
- `y` if `x` is not finite.
81+
)";
82+
FunctionDocumentation::Examples examples = {{"","SELECT 1/0 AS infimum, ifNotFinite(infimum,42)","inf 42"}};
83+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
84+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
85+
86+
factory.registerFunction<FunctionIfNotFinite>(documentation);
7087
}
7188

7289
}

‎src/Functions/intDiv.cpp‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,45 @@ using FunctionIntDiv = BinaryArithmeticOverloadResolver<DivideIntegralImpl, Name
123123

124124
REGISTER_FUNCTION(IntDiv)
125125
{
126-
factory.registerFunction<FunctionIntDiv>();
126+
FunctionDocumentation::Description description = R"(
127+
Performs an integer division of two values `x` by `y`. In other words it
128+
computes the quotient rounded down to the next smallest integer.
129+
130+
The result has the same width as the dividend (the first parameter).
131+
132+
An exception is thrown when dividing by zero, when the quotient does not fit
133+
in the range of the dividend, or when dividing a minimal negative number by minus one.
134+
)";
135+
FunctionDocumentation::Syntax syntax = "intDiv(x, y)";
136+
FunctionDocumentation::Argument argument1 = {"x", "Left hand operand."};
137+
FunctionDocumentation::Argument argument2 = {"y", "Right hand operand."};
138+
FunctionDocumentation::Arguments arguments = {argument1, argument2};
139+
FunctionDocumentation::ReturnedValue returned_value = "Result of integer division of `x` and `y`";
140+
FunctionDocumentation::Example example1 = {"Integer division of two floats", "SELECT intDiv(toFloat64(1), 0.001) AS res, toTypeName(res)", R"(
141+
┌──res─┬─toTypeName(intDiv(toFloat64(1), 0.001))─┐
142+
│ 1000 │ Int64 │
143+
└──────┴─────────────────────────────────────────┘
144+
)"};
145+
FunctionDocumentation::Example example2 = {
146+
"Quotient does not fit in the range of the dividend",
147+
R"(
148+
SELECT
149+
intDiv(1, 0.001) AS res,
150+
toTypeName(res)
151+
)",
152+
R"(
153+
Received exception from server (version 23.2.1):
154+
Code: 153. DB::Exception: Received from localhost:9000. DB::Exception:
155+
Cannot perform integer division, because it will produce infinite or too
156+
large number: While processing intDiv(1, 0.001) AS res, toTypeName(res).
157+
(ILLEGAL_DIVISION)
158+
)"
159+
};
160+
FunctionDocumentation::Examples examples = {example1, example2};
161+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
162+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
163+
164+
factory.registerFunction<FunctionIntDiv>(documentation);
127165
}
128166

129167
struct NameIntDivOrNull { static constexpr auto name = "intDivOrNull"; };

‎src/Functions/intDivOrZero.cpp‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,22 @@ using FunctionIntDivOrZero = BinaryArithmeticOverloadResolver<DivideIntegralOrZe
3131

3232
REGISTER_FUNCTION(IntDivOrZero)
3333
{
34-
factory.registerFunction<FunctionIntDivOrZero>();
34+
FunctionDocumentation::Description description = R"(
35+
Same as `intDiv` but returns zero when dividing by zero or when dividing a
36+
minimal negative number by minus one.
37+
)";
38+
FunctionDocumentation::Syntax syntax = "intDivOrZero(a, b)";
39+
FunctionDocumentation::Argument argument1 = {"a", "Left hand operand."};
40+
FunctionDocumentation::Argument argument2 = {"b", "Right hand operand."};
41+
FunctionDocumentation::Arguments arguments = {argument1, argument2};
42+
FunctionDocumentation::ReturnedValue returned_value = "Result of integer division of a and b, or zero.";
43+
FunctionDocumentation::Example example1 = {"Integer division by zero", "SELECT intDivOrZero(1, 0)","0"};
44+
FunctionDocumentation::Example example2 = {"Dividing a minimal negative number by minus 1", "SELECT intDivOrZero(0.05, -1)","0"};
45+
FunctionDocumentation::Examples examples = {example1, example2};
46+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
47+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
48+
49+
factory.registerFunction<FunctionIntDivOrZero>(documentation);
3550
}
3651

3752
}

‎src/Functions/isFinite.cpp‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,19 @@ using FunctionIsFinite = FunctionNumericPredicate<IsFiniteImpl>;
4040

4141
REGISTER_FUNCTION(IsFinite)
4242
{
43-
factory.registerFunction<FunctionIsFinite>();
43+
FunctionDocumentation::Description description = R"(
44+
Returns `1` if the Float32 or Float64 argument not infinite and not a `NaN`,
45+
otherwise this function returns `0`.
46+
)";
47+
FunctionDocumentation::Syntax syntax = "isFinite(x)";
48+
FunctionDocumentation::Argument argument1 = {"x", "Number to check for finiteness. Float32 or Float64."};
49+
FunctionDocumentation::Arguments arguments = {argument1};
50+
FunctionDocumentation::ReturnedValue returned_value = "`1` if x is not infinite and not `NaN`, otherwise `0`.";
51+
FunctionDocumentation::Examples examples = {{"Test if a number is finite", "SELECT isFinite(inf)", "0"}};
52+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
53+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
54+
55+
factory.registerFunction<FunctionIsFinite>(documentation);
4456
}
4557

4658
}

‎src/Functions/isInfinite.cpp‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,20 @@ using FunctionIsInfinite = FunctionNumericPredicate<IsInfiniteImpl>;
3636

3737
REGISTER_FUNCTION(IsInfinite)
3838
{
39-
factory.registerFunction<FunctionIsInfinite>();
39+
FunctionDocumentation::Description description = R"(
40+
Returns `1` if the Float32 or Float64 argument is infinite, otherwise this function returns `0`.
41+
Note that `0` is returned for a `NaN`.
42+
)";
43+
FunctionDocumentation::Syntax syntax = "isInfinite(x)";
44+
FunctionDocumentation::Argument argument1 = {"x", "Number to check for infiniteness. Float32 or Float64."};
45+
FunctionDocumentation::Arguments arguments = {argument1};
46+
FunctionDocumentation::ReturnedValue returned_value = "`1` if x is infinite, otherwise `0` (including for `NaN`).";
47+
FunctionDocumentation::Examples examples = {{"Test if a number is infinite", "SELECT isInfinite(inf), isInfinite(NaN), isInfinite(10))", "1 0 0"}
48+
};
49+
FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
50+
FunctionDocumentation documentation = {description, syntax, arguments, returned_value, examples, categories};
51+
52+
factory.registerFunction<FunctionIsInfinite>(documentation);
4053
}
4154

4255
}

0 commit comments

Comments
 (0)