xxx()

主函数。这是计算函数结果的地方。SQL 函数数据类型与 C++ 函数的返回类型之间的对应关系如下所示。

还可以声明一个 DECIMAL 函数，但值将作为字符串返回，因此您应该像编写 STRING 函数一样编写函数。 ROW 函数未实现。

xxx_init()

xxx() 的初始化函数。如果存在，它可用于以下目的：

xxx_deinit()

xxx() 的去初始化函数。如果存在，它应该释放初始化函数分配的任何内存。

xxx_clear()

重置当前聚合值，但不将参数插入为新组的初始聚合值。

xxx_add()

将参数添加到当前聚合值。

bool maybe_null

如果 xxx() 可以返回 NULL，则 xxx_init() 应该将 maybe_null 设置为 1。如果任何参数声明为 maybe_null，则默认值为 1。

unsigned int decimals

小数点右侧的十进制数字数。默认值为传递给主函数的参数中的最大十进制数字数。例如，如果函数传递了 1.34、1.345 和 1.3，则默认值为 3，因为 1.345 有 3 个十进制数字。

对于没有固定小数位数的参数，decimals 值设置为 31，这比允许的 DECIMAL、FLOAT 和 DOUBLE 数据类型的最大小数位数多 1。此值在 mysql_com.h 头文件中作为常量 NOT_FIXED_DEC 可用。

在以下情况下，decimals 值为 31 用于参数：例如，FLOAT 或 DOUBLE 列声明时没有显式的小数位数（例如，FLOAT 而不是 FLOAT(10,3)），以及浮点常量，如 1345E-3。它也用于字符串和其他可能在函数内部转换为数值形式的非数值参数。

decimals 成员初始化的值只是一个默认值。它可以在函数内部更改以反映执行的实际计算。默认值由参数的最大小数位数决定。如果参数之一的小数位数为 NOT_FIXED_DEC，则使用该值作为 decimals 的值。

无符号整数 max_length

结果的最大长度。默认的 max_length 值取决于函数的结果类型。对于字符串函数，默认值为最长参数的长度。对于整数函数，默认值为 21 位。对于实数函数，默认值为 13 加上由 initid->decimals 指示的小数位数。（对于数值函数，长度包括任何符号或小数点字符。）

如果要返回一个 blob 值，可以将 max_length 设置为 65KB 或 16MB。这部分内存不会分配，但该值用于在需要临时存储数据时决定使用哪种数据类型。

字符 *ptr

函数可以将其用于自身目的的指针。例如，函数可以使用 initid->ptr 在彼此之间传递分配的内存。 xxx_init() 应该分配内存并将其赋予此指针。

initid->ptr = allocated_memory;

在 xxx() 和 xxx_deinit() 中，请参考 initid->ptr 来使用或释放内存。

布尔 const_item

xxx_init() 应该将 const_item 设置为 1（如果 xxx() 始终返回相同的值）或设置为 0（否则）。

xxx_reset()

当 MySQL 在一个新组中找到第一行时，就会调用此函数。它应该重置任何内部汇总变量，然后使用给定的 UDF_ARGS 参数作为该组的内部汇总值的第一个值。声明 xxx_reset() 如下

void xxx_reset(UDF_INIT *initid, UDF_ARGS *args,
               char *is_null, char *error);

xxx_reset() 在 MySQL 8.4 中不需要也不使用，在 MySQL 8.4 中，可加载函数接口使用 xxx_clear() 而不是 xxx_reset()。但是，如果您希望您的函数与旧版本的服务器一起使用，可以同时定义 xxx_reset() 和 xxx_clear()。（如果您确实同时包含了这两个函数，在许多情况下，xxx_reset() 函数可以在内部通过调用 xxx_clear() 来重置所有变量，然后调用 xxx_add() 来添加 UDF_ARGS 参数作为组中的第一个值。）

xxx_clear()

当 MySQL 需要重置汇总结果时，就会调用此函数。它会在每个新组的开始被调用，但也可以在没有匹配行的查询中被调用来重置值。声明 xxx_clear() 如下

void xxx_clear(UDF_INIT *initid, char *is_null, char *error);

在调用 xxx_clear() 之前，is_null 被设置为指向 CHAR(0)。

如果出现错误，您可以将值存储在 error 参数指向的变量中。 error 指向一个单字节变量，而不是字符串缓冲区。

xxx_clear() 是 MySQL 8.4 所要求的。

xxx_add()

此函数将针对属于同一个组的所有行调用。您应该使用它将 UDF_ARGS 参数中的值添加到您的内部汇总变量中。

void xxx_add(UDF_INIT *initid, UDF_ARGS *args,
             char *is_null, char *error);

无符号整数 arg_count

参数数量。如果您的函数需要以特定数量的参数调用，请在初始化函数中检查此值。例如

if (args->arg_count != 2)
{
    strcpy(message,"XXX() requires two arguments");
    return 1;
}

