BinaryFormat.Group

Syntaxe

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

À propos

Les paramètres sont les suivants :

• Le paramètre binaryFormat spécifie le format binaire de la valeur de clé.
• Le paramètre group fournit des informations sur le groupe d’éléments connus.
• Le paramètre extra facultatif peut être utilisé pour spécifier une fonction qui retourne une valeur de format binaire pour la valeur suivant une clé inattendue. Si le paramètre extra n’est pas spécifié, une erreur est générée s’il existe des valeurs de clé inattendues.

Le paramètre group spécifie une liste de définitions d’éléments. Chaque définition d’élément est une liste contenant 3 à 5 valeurs, comme suit :

• Valeur de clé. Valeur de la clé qui correspond à l’élément. Cela doit être unique dans l’ensemble d’éléments.
• Format de l’élément. Format binaire correspondant à la valeur de l’élément. Cela permet à chaque élément d’avoir un format différent.
• Occurrence de l'élément. Valeur BinaryOccurrence.Type pour le nombre de fois où l’élément doit apparaître dans le groupe. Les éléments obligatoires qui ne sont pas présents provoquent une erreur. Les éléments en doublon obligatoires ou facultatifs sont traités comme des valeurs de clés inattendues.
• Valeur d’élément par défaut (facultatif). Si la valeur d’élément par défaut apparaît dans la liste de définitions d’élément et n’est pas null, elle sera utilisée au lieu de la valeur par défaut. La valeur par défaut pour les éléments répétitifs ou facultatifs est Null, et la valeur par défaut pour les valeurs répétées est une liste vide { }.
• Transformation de la valeur de l’élément (facultatif). Si la fonction de transformation de valeur d’élément est présente dans la liste de définitions d’élément et n’est pas null, elle est appelée pour transformer la valeur de l’élément avant son retour. La fonction de transformation est appelée uniquement si l’élément apparaît dans l’entrée (il ne sera jamais appelé avec la valeur par défaut).

Exemple 1

L’exemple suivant suppose une valeur de clé qui est un octet unique, avec 4 éléments attendus dans le groupe, dont tous ont un octet de données suivant la clé. Les éléments apparaissent dans l’entrée comme suit :

• La clé 1 est requise et apparaît avec la valeur 11.
• La clé 2 se répète et apparaît deux fois avec la valeur 22, et génère une valeur de { 22, 22 }.
• La clé 3 est facultative et n’apparaît pas et génère une valeur null.
• La clé 4 se répète, mais n’apparaît pas et génère une valeur de { }.
• La clé 5 ne fait pas partie du groupe, mais apparaît une fois avec la valeur 55. La fonction supplémentaire est appelée avec la valeur de clé 5 et retourne le format correspondant à cette valeur (BinaryFormat.Byte). La valeur 55 est lue et ignorée.

Utilisation

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)

Sortie

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

Exemple 2

L’exemple suivant illustre la transformation de valeur de l’élément et la valeur d’élément par défaut. L’élément répétitif avec la clé 1 additionne la liste des valeurs lues à l’aide de List.Sum. L’élément facultatif avec la clé 2 a une valeur par défaut de 123 au lieu de null.

Utilisation

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)

Sortie

{203, 123}