陣列

陣列是一種儲存一組值的資料結構。 當您擁有相似類型的項目清單時，陣列很有用。 例如，區號、電話號碼或客戶姓名清單。

在 Studio 中可以使用兩種陣列：

• 字串陣列：變數中以豎線分隔的字串。 其儲存字串值，這些值可以由英數字元組成。
• 動態陣列：儲存在動態資料物件中的陣列。

如果您有一個清單，其中的資料是關於單個實體的所有不同類型的資訊，動態資料物件是更適合使用的資料結構。 有關陣列和物件的比較可在資料結構説明頁面上找到。

有關陣列的重要資訊

• 陣列必須至少有兩個元素。 只有一個元素的陣列類似一個常規變數。 這仍然是一個陣列，可以作為陣列調用。 動態陣列也是如此。

• 在 Studio 中，陣列索引從 1 開始。

• 有些 函數 可用於陣列，如 index() 和 indexof()。

• 您可以在字串陣列中使用任何分隔符號。 不過，要進行本地讀取，字串陣列必須使用豎線字元作為分隔符號。

嘗試一下

下載 陣列範例指令碼並將其匯入到 Studio中。 本說明頁面中的許多範例可在範例指令碼中的 Snippet 動作中找到。 您可以開啟 Snippet 編輯器視窗並運行偵錯程式來查看範例。

陣列文法摘要

使用以下文法之一建立字串陣列。

使用其索引為每個元素賦值：

ASSIGN <var>[<index1>] = "<value1>"

ASSIGN <var>[<index2>] = "<value2>"

ASSIGN <var>[<index3>] = "<value3>"

將所有元素值指派給以豎線分隔的字串中的變數：

ASSIGN <var> = "<value1> | <value2> | <value3>"

使用以下文法建立動態陣列：

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

支援動態陣列的其他形式。

要引用字串陣列中的特定元素，請使用此文法：

<var>[index]

要引用動態陣列中的特定元素，請使用此文法：

ASSIGN <var> = <object>.<member>[<index>].<arrayElement>

元素和索引

陣列保留的值稱為元素。 指令碼會記錄陣列中元素的順序。 陣列中的每個元素都有一個數字識別碼，稱為索引號。 索引是根據每個元素在陣列中的位置自動指派。 如果重新排列、新增或刪除元素，其索引可能會變更。

在 Studio 中，陣列索引從 1 開始。 索引必須是正整數。 需要知道索引才能與陣列中的特定元素交互。 如果不知道元素的索引，可以使用 indexof() 函數 來確定。

參見字串陣列的單個元素

在引用字串陣列中的單個元素時，請使用此文法：<arrayElement>[<index>]. 您可以在等號的兩側使用此文法。 例如，您可以用其為元素賦值或引用元素的值，如 為另一個變數賦值時。

範例：

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

在這個範例中，Beowulf 的索引是 1，Sir Gawain 的索引是 2，Byrtnoth 的索引是 3。 以豎線分隔陣列時，這些元素的索引相同：name = "Beowulf|Sir Gawain|Byrhtnoth"。 要確定這種格式陣列的索引，從 1 開始，從左到右數元素。

索引是按數字順序填充

索引是按數字順序逐個填充。 如果您引用了陣列中目前不存在的索引，指令碼將建立該索引，除非您為其賦值，否則該索引將為空。 如果在陣列中引用的元素和前一元素之間不存在索引，指令碼會建立索引。 指令碼新增來填充索引的元素為空。 範例：

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth" 
ASSIGN heroes[6] = "Lancelot"

結果陣列為 heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot"。 指令碼為索引 4 和 5 新增了元素，但由於沒有賦值，所以這些元素是空的。

同樣，如果嘗試從一個不存在的元素中提取值，則會建立該元素。 您試圖引用的元素和上一個元素之間的所有元素也會被建立，並且都是空的。

如果在期望使用數字的上下文中引用了空陣列元素，指令碼會將該值視為零。

確定下一個未使用的索引

為了避免在陣列中建立不必要的空元素，可以確定下一個未使用的索引。 您必須數出陣列中的元素，然後在這個數字上加 1。 這樣就得到了下一個開啟的索引號。

要做到這一點，請使用 size() 函數。 範例：

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"  
ASSIGN nextIndex = heroes.size() + 1
ASSIGN heroes[nextIndex] = Roland

在本例中，heroes.size() 返回名稱陣列中元素的個數。 totalNames 的值是 3。 在陣列中新增一個元素，並用 nextIndex 變數代替索引號，就可以在陣列中新增一個元素。

您還可以使用 count() 功能。

字串陣列

字串陣列有兩種定義方式。 第一種是為每個元素單獨明確命名。 下面的範例顯示了一個字串陣列，其中包含逐個元素定義的文字值。

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

陣列名稱之後方括號中的數字是元素的索引號。 這是每個元素的識別碼。

定義字串陣列的第二種方法是使用豎線分隔字串，在每個元素之間使用一個豎線字元 (|)。 該範例顯示了第一個範例中以豎線分隔字串定義的陣列。 建立豎線分隔字串陣列時，語句右側的值必須用雙引號括起來。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

這兩個函數之間沒有區別，可以替換使用。 定義字串陣列的兩種方法都會產生相同的結果，即一個包含陣列元素的變數。

動態陣列

動態陣列有以下幾種形式：

• 動態資料物件包含一個陣列。 每個陣列元素也是一個物件成員。

  DYNAMIC beowulfLocations 
  ASSIGN beowulfLocations[1] = "Land of the Geats"
  ASSIGN beowulfLocations[2] = "Heorot" 
  ASSIGN beowulfLocations[3] = "Earnanæs"

