函數

函數是可重複使用的代碼塊，用於完成特定任務。任何時候，只要您需要這項任務，就可以在指令碼中使用該函數。這樣，您就可以省去每次需要時在指令碼中新增該任務代碼所需的時間和精力。它還能減少指令碼中的代碼量，從而使指令碼更整潔、不淩亂。

函數可以：

  • 從指令碼中獲取資料，以某種方式對其進行處理，然後將結果返回給指令碼。
  • 執行一個或一系列動作，並將結果資料傳遞給指令碼。

某些函數已內建至 Studio，供您在指令碼中使用。使用內建函數無需在指令碼中新增任何內容。當您想使用其中一個時，只需 調用它即可。

您還可以建立自己的自訂函數，以便在指令碼中使用。當您的指令碼中有經常使用的代碼時，這將很有幫助。與其每次需要時都將其新增到指令碼中，不如建立一個包含代碼的函數。然後，當您需要該代碼時，就可以調用該函數。

使用函數的範例可供您下載並匯入 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 動作中調用該函數。如果對包含函數定義的 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 視窗中開始鍵入函數名稱時彈出的工具提示文字。該幫助僅在使用點符號調用函數時才會出現。

Snippet 編輯器視窗中顯示 IntelliPrompt 幫助的「文字視圖」標籤的範例。

您可以使用這些工具提示提供有關函數的有用資訊。例如，您可以用它來定義函數的參數。

要新增自動完成說明，請在函數聲明的同一行新增備註。例如，要建立上圖所示的工具提示，函數聲明應如下所示：

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

如果在函數中新增自動完成說明，包含函數代碼的大括號必須與函數定義分開放置在單獨一行。指令碼將兩個正斜杠後的所有文字視為備註的一部分。如果大括號在同一行，指令碼會將其包含在備註中。

在指令碼中調用函數

在指令碼中使用函數時，必須調用該函數。有三種方法可以調用函數。並非所有選項都適用於所有函數。特定函數的可用選項取決於函數是否返回值。您可以調用函數：

  • 單獨像一個語句。此選項適用於所有函數。
  • 在使用變數或運算式的地方。該選項僅適用於返回值的函數。
  • 使用點符號的變數。該選項僅適用於返回值的函數。

以語句形式調用函數

語句是帶有命令關鍵字的一行代碼，它會告訴指令碼要執行的動作。您可以使用函數作為語句。當您這樣操作時，不需要特殊的命令關鍵字，就像 snippet 中的 其他語句一樣。函數中的代碼告訴指令碼要執行的動作。

您可以以語句的形式調用任何函數。如果函數不包含 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], [...])>}>

如果希望將函數結果賦值給變數，可以在 ASSIGN 語句中調用函數。例如，ASSIGN var = otherVar.function()。但是，有一種情況下，這種方法不起作用，那就是調用GetRESTproxy() 函數的成員函數。

下面的範例展示了如何使用返回值的函數。這就是範例函數：

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

該函數用單詞 and 代替安培字元 ( & )。在下面的範例中，replaceCharacters() 函數用於代替 stringRes 變數字串值中的變數。該代碼運行時，stringRes 的值將更新為 My favorite animals are dogs and cats.。

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

使用帶點符號的函數

當函數返回值時，可以使用點符號將其與變數一起使用。這樣就會將函數附加到了變數上，就像這樣：variable.function().以這種方式調用函數時，變數的值會傳入函數。該選項僅適用於返回值的函數。

使用點符號的函數語法：

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

下面的範例展示了這種方法。這是函數：

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

這是 FOR 迴圈，使用了帶有變數 ph 的 MyAppend 函數：

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

FOR 迴圈的結果是 ph="123456789"。

使用點符號調用函數時，所連接變數的值會作為第一個參數的隱式參數傳遞給函數。在上例中，ph 的初始值作為參數 a 的隱式參數傳遞給 MyAppend() 函數。這就是為什麼函數調用只包含一個隱式參數，而函數定義有兩個參數。i 的初始值作為參數 b 的隱式參數傳遞給函數。

使用點符號調用函數的好處是可以為函數新增工具提示說明。