Merge pull request ClickHouse#79538 from Blargian/source_docs_categories

Docs: make FunctionDocumentation category enum

Author: rschu1ze

src/Common/FunctionDocumentation.cpp

@@ -1,8 +1,17 @@
 #include <Common/FunctionDocumentation.h>
 
+#include <Common/Exception.h>
+
+#include <unordered_map>
+
 namespace DB
 {
 
+namespace ErrorCodes
+{
+    extern const int LOGICAL_ERROR;
+}
+
 std::string FunctionDocumentation::argumentsAsString() const
 {
     std::string res;
@@ -28,4 +37,56 @@ std::string FunctionDocumentation::examplesAsString() const
     return res;
 }
 
+std::string FunctionDocumentation::categoryAsString() const
+{
+    static const std::unordered_map<Category, std::string> category_to_string = {
+        {Category::Unknown, ""}, /// Default enum value for default-constructed FunctionDocumentation objects. Be consistent with other default fields (empty).
+        {Category::Arithmetic, "Arithmetic"},
+        {Category::Array, "Arrays"},
+        {Category::Bit, "Bit"},
+        {Category::Bitmap, "Bitmap"},
+        {Category::Comparison, "Comparison"},
+        {Category::Conditional, "Conditional"},
+        {Category::DateAndTime, "Dates and Times"},
+        {Category::Dictionary, "Dictionary"},
+        {Category::Distance, "Distance"},
+        {Category::EmbeddedDictionary, "Embedded Dictionary"},
+        {Category::Geo, "Geo"},
+        {Category::Encoding, "Encoding"},
+        {Category::Encryption, "Encryption"},
+        {Category::File, "File"},
+        {Category::Hash, "Hash"},
+        {Category::IPAddress, "IP Address"},
+        {Category::Introspection, "Introspection"},
+        {Category::JSON, "JSON"},
+        {Category::Logical, "Logical"},
+        {Category::MachineLearning, "Machine Learning"},
+        {Category::Map, "Map"},
+        {Category::Mathematical, "Mathematical"},
+        {Category::NLP, "Natural Language Processing"},
+        {Category::Nullable, "Nullable"},
+        {Category::Other, "Other"},
+        {Category::RandomNumber, "Random Number"},
+        {Category::Rounding, "Rounding"},
+        {Category::StringReplacement, "String Replacement"},
+        {Category::StringSearch, "String Search"},
+        {Category::StringSplitting, "String Splitting"},
+        {Category::String, "String"},
+        {Category::TimeSeries, "Time Series"},
+        {Category::TimeWindow, "Time Window"},
+        {Category::Tuple, "Tuple"},
+        {Category::TypeConversion, "Type Conversion"},
+        {Category::ULID, "ULID"},
+        {Category::URL, "URL"},
+        {Category::UUID, "UUID"},
+        {Category::UniqTheta, "UniqTheta"},
+        {Category::TableFunction, "Table Functions"}
+    };
+
+    if (auto it = category_to_string.find(category); it != category_to_string.end())
+        return it->second;
+    else
+        throw Exception(ErrorCodes::LOGICAL_ERROR, "Category has no mapping to string");
+}
+
 }

src/Common/FunctionDocumentation.h

@@ -63,20 +63,71 @@ struct FunctionDocumentation
     };
     using Examples = std::vector<Example>;
 
-    using Category = std::string;
+    enum class Category : uint8_t
+    {
+        /// Default category
+        Unknown,
+
+        /// Regular functions
+        Arithmetic,
+        Array,
+        Bit,
+        Bitmap,
+        Comparison,
+        Conditional,
+        DateAndTime,
+        Dictionary,
+        Dynamic,
+        Distance,
+        EmbeddedDictionary,
+        Geo,
+        Encoding,
+        Encryption,
+        File,
+        Hash,
+        IPAddress,
+        Introspection,
+        JSON,
+        Logical,
+        MachineLearning,
+        Map,
+        Mathematical,
+        NLP,
+        Nullable,
+        Other,
+        RandomNumber,
+        Rounding,
+        StringReplacement,
+        StringSearch,
+        StringSplitting,
+        String,
+        TimeSeries,
+        TimeWindow,
+        Tuple,
+        TypeConversion,
+        ULID,
+        URL,
+        UUID,
+        UniqTheta,
+        Variant,
+
+        /// Table functions
+        TableFunction
+    };
 
-    using Related = std::string;
+    using Related = std::vector<std::string>;
 
     /// TODO Fields with {} initialization are optional. We should make all fields non-optional.