• 動態物件包含一個儲存陣列的成員。 物件的其他成員可能儲存字串或數值，也可能是其他陣列。

  DYNAMIC beowulfCharacteristics 
  ASSIGN beowulfCharacteristics.foe[1].characteristics[1] = "Grendel"
  ASSIGN beowulfCharacteristics.foe[1].characteristics[2] = "son of Cain"
  ASSIGN beowulfCharacteristics.foe[2] = $"Grendel\'s mother" 
  ASSIGN beowulfCharacteristics.foe[3] = "Dragon"

• 字串陣列中的每個元素都包含一個動態資料物件。

  DYNAMIC epicPoems
  ASSIGN epicPoems.poemName = "Beowulf"
  DYNAMIC heroes 
  ASSIGN heroes.heroName = "Beowulf"
  DYNAMIC monsters
  ASSIGN monsters.monsterName = "Grendel"
  ASSIGN oldEnglish[1] = epicPoems
  ASSIGN oldEnglish[2] = heroes
  ASSIGN oldEnglish[3] = monsters

  運行偵錯程式時，您可以在 Snippet 編輯器視窗內的「變數為樹」標籤上查看動態物件和字串陣列的內容。

  當您需要您的指令碼用於其他系統時，例如連接到 API 時，不能使用這種類型的動態陣列。 字串陣列儲存的資料無法序列化或轉換為 JSON 或 XML 字串。

依據位置引用陣列元素

您可以使用陣列中元素的位置（由其索引指定）來引用字串或動態陣列中的元素。 範例：

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN currentName = heroes[2]

currentName 的值是 Sir Gawain。

在 ASSIGN 語句中，您可以使用變數來代替等號兩側的索引號。 這樣就可以引用特定索引，而無需在指令碼中硬編碼索引。 範例：

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN location = 2
ASSIGN currentHero = heroes[location]
ASSIGN nextIndex = heroes.count() + 1
ASSIGN heroes[nextIndex] = "Roland"

本例中 currentHero 的值為 Sir Gawain。 上例的最後兩行顯示了使用變數作為 ASSIGN 語句左側的索引。 其還顯示了使用 count() 函數返回陣列中元素的個數。 該資訊用於在下一個空索引中新增新元素。

使用變數表示索引號時，不需要在變數名前後使用大括號。 指令碼需要在陣列名稱的方括號之間輸入數值。 其假定任何非數字都是變數，因此會尋找具有該名稱的變數。 必須有相應的變數聲明，在聲明中賦值。 如果沒有，則會出現以下錯誤：

_ERR=In Snippet line 12: Array index must be >= 1.

如果連接了 Snippet 動作的 Error 分支，指令碼會在出現此錯誤時使用此分支。

對字串陣列使用 FOREACH

您可以對字串陣列使用 FOREACH 語句 遍歷每個元素。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
 FOREACH elem IN heroes 
{
   ASSIGN aName = elem 
}

在本例中，elem 和 aName 在每次反覆運算時都會更新。 elem 變數儲存了 FOREACH 迴圈正在處理的目前元素。 指令碼用 elem 的內容更新 aName。 在每次反覆運算結束時，elem 和 aName 保留相同的值，但在反覆運算中間，elem 保留新值，aName 保留舊值（或者在第一次反覆運算開始時沒有值）。

您可以在陣列範例指令碼中的 FOREACH Loop with a String Array snippet 中清楚地看到這一點。 要查看變數的更新方式，請逐行查看 snippet。

對字串陣列使用 FOR

您可以對字串陣列使用 FOR 迴圈，遍歷陣列並按設定次數執行定義的動作。

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
FOR i = 1 TO heroes.count 
   {    
      item = "{heroes[i]}" 
   } 
        

本例的結果是，Item 在 FOR 迴圈的每次反覆運算中都會更新 heroes 陣列中由 i 值指定的索引位置的內容。 如 heroes.count 所示，FOR 迴圈在到達字串陣列的末尾後停止遍歷。

您可以在陣列範例指令碼中的 FOR Loop with a String Array snippet 中看到此迴圈。

在陣列中使用函數

您可以在陣列中使用 函數。 使用陣列名稱和方括號中的索引，然後使用點符號新增函數名稱。 如下範例所示：

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN miniHero = "{heroes[2].lower}"
ASSIGN yellyHero = "{heroes[2].upper}"

此範例的結果為 miniHero = sir gawain 和 yellyHero = SIR GAWAIN。

並非所有函數都適用於所有陣列。 某些函數僅適用於某些類型的值。 使用函數時，請驗證要使用函數的值類型。

可以在動態陣列中使用函數。 不過，根據具體的動態陣列及其包含的內容，您可能需要 使用特殊的物件屬性。$value。 某些函數不適用於整個物件。 例如，無法在物件陣列上使用 lower() 函數。 如果您嘗試這樣做，指令碼將忽略該函數。 在這些情況下，您必須採用變通方法。 例如，可以將陣列中物件的特定值複製到一個單獨的變數中。 然後，您可以對變數的內容使用 lower()，如果需要，還可以將轉換後的值複製回物件中。

下表中的函數專門用於陣列。 您可以在 陣列範例指令碼 的 Functions and Arrays snippet 中測試這些函數。

函數	描述
count()	返回陣列或物件中的元素個數。
index(indexValue)	根據指定的 indexValue 從變數內容中返回陣列元素。
indexof(text)	返回變數內容中指定 text 字元的位置。
size()	返回陣列中的元素數目。
split(delimiter)	將變數的內容轉換為適合作為陣列處理的豎線分隔字串。 用豎線字元替換現有的指定delimiter。