函数

函数是完成特定任务的可重用代码块。在需要这项任务的任何时候，您都可以在脚本中使用该函数。这样就省去了每次需要时在脚本中添加该任务代码所需的时间和精力。此外，它还能减少脚本中的代码量，从而使脚本更整洁、不凌乱。

函数可以：

• 从脚本中获取数据，以某种方式对其进行处理，然后将结果返回给脚本。
• 执行一个或一系列操作，并将结果数据传递给脚本。

有些函数已内置在 Studio 中，以便在脚本中使用。无需向脚本添加任何内容即可使用内置函数。要使用某个函数时，只需调用即可。

您还可以创建自己的自定义函数，以便在脚本中使用。当您的脚本中有经常使用的代码时，这会很有帮助。您可以创建一个包含代码的函数，而不是每次需要时都将其添加到脚本中。然后，当您需要该代码时，即可调用该函数。

语法

函数名称末尾有一组左圆括号和右圆括号：functionName()。

括号内的任何文本都是参数，定义了函数与脚本之间传递的数据：functionName(param1,param2)。

要创建自定义函数，请使用以下语法：

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

在此语法中：

• FUNCTION 是所有自定义函数语句开头的必填关键字。
• <name> 是函数名称。
• ([<parameter>] [...]) 定义函数所需的任何参数。
• { ... } 包含函数的代码。
• [RETURN <data>] 是要包含的语句，用于将数据从函数传递到主脚本。

只要遵循以下准则，即可为自定义函数命名任何名称：

• 使用字母数字字符 (a-z, A-Z, 0-9)。

• 名称的第一个字符必须是字母。
• 在名称的任何地方使用下划线字符 ( _ ) 和美元符号 ( $ )。
• 请勿使用保留字或内置函数的名称。

RETURN 语句的语法是：

RETURN 或 RETURN <var>

调用函数时，请使用以下语法之一：

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

形参和实参

许多函数需要使用脚本中的数据。您可以使用形参和实参来实现这一点。

参数在创建函数时定义参数是出现在函数名称后面括号中的变量名。一个函数可以有多个参数。每个参数之间用逗号分隔。如果需要，可以加上空格，但不是必须的。例如，函数 logn(value, base) 有两个参数：value 和 base。

脚本通过参数传入函数的特定数据称为参数。以下示例演示了如何在脚本中使用内置函数 abs(value)。在此示例中，-42 是传入 value 参数的参数。

ASSIGN abVal = abs(-42)

在 Studio 中，所有参数都是必需的。如果函数定义了参数，则在调用函数时必须传入参数值。传入函数的参数数目必须与定义的参数数目相一致。

脚本不会检查参数的类型或格式是否正确。但是，如果参数的类型或格式不符合函数的预期，函数可能无法成功完成，或者结果可能不准确。

如果传入函数的参数过多或过少，在运行脚本时会导致编译错误。内置函数和自定义函数都可能出现这种情况。

参数格式化

调用需要参数的函数时，必须包含传入函数中的参数。请遵循以下准则来格式化参数：

• 如果参数是数字或变量，则无需用单引号或双引号引起来。
• 如果参数是变量，则无需用大括号括起来。
• 如果参数是字母数字而不是变量，则用单引号或双引号引起来。

例如，dateadd() 函数需要三个参数：unit、date 和 value。

Unit 定义了函数要更改的日期部分，如如年份或月份。Date 是要修改的原始日期。而 value 是您希望函数将原始日期的指定单位增加多少。以下示例显示了各部分的格式：

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

unit 是一个字母数字字符串，因此其格式以单引号表示。本例中的 date 是一个变量，因此没有引号。如果传入字符串日期，则需要引号。由于 value 是数字，因此未格式化。

RETURN 语句

RETURN 语句终止函数并将控制权传回脚本。它也可以将数据传回脚本。

RETURN 语句只能以变量值或数组的形式向脚本传递数据。此类语句不能传递多个值，除非这些值是数组或对象的一部分。此类语句无法传递对象，除非对象已先转换为 JSON。如有必要，可以在脚本中将其转换回对象。

RETURN 语句的语法是：

RETURN 或 RETURN <var>

所有向脚本返回值的内置函数均包含一条 RETURN 语句。在您创建的自定义函数中，RETURN 语句是可选的。如果不包含 RETURN 语句，该函数就不能向脚本传递任何值。要使用不包含 RETURN 语句的函数，唯一的方法是像调用 语句一样调用它。

如果在函数中包含 RETURN 语句，该语句必须位于函数的最后一行。