对于其他值为数组的 UDF_ARGS 成员值，数组引用是从零开始的。也就是说，使用从 0 到 args->arg_count − 1 的索引值来引用数组成员。

枚举 Item_result *arg_type

指向包含每个参数类型的数组的指针。可能的类型值为 STRING_RESULT、INT_RESULT、REAL_RESULT 和 DECIMAL_RESULT。

为了确保参数具有给定的类型，并在参数类型不匹配时返回错误，请在初始化函数中检查 arg_type 数组。例如

if (args->arg_type[0] != STRING_RESULT ||
    args->arg_type[1] != INT_RESULT)
{
    strcpy(message,"XXX() requires a string and an integer");
    return 1;
}

类型为 DECIMAL_RESULT 的参数以字符串形式传递，因此您应该以与处理 STRING_RESULT 值相同的方式来处理它们。

作为要求函数参数具有特定类型的替代方法，您可以使用初始化函数将 arg_type 元素设置为所需的类型。这会导致 MySQL 在每次调用 xxx() 时将参数强制转换为这些类型。例如，要指定前两个参数应该分别强制转换为字符串和整数，请在 xxx_init() 中执行此操作。

args->arg_type[0] = STRING_RESULT;
args->arg_type[1] = INT_RESULT;

精确值小数参数（如 1.3 或 DECIMAL 列值）以 DECIMAL_RESULT 类型的形式传递。但是，这些值是以字符串形式传递的。要接收数字，请使用初始化函数指定参数应该强制转换为 REAL_RESULT 值

args->arg_type[2] = REAL_RESULT;

字符 **args

args->args 将有关传递给函数的参数的通用性质的信息传递给初始化函数。对于常量参数 i，args->args[i] 指向参数值。（有关如何正确访问该值的说明，请参见后面部分。）对于非常量参数，args->args[i] 为 0。常量参数是只使用常量的表达式，例如 3 或 4*7-2 或 SIN(3.14)。非常量参数是指可能在行之间发生变化的值的表达式，例如列名或使用非常量参数调用的函数。

对于主函数的每次调用，args->args 都包含当前正在处理的行传递的实际参数。

如果参数 i 代表 NULL，args->args[i] 是一个空指针（0）。如果参数不是 NULL，函数可以按以下方式引用它

无符号长整型 *lengths

对于初始化函数，lengths 数组表示每个参数的最大字符串长度。您不应该更改这些。对于主函数的每次调用，lengths 都包含当前正在处理的行传递的任何字符串参数的实际长度。对于类型为 INT_RESULT 或 REAL_RESULT 的参数，lengths 仍然包含参数的最大长度（与初始化函数相同）。

字符 *maybe_null

对于初始化函数，maybe_null 数组表示每个参数的值是否可能为 null（0 表示否，1 表示是）。

字符 **attributes

args->attributes 传递有关函数参数名称的信息。对于参数 i，属性名称可以在 args->attributes[i] 中以字符串形式获取，属性长度为 args->attribute_lengths[i]。不要假设字符串以 null 结尾。

默认情况下，函数参数的名称是用于指定参数的表达式的文本。对于可加载函数，参数也可以有一个可选的 [AS] alias_name 子句，在这种情况下，参数名称为 alias_name。因此，每个参数的 attributes 值取决于是否给出了别名。

假设一个可加载函数 my_udf() 被调用如下

SELECT my_udf(expr1, expr2 AS alias1, expr3 alias2);

在这种情况下，attributes 和 attribute_lengths 数组将具有以下值

args->attributes[0] = "expr1"
args->attribute_lengths[0] = 5

args->attributes[1] = "alias1"
args->attribute_lengths[1] = 6

args->attributes[2] = "alias2"
args->attribute_lengths[2] = 6

无符号长整型 *attribute_lengths

attribute_lengths 数组指示每个参数名称的长度。

关于它们传递给可加载函数的参数，应用程序将继续工作，因为该函数现在能够处理任何字符集中的字符串参数，包括二进制字符串。

如果可加载函数要以与其参数的字符集不同的字符集返回字符串结果，则该函数必须在内部执行字符集转换。例如，如果函数接受 latin1 参数，但返回 utf8mb4 结果，就会出现这种情况。

metaphon() 返回字符串参数的元音字符串。这有点像 soundex 字符串，但它更适合英语。

myfunc_double() 返回其参数中字符的 ASCII 值之和，除以其参数的长度之和。

myfunc_int() 返回其参数的长度之和。

sequence([const int]) 返回从给定数字或 1（如果未给出数字）开始的序列。

lookup() 返回主机名的 IP 地址。

reverse_lookup() 返回 IP 地址的主机名。该函数可以使用 'xxx.xxx.xxx.xxx' 形式的单个字符串参数调用，也可以使用四个数字调用。

avgcost() 返回平均成本。这是一个聚合函数。