BinaryFormat.Group

語法

BinaryFormat.Group(binaryFormat as function, group as list, optional extra as nullable function, optional lastKey as any) as function

關於

參數如下所示：

• binaryFormat 參數會指定金鑰值的二進位格式。
• group 參數會提供已知項目群組的相關資訊。
• 選擇性的 extra 參數可以用來指定函式，此函式會針對非預期的任何索引鍵，傳回值的二進位格式值。 如果未指定 extra 參數，則會在有未預期的金鑰值時引發錯誤。

group 參數會指定項目定義的清單。 每個項目定義都是一個清單，其包含 3-5 值，如下所示：

• 索引鍵值。 對應至項目的索引鍵值。 這在項目集合內必須是唯一的。
• 項目格式。 對應至項目值的二進位格式。 這可讓每個項目都具有不同的格式。
• 項目發生次數。 項目應出現在群組中多少次的 BinaryOccurrence.Type 值。 若必要項目不存在，則會造成錯誤。 必要或選擇性的重複項目，其處理方式會如同非預期的索引鍵值一樣。
• 預設項目值 (選擇性)。 如果預設項目值出現在項目定義清單中且非 null，則會使用該項目值，而非預設值。 重複或選擇性項目的預設值為 null，而重複值的預設值為空白清單 { }。
• 項目值轉換 (選擇性)。 如果項目值轉換函式出現在項目定義清單中且不是 null，則會將其呼叫來轉換項目值，然後傳回。 只有當項目出現在輸入中時，才會呼叫轉換函式 (一律不會使用預設值來呼叫)。

範例 1

下列假設為單一位元組的索引鍵值，其包含群組中的 4 個預期項目，其中資料都是索引鍵後面的一個位元組。 項目會顯示在輸入中，如下所示：

• 索引鍵 1 為必要，且顯示值為 11。
• 索引鍵 2 會重複，並以值 22 顯示兩次，並產生 { 22, 22 } 的值。
• 索引鍵 3 為選擇性，但不會顯示，且會產生 null 值。
• 索引鍵 4 會重複，但不會顯示，且會產生 { } 的值。
• 索引鍵 5 不是群組的一部分，但會以值 55 出現一次。 使用索引鍵值 5 呼叫額外函式，並傳回對應至該值的格式 (BinaryFormat.Byte)。 會讀取並捨棄值 55。

使用方式

let
    b = #binary({
        1, 11,
        2, 22,
        2, 22,
        5, 55,
        1, 11
    }),
    f = BinaryFormat.Group(
        BinaryFormat.Byte,
        {
            {1, BinaryFormat.Byte, BinaryOccurrence.Required},
            {2, BinaryFormat.Byte, BinaryOccurrence.Repeating},
            {3, BinaryFormat.Byte, BinaryOccurrence.Optional},
            {4, BinaryFormat.Byte, BinaryOccurrence.Repeating}
        },
        (extra) => BinaryFormat.Byte
    )
in
    f(b)

輸出

{11, {22, 22}, null, {}}

範例 2

下列範例說明項目值轉換和預設項目值。 索引鍵為 1 的重複項目，會加總 List.Sum 所讀取的值清單。 具有索引鍵 2 的選擇性項目，預設值為 123，而不是 null。

使用方式

let
    b = #binary({
        1, 101,
        1, 102
    }),
    f = BinaryFormat.Group(
        BinaryFormat.Byte,
        {
            {1, BinaryFormat.Byte, BinaryOccurrence.Repeating,
              0, (list) => List.Sum(list)},
            {2, BinaryFormat.Byte, BinaryOccurrence.Optional, 123}
        }
    )
in
    f(b)

輸出

{203, 123}