Service ScriptForge.Dictionary

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

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

Ic√īne Astuce

Le service Dictionnaire est similaire √† l'objet Collection LibreOffice Basic int√©gr√©, mais avec plus de fonctionnalit√©s. Par exemple, les objets Collection ne prennent pas en charge la r√©cup√©ration des cl√©s. De plus, les dictionnaires offrent des fonctionnalit√©s suppl√©mentaires telles que le remplacement des cl√©s, le test si une cl√© sp√©cifique existe d√©j√† et la conversion du dictionnaire en un objet Array ou une cha√ģne JSON.


Invocation du service

En Basic :

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


    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myDict As Variant
    myDict = CreateScriptService("Dictionary")
  

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


     Set myDict = myDict.Dispose()
  
En Python

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 dict 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()
  
note

√Čtant donn√© que Python prend en charge les dictionnaires int√©gr√©s, la plupart des m√©thodes du service Dictionary sont disponibles uniquement pour les scripts Basic. Les exceptions sont ConvertToPropertyValues et ImportFromPropertyValues qui sont pris en charge √† la fois en Basic et en Python.


Propriétés

Nom

En lecture seule

Type

Description

Count

Oui

Long

Le nombre d'entrées dans le dictionnaire

Items

Oui

Matrice de variants

La liste des éléments comme matrice à une dimension

Keys

Oui

Matrice de cha√ģnes

La liste des clés comme matrice à une dimension


Ic√īne Astuce

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.


Exemple :

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
    

Liste des méthodes dans le service Dictionary

Add
ConvertToArray
ConvertToJson
ConvertToPropertyValues

Exists
ImportFromJson
ImportFromPropertyValues
Item

Remove
RemoveAll
ReplaceItem
ReplaceKey


Add

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

Syntaxe :

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

Paramètres :

key¬†: valeur de cha√ģne utilis√©e pour identifier l'√©l√©ment. La cl√© n'est pas sensible √† la casse.

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

Exemple :


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

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.

Syntaxe :

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

Exemple :


      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.

Syntaxe :

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

Paramètres :

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.

Exemple :


      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.

Syntaxe :

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

Exemple :

En Basic :

    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()
  
En Python

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()
  
tip

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.

Syntaxe :

dict.Exists(key: str): bool

Paramètres :

key : la clé à rechercher dans le dictionnaire.

Exemple :


    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.

Syntaxe :

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

Paramètres :

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.

Exemple :


    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.

Syntaxe :

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

Paramètres :

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.

Exemple :

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

En Basic :

    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
  
En Python

    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.

Syntaxe :

dict.Item(key: str): any

Paramètres :

clé : non sensible à la casse. Si elle n'existe pas, la valeur Empty est renvoyée.

Exemple :

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.

Syntaxe :

dict.Remove(key: str): bool

Paramètres :

clé : non sensible à la casse. Doit exister dans le dictionnaire, sinon une erreur UNKNOWNKEYERROR est générée.

Exemple :


    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.

Syntaxe :

dict.RemoveAll(): bool

Exemple :


    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.

Syntaxe :

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

Paramètres :

cl√©¬†: valeur de cha√ģne repr√©sentant la cl√© dont la valeur sera remplac√©e. Non sensible √† la casse. Si la cl√© n'existe pas dans le dictionnaire, une erreur UNKNOWNKEYERROR est renvoy√©e.

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

Exemple :


    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.

Syntaxe :

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

Paramètres :

key¬†: valeur de cha√ģne repr√©sentant la cl√© √† remplacer. Non sensible √† la casse. Si la cl√© n'existe pas dans le dictionnaire, une erreur UNKNOWNKEYERROR est renvoy√©e.

value¬†: valeur de cha√ģne pour la nouvelle cl√©. Non sensible √† la casse. Si la nouvelle cl√© existe d√©j√† dans le dictionnaire, une erreur DUPLICATEKEYERROR est renvoy√©e.

Exemple :


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

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.


Aidez-nous !