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 facultatif extra peut être utilisé pour spécifier une fonction qui retourne une valeur au 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ément. 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. Elle doit être unique au sein de l’ensemble d’éléments.
• Format de l’élément. Format binaire correspondant à la valeur de l’élément. Ceci permet à chaque élément d’avoir un format différent.
• Occurrence de l’élément. Valeur BinaryOccurrence.Type indiquant 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 par défaut de l’élément (facultatif) Si la valeur par défaut de l’élément apparaît dans la liste des définitions d’élément et n’est pas Null, elle est utilisée à la place de la valeur par défaut. La valeur par défaut pour les éléments répétés 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 la valeur de l’élément est présente dans la liste de définitions d’élément et qu’elle n’est pas Null, elle est appelée pour transformer la valeur de l’élément avant qu’il soit retourné. La fonction de transformation est appelée seulement si l’élément apparaît dans l’entrée (elle ne sera jamais appelée avec la valeur par défaut).

Exemple 1

Ceci suppose une valeur de clé d’un seul octet, avec 4 éléments attendus dans le groupe, tous ayant un octet de données après la clé. Les éléments apparaissent dans l’entrée comme suit :

• La clé 1 est obligatoire et elle apparaît avec la valeur 11.
• La clé 2 est répétée et apparaît deux fois avec la valeur 22 : elle a pour résultat une valeur { 22, 22 }.
• La clé 3 est facultative et n’apparaît pas, et elle a pour résultat une valeur Null.
• La clé 4 est répétée mais n’apparaît pas, et elle a pour résultat une valeur { }.
• La clé 5 ne fait pas partie du groupe, mais elle 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 des valeurs des éléments et la valeur par défaut des éléments. L’élément répétitif avec la clé 1 additionne la liste des valeurs lues avec 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}