-    Description description;           /// E.g. "Returns the position (in bytes, starting at 1) of a substring needle in a string haystack."
-    Syntax syntax {};                  /// E.g. "position(haystack, needle)"
-    Arguments arguments {};            /// E.g. ["haystack — String in which the search is performed. String.", "needle — Substring to be searched. String."]
-    ReturnedValue returned_value {};   /// E.g. "Starting position in bytes and counting from 1, if the substring was found."
-    Examples examples {};              ///
-    Category category {};              /// E.g. "String Search"
+    Description description;                /// E.g. "Returns the position (in bytes, starting at 1) of a substring needle in a string haystack."
+    Syntax syntax {};                       /// E.g. "position(haystack, needle)"
+    Arguments arguments {};                 /// E.g. ["haystack — String in which the search is performed. String.", "needle — Substring to be searched. String."]
+    ReturnedValue returned_value {};        /// E.g. "Starting position in bytes and counting from 1, if the substring was found."
+    Examples examples {};                   ///
+    Category category;                      /// E.g. Category::DatesAndTimes
 
     std::string argumentsAsString() const;
     std::string examplesAsString() const;
+    std::string categoryAsString() const;
 };
 
 }

src/Functions/FunctionGenerateRandomStructure.cpp

@@ -450,7 +450,7 @@ The function returns a value of type String.
                 {"with specified number of columns", "SELECT generateRandomStructure(3)", "c1 String, c2 Array(Int32), c3 LowCardinality(String)"},
                 {"with specified seed", "SELECT generateRandomStructure(1, 42)", "c1 UInt128"},
             },
-            .category{"Random Numbers"}
+            .category = FunctionDocumentation::Category::RandomNumber
         });
 }
 

src/Functions/FunctionsCodingULID.cpp

@@ -179,8 +179,9 @@ An optional second argument can be passed to specify a timezone for the timestam
 )",
             .examples{
                 {"ulid", "SELECT ULIDStringToDateTime(generateULID())", ""},
-                {"timezone", "SELECT ULIDStringToDateTime(generateULID(), 'Asia/Istanbul')", ""}},
-            .category{"ULID"}
+                {"timezone", "SELECT ULIDStringToDateTime(generateULID(), 'Asia/Istanbul')", ""}
+            },
+            .category = FunctionDocumentation::Category::ULID
         });
 }
 

src/Functions/FunctionsCodingUUID.cpp

@@ -496,7 +496,7 @@ This function accepts a UUID and returns a FixedString(16) as its binary represe
 │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │ @</a];!~p{jTj={) │
 └──────────────────────────────────────┴──────────────────┴──────────────────┘
 )"}},
-            .category{"UUID"}});
+            .category = FunctionDocumentation::Category::UUID});
 
 
     factory.registerFunction<FunctionUUIDv7ToDateTime>(
@@ -509,7 +509,7 @@ An optional second argument can be passed to specify a timezone for the timestam
             .examples{
                 {"uuid","select UUIDv7ToDateTime(generateUUIDv7())", ""},
                 {"uuid","select generateUUIDv7() as uuid, UUIDv7ToDateTime(uuid), UUIDv7ToDateTime(uuid, 'America/New_York')", ""}},
-            .category{"UUID"}});
+            .category = FunctionDocumentation::Category::UUID});
 }
 
 }

src/Functions/FunctionsConversion_reg.cpp

@@ -26,7 +26,7 @@ Converts Float32 to BFloat16 with losing the precision.
 )",
         .examples{
             {"typical", "SELECT toBFloat16(12.3::Float32);", "12.3125"}},
-        .category{"Type Conversion"}});
+        .category = FunctionDocumentation::Category::TypeConversion});
 
     factory.registerFunction<detail::FunctionToFloat32>();
     factory.registerFunction<detail::FunctionToFloat64>();
@@ -89,7 +89,7 @@ Example of a loss of precision:
             {"invalid1", "SELECT toBFloat16OrZero('abc');", "0"},
             {"invalid2", "SELECT toBFloat16OrZero(' 1');", "0"},
             {"precision", "SELECT toBFloat16OrZero('12.3456789');", "12.375"}},
-        .category{"Type Conversion"}});
+        .category = FunctionDocumentation::Category::TypeConversion});
 
     factory.registerFunction<detail::FunctionToFloat32OrZero>();
     factory.registerFunction<detail::FunctionToFloat64OrZero>();
@@ -142,7 +142,7 @@ Example of a loss of precision:
         {"invalid1", "SELECT toBFloat16OrNull('abc');", "NULL"},
         {"invalid2", "SELECT toBFloat16OrNull(' 1');", "NULL"},
         {"precision", "SELECT toBFloat16OrNull('12.3456789');", "12.375"}},
-    .category{"Type Conversion"}});
+    .category = FunctionDocumentation::Category::TypeConversion});
 
     factory.registerFunction<detail::FunctionToFloat32OrNull>();
     factory.registerFunction<detail::FunctionToFloat64OrNull>();