Service ScriptForge.Dictionary

Un dictionnaire est une collection de paires d'éléments clés

• La clé est une chaîne de caractères. Dans les scripts Basic, la sensibilité à la casse de la clé est déterminée lors de la création du dictionnaire. Dans les scripts Python, la clé est toujours sensible à la casse.

• Les articles peuvent être de tout type

Les clés et les objets peuvent être récupérés, comptés, mis à jour et bien plus encore.

Le service Dictionary est similaire à l'objet intégré LibreOffice Basic Collection, mais offre davantage de fonctionnalités. Par exemple, les objets Collection ne permettent pas de récupérer les clés. De plus, les dictionnaires proposent des fonctionnalités supplémentaires telles que le remplacement de clés, la vérification de l'existence d'une clé spécifique et la conversion du dictionnaire en une matrice de PropertyValues ou en une chaîne JSON.

Invocation du service

L'exemple suivant crée myDict en tant que dictionnaire vide.

    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary", True)
                ' Les clés sont sensibles à la casse, donc le deuxième argument est True
 

Il est recommandé de libérer des ressources après utilisation :

     Set myDict = myDict.Dispose()
  

L'exemple ci-dessous crée une instance vide du service Dictionary et utilise la méthode native Python update pour la remplir avec le contenu d'un objet Python dict .

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Initialiser myDict comme un objet Dictionary vide
    myDict = CreateScriptService('Dictionary')
    # Charger les valeurs de dico dans myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Il est possible de créer une instance du service Dictionary en utilisant un objet Python dict comme argument, comme illustré dans l'exemple suivant.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Initialiser myDict avec le contenu de dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Comme Python intègre la gestion des dictionnaires, la plupart des méthodes du service Dictionary ne sont disponibles que pour les scripts Basic. Les exceptions sont les méthodes ConvertToPropertyValues et ImportFromPropertyValues, qui sont prises en charge à la fois par Basic et Python.

Propriétés

Les propriétés Keys et Items retournent leur contenu respectif, en utilisant un ordre identique. L'ordre est indépendant de la séquence de création.

L'exemple suivant utilise la propriété Keys pour parcourir toutes les clés du dictionnaire myDict.

    Dim a As Variant, b As String
    a = myDict.Keys
    For Each b In a
        MsgBox(myDict.Item(b))
    Next b
    

Add

Ajoute une nouvelle paire clé-élément dans le dictionnaire. Renvoie True en cas de succès.

dict.Add(key: str, item: any): bool

key : valeur de type chaîne de caractères utilisée pour identifier l’élément. La sensibilité à la casse de la clé a été déterminée lors de la création du dictionnaire.

item : toute valeur, y compris une matrice, un objet Basic, un objet UNO, un dictionnaire, etc.

      Dim NewValue As Variant
      myDict.Add("NewKey", NewValue)
    

Chaque clé doit être unique dans le même dictionnaire. Si la clé existe déjà dans le dictionnaire, une DUPLICATEKEYERROR sera retournée. Les clés composées de caractères d'espace génèrent une erreur INVALIDKEYERROR.

ConvertToArray

Stocke le contenu du dictionnaire dans une matrice de base zéro à deux colonnes. Les clés sont stockées dans la première colonne et les éléments sont stockés dans la deuxième colonne.

Si le dictionnaire est vide, cette méthode renverra une Array vide.

dict.ConvertToArray(): any[0..*, 0..1]

      Dim myDict as Variant
      myDict = CreateScriptService("Dictionary")
      myDict.Add("a", 1)
      myDict.Add("b", 2)
      myDict.Add("c", 3)
      Dim arr as Variant
      arr = myDict.ConvertToArray()
      '(("a", 1), ("b", 2), ("c", 3))
    

ConvertToJson

Convertit le contenu d'un dictionnaire en texte JSON (JavaScript Object Notation).

Limitations

Cette méthode prend en charge les types de données suivants : String, Boolean, nombres, Null et Empty. Les matrices contenant des éléments de ces types sont également autorisées, quelles que soient leurs dimensions. Les dates sont converties en chaînes, mais elles ne peuvent pas être utilisées dans les matrices. Les autres types de données sont convertis en leur représentation sous forme de chaîne à l'aide du service SF_String.Represent.

dict.ConvertToJson(indent: str = ""): str

indent : lorsque indent est un nombre positif ou un texte, les éléments de matrice JSON et les membres d'objet sont joliment imprimés avec ce niveau d'indentation. Une valeur indent négative ajoutera de nouvelles lignes sans indentation. La valeur par défaut est une chaîne vide "" qui sélectionne la représentation la plus compacte. L'utilisation d'un entier positif pour indent indente autant d'espaces par niveau. Lorsque indent est une chaîne, telle que Chr(9) ou Tab(1), le caractère Tab est utilisé pour indenter chaque niveau.

      myDict.Add("p0", 12.5)
      myDict.Add("p1", "a string àé""ê")
      myDict.Add("p2", DateSerial(2020,9,28))
      myDict.Add("p3", True)
      myDict.Add("p4", Array(1,2,3))
      MsgBox myDict.ConvertToJson()    
      '{"p0": 12.5, "p1": "a string \u00e0\u00e9\"\u00ea", "p2": "2020-09-28", "p3": true, "p4": [1, 2, 3]}
    

ConvertToPropertyValues

Stocke le contenu du dictionnaire dans une matrice de PropertyValues.

Chaque entrée de la matrice est une com.sun.star.beans.PropertyValue. La clé est stockée dans Name, l'élément est stocké dans Value.

Si l'un des éléments a un type Date, il est converti en une structure com.sun.star.util.DateTime. Si l'un des éléments est une matrice vide, il est converti en Null. La matrice résultante est vide lorsque le dictionnaire est vide.

dict.ConvertToPropertyValues(): obj[0..*]

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Ajoute des propriétés au dictionnaire
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    'Convertit en une matrice d'objets PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

Notez dans l'exemple ci-dessous qu'un dictionnaire Python doit être passé comme deuxième argument de la méthode CreateScriptService.

    myDict = dict()
    myDict["Color"] = "Blue"
    myDict["Width"] = 30
    sfDic = CreateScriptService("Dictionary", myDict)
    prop = sfDic.ConvertToPropertyValues()
  

De nombreux services et méthodes de la bibliothèque UNO acceptent des paramètres représentés à l'aide de la structure PropertyValue, qui fait partie de l'API LibreOffice.

Exists

Détermine si une clé existe dans le dictionnaire.

dict.Exists(key: str): bool

key : la clé à rechercher dans le dictionnaire.

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Ajoute des propriétés au dictionnaire
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    '(...)
    If Not myDict.Exists("Size") Then
       MsgBox "You have to provide a Size value"
    End If
  

ImportFromJson

Ajoute le contenu d'une chaîne JSON (JavaScript Object Notation) dans le dictionnaire actuel. Renvoie True en cas de succès.

Limitations

La chaîne JSON peut contenir des nombres, du texte, des booléens, des valeurs nulles et des matrices contenant ces types. Elle ne doit pas contenir d'objets JSON à savoir des sous-dictionnaires.

Une tentative de conversion du texte en date est effectuée si l'élément correspond à l'un de ces modèles : YYYY-MM-DD, HH:MM:SS ou YYYY-MM-DD HH:MM:SS.

dict.ImportFromJson(inputstr: str, overwrite: bool = False): bool

inputstr : la chaîne à importer.

overwrite : lorsque True, les entrées portant le même nom peuvent exister dans le dictionnaire et leurs valeurs sont écrasées. Lorsque False (par défaut), les clés répétées génèrent une erreur. Sachez que les clés de dictionnaire ne sont pas sensibles à la casse, tandis que les noms sont sensibles à la casse dans les chaînes JSON.

    Dim s As String
    s = "{'firstName': 'John','lastName': 'Smith','isAlive': true,'age': 66, 'birth':  '1954-09-28 20:15:00'" _
        & ",'address': {'streetAddress': '21 2nd Street','city': 'New York','state': 'NY','postalCode': '10021-3100'}" _
        & ",'phoneNumbers': [{'type': 'home','number': '212 555-1234'},{'type': 'office','number': '646 555-4567'}]" _
        & ",'children': ['Q','M','G','T'],'spouse': null}"
    s = Replace(s, "'", """")
    myDict.ImportFromJson(s, OverWrite := True)
    'Les (sous)-dictionnaires "address" et "phoneNumbers" (0) et (1) sont importés en tant que valeurs vides.
  

ImportFromPropertyValues

Insère le contenu d'une matrice d'objets PropertyValue dans le dictionnaire courant. PropertyValue Names sont utilisés comme clés dans le dictionnaire, tandis que les valeurs contiennent les valeurs correspondantes. Renvoie True en cas de succès.

dict.ImportFromPropertyValues(propertyvalues: obj[0..*], overwrite: bool = False): bool

propertyvalues : matrice unidimensionnel de base zéro contenant des objets com.sun.star.beans.PropertyValue. Ce paramètre peut également être un seul objet PropertyValue non contenu dans un Array.

overwrite : lorsque Vrai, les entrées portant le même nom peuvent exister dans le dictionnaire et leurs valeurs sont écrasées. Lorsque False (par défaut), les clés répétées génèrent une erreur. Notez que les clés de dictionnaire ne sont pas sensibles à la casse dans Basic, alors que les noms sont sensibles à la casse dans les ensembles de valeurs de propriété et dans les dictionnaires Python.

Les exemples ci-dessous créent d'abord une matrice avec deux objets PropertyValue puis le convertissent en dictionnaire.

    Dim vProp As New com.sun.star.beans.PropertyValue
    Dim arrProp : arrProp = Array()
    vProp.Name = "Color"
    vProp.Value = "Blue"
    arrProp = SF_Array.Append(arrProp, vProp)
    vProp.Name = "Date"
    vProp.Value = CDateToUnoDateTime(Now)
    arrProp = SF_Array.Append(arrProp, vProp)
    myDict = CreateScriptService("Dictionary")
    myDict.ImportFromPropertyValues(arrProp, Overwrite := True)
    Dim keys : keys = myDict.Keys
    For Each k In keys
        MsgBox k & " - " & myDict.Item(k)
    Next k
  

    from scriptforge import CreateScriptService
    from datetime import datetime
    import uno
    bas = CreateScriptService("Basic")
    arrProp = list()
    vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")
    vProp.Name = "Color"
    vProp.Value = "Blue"
    arrProp.append(vProp)
    vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")
    vProp.Name = "Date"
    vProp.Value = bas.CDateToUnoDateTime(datetime.now())
    arrProp.append(vProp)
    myDict = CreateScriptService("Dictionary")
    myDict.ImportFromPropertyValues(arrProp, overwrite=True)
    for k in myDict.keys():
        bas.MsgBox("{} - {}".format(k, myDict[k]))
  

Item

Récupère une entrée de dictionnaire existante en fonction de sa clé. Renvoie la valeur de l'élément en cas de succès, sinon renvoie Empty.

dict.Item(key: str): any

key : si elle n’existe pas, la valeur Empty est renvoyée.

L'exemple suivant itère sur toutes les clés du dictionnaire et utilise la méthode Item pour accéder à leurs valeurs.

    Dim myDict as Variant, k as Variant, allKeys as Variant
    myDict = CreateScriptService("Dictionary")
    myDict.Add("key1", 100)
    myDict.Add("key2", 200)
    myDict.Add("key3", 300)
    allKeys = myDict.Keys
    For Each k in allKeys
       MsgBox(myDict.Item(k))
    Next k
  

Remove

Supprime une entrée de dictionnaire existante en fonction de sa clé. Renvoie True en cas de succès.

dict.Remove(key: str): bool

key : doit exister dans le dictionnaire, sinon une erreur UNKNOWNKEYERROR est levée.

    myDict.Add("key1", 100)
    myDict.Add("key2", 200)
    myDict.Add("key3", 300)
    MsgBox(myDict.Count) ' 3
    myDict.Remove("key2")
    MsgBox(myDict.Count) ' 2
  

RemoveAll

Supprime toutes les entrées du dictionnaire. Renvoie True en cas de succès.

dict.RemoveAll(): bool

    myDict.Add("key1", 100)
    myDict.Add("key2", 200)
    myDict.Add("key3", 300)
    MsgBox(myDict.Count) ' 3
    myDict.RemoveAll()
    MsgBox(myDict.Count) ' 0
  

ReplaceItem

Remplace une valeur d'élément existante en fonction de sa clé. Renvoie True en cas de succès.

dict.ReplaceItem(key: str, value: any): bool

key : chaîne de caractères représentant la clé dont la valeur sera remplacée. Si la clé n'existe pas dans le dictionnaire, une erreur UNKNOWNKEYERROR est levée.

value : la nouvelle valeur de l'élément référencé avec le paramètre clé.

    myDict.Add("a", 1)
    MsgBox(myDict.Item("a")) ' 1
    myDict.ReplaceItem("a", 100)
    MsgBox(myDict.Item("a")) ' 100
  

ReplaceKey

Remplace une clé existante dans le dictionnaire par une nouvelle clé. La valeur de l'élément reste inchangée. Renvoie True en cas de succès.

dict.ReplaceKey(key: str, value: str): bool

key : valeur de type chaîne représentant la clé à remplacer. Si la clé n'existe pas dans le dictionnaire, une erreur UNKNOWNKEYERROR est levée.

value : valeur de type chaîne de caractères pour la nouvelle clé. Si la nouvelle clé existe déjà dans le dictionnaire, une erreur DUPLICATEKEYERROR est levée.

    myDict.Add("oldKey", 100)
    MsgBox(myDict.Item("oldKey")) ' 100
    myDict.ReplaceKey("oldKey", "newKey")
    MsgBox(myDict.Item("newKey")) ' 100
  

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.