变量可见性

默认情况下，函数中的所有值仅在函数内部可用。当函数结束时，函数中的所有值都将丢失。如果函数包含一条将变量值传回脚本的 RETURN 语句，则只有通过 RETURN 语句传递的值在函数之外可用。

如果在自定义函数中包含存在于主脚本中的变量，则这些变量具有全局作用域。这意味着这些值在函数之外也可以使用，而无需使用 RETURN 语句。同样，如果将函数中的变量声明为全局变量，其值也可在主脚本中使用。这与子脚本中的行为类似。

在表达式中使用函数或将其作为变量的值时，函数将遵循默认行为。然而，如果作为语句调用函数，函数中的所有值都具有全局作用域，可以在函数之外使用。对于不包含 RETURN 的函数，这是其唯一的使用方式。

创建自定义函数

如果您希望在脚本中的多个位置使用代码，可以创建自定义函数。自定义函数只能在创建它的脚本中使用。如果要在其他脚本中使用自定义函数，必须将函数定义代码复制到该脚本中。

您可以在脚本中的一个 Snippet 操作中创建函数，然后在同一脚本的其他 Snippet 操作中调用该函数。如果对包含函数定义的代码片段进行调试，它就会包含在调试中。不过，在调试其他代码片段时，函数不会被包含在内。

声明自定义函数的语法如下：

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION 是一个关键字，让脚本知道后面的内容是一个自定义函数。函数名称必须遵循与脚本中其他实体相同的命名准则：

• 使用字母数字字符 (a-z, A-Z, 0-9)。

• 名称的第一个字符必须是字母。
• 在名称的任何地方使用下划线字符 ( _ ) 和美元符号 ( $ )。
• 请勿使用保留字或内置函数的名称。

如果函数需要参数，请将参数放在函数名末尾的括号之间。如果没有任何参数，括号可以留空。用逗号分隔多个参数。

组成函数的代码放在大括号之间。大括号的位置是灵活的。它们可以与 FUNCTION 关键字和名称放在同一行，也可以分开放置。例如，以下两种情况都是有效的函数定义：

FUNCTION myFunction() { ASSIGN var = "value" } 

FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

如果函数包含一条 RETURN 语句，则它必须是结尾大括号之前的最后一条语句。

函数不接受字符串，不含引号，但如果不含引号且不是数字或布尔值，则假定为变量

有关创建函数的更多信息，请参见声明语句页面。

自定义函数的自动完成帮助

您可以为自定义函数添加自动完成帮助。这是在 Snippet editor 窗口中开始键入函数名称时弹出的工具提示文本。该帮助仅在使用点符号调用函数时出现。

查看图像

您可以使用这些工具提示提供有关函数的有用信息。例如，您可以使用它来定义函数的参数。

要添加自动完成帮助，请在函数声明的同一行添加注释。例如，要创建上图所示的工具提示，函数声明应如下所示：

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}	

如果要在函数中添加自动完成帮助，则包含函数代码的大括号必须与函数定义放在不同的行上。该脚本会将两个正斜杠之后的所有文本视为注释的一部分。如果大括号在同一行，脚本会将其包含在注释中。

在脚本中调用函数

在脚本中使用函数时，必须调用该函数。有三种方法可以调用函数。并非所有选项都适用于所有函数。给定函数的可用选项取决于该函数是否返回值。可以调用一个函数：

• 像语句一样单独调用。该选项适用于所有函数。
• 在使用变量或表达式的位置。该选项仅适用于返回值的函数。
• 使用点符号调用变量。该选项仅适用于返回值的函数。

以语句形式调用函数

语句是包含命令关键字的一行代码，会通知脚本执行何种操作。您可以将函数作为语句使用。使用时，不需要像使用代码片段中的其他语句那样使用特殊的命令关键字。函数中的代码会通知脚本执行何种操作。

您可以将任何函数作为语句调用。如果函数不包含 RETURN 语句，这是调用它的唯一方法。这是因为 RETURN 语句会将数据从函数传回脚本。如果没有 RETURN，以语句形式调用函数是脚本访问该函数中数据的唯一方法。

以语句形式调用函数的语法如下：

<functionName><([parameter], [parameter], [...])>

以下示例显示了以语句形式调用 append() 函数的情况：

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

使用函数代替变量

当函数返回一个值时，可以在使用变量或表达式的任何位置使用它。脚本可以像使用变量值或表达式结果一样使用函数返回的值。

使用函数代替变量的语法如下：

<functionName><([parameter], [parameter], [...])>

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}			

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}	

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}