Υπηρεσία ScriptForge.Dictionary

Ένα λεξικό είναι μια συλλογή από ζεύγη κλειδιών-στοιχείων

• Το κλειδί είναι μια συμβολοσειρά χωρίς διάκριση πεζών-κεφαλαίων

• Τα στοιχεία μπορεί να είναι οποιουδήποτε τύπου

Τα κλειδιά και τα στοιχεία μπορούν να ανακτηθούν, να μετρηθούν, να ενημερωθούν και πολλά άλλα.

Η υπηρεσία Dictionary (Λεξικό) είναι παρόμοια με το ενσωματωμένο αντικείμενο του LibreOffice Basic Collection (Συλλογή), ωστόσο με περισσότερες δυνατότητες. Για παράδειγμα, τα αντικείμενα Collection δεν υποστηρίζουν την ανάκτηση κλειδιών. Επιπλέον, τα Λεξικά παρέχουν πρόσθετες δυνατότητες όπως αντικατάσταση κλειδιών, έλεγχος εάν υπάρχει ήδη ένα συγκεκριμένο κλειδί και μετατροπή του Λεξικού σε αντικείμενο πίνακα ή συμβολοσειρά JSON.

Κλήση υπηρεσίας

Το παρακάτω παράδειγμα δημιουργεί το myDict ως κενό λεξικό.

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

Συνιστάται η απελευθέρωση πόρων μετά τη χρήση:

     Set myDict = myDict.Dispose()
  

Το παρακάτω παράδειγμα δημιουργεί μια κενή παρουσία της υπηρεσίας Dictionary και χρησιμοποιεί την εγγενή μέθοδο update (ενημέρωση) της Python για να τη συμπληρώσει με τα περιεχόμενα ενός αντικειμένου Python dict .

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Αρχικοποιεί το myDict ως κενό αντικείμενο dict
    myDict = CreateScriptService('Dictionary')
    # Φόρτωση των τιμών του dico στο myDict
    myDict.update(dico)
    myDict['D'] = 4
    print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Είναι δυνατή η δημιουργία μιας παρουσίας της υπηρεσίας Dictionary χρησιμοποιώντας ένα αντικείμενο Python dict ως όρισμα όπως φαίνεται στο παρακάτω παράδειγμα.

    dico = dict('A' = 1, 'B' = 2, 'C' = 3)
    # Αρχικοποιεί το myDict με το περιεχόμενο του dico
    myDict = CreateScriptService('Dictionary', dico)
    myDict['D'] = 4
    print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
    propval = myDict.ConvertToPropertyValues()
  

Επειδή η Python διαθέτει ενσωματωμένη υποστήριξη λεξικού, οι περισσότερες μέθοδοι στην υπηρεσία Dictionary (Λεξικό) είναι διαθέσιμες μόνο για σενάρια Basic. Εξαιρέσεις είναι τα ConvertToPropertyValues και ImportFromPropertyValues που υποστηρίζονται τόσο σε Basic όσο και σε Python.

Ιδιότητες

Οι ιδιότητες Keys και Items επιστρέφουν τα αντίστοιχα περιεχόμενά τους, χρησιμοποιώντας την ίδια σειρά. Η σειρά δεν σχετίζεται με τη σειρά δημιουργίας.

Το παρακάτω παράδειγμα χρησιμοποιεί την ιδιότητα Keys για επανάληψη σε όλα τα κλειδιά του λεξικού myDict.

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

Add

Προσθέτει ένα νέο ζεύγος κλειδιών-στοιχείων στο λεξικό. Επιστρέφει True εάν είναι επιτυχής.

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

key (κλειδί): Τιμή συμβολοσειράς που χρησιμοποιείται για τον προσδιορισμό του στοιχείου. Το κλειδί δεν κάνει διάκριση πεζών-κεφαλαίων.

item (στοιχείο): Οποιαδήποτε τιμή, συμπεριλαμβανομένου ενός πίνακα, ενός βασικού αντικειμένου, ενός αντικειμένου UNO, ενός λεξικού κ.λπ.

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

Κάθε κλειδί πρέπει να είναι μοναδικό στο ίδιο λεξικό. Εάν το κλειδί υπάρχει ήδη στο λεξικό, θα εμφανιστεί ένα DUPLICATEKEYERROR. Τα κλειδιά που αποτελούνται από χαρακτήρες διαστήματος θα δημιουργήσουν σφάλμα INVALIDKEYERROR.

ConvertToArray

Αποθηκεύει τα περιεχόμενα του λεξικού σε έναν πίνακα δύο στηλών με βάση το μηδέν. Τα κλειδιά αποθηκεύονται στην πρώτη στήλη και τα στοιχεία αποθηκεύονται στη δεύτερη στήλη.

Εάν το λεξικό είναι κενό, αυτή η μέθοδος θα επιστρέψει έναν κενό Array (Πίνακα).

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

Μετατρέπει τα περιεχόμενα ενός λεξικού σε κείμενο JSON (JavaScript Object Notation).

Περιορισμοί

Αυτή η μέθοδος υποστηρίζει τους ακόλουθους τύπους δεδομένων: String (Συμβολοσειρά), Boolean (τιμές Μπουλ), αριθμούς, Null και Empty (Κενό). Επιτρέπονται επίσης πίνακες που περιέχουν στοιχεία αυτού του τύπου, ανεξάρτητα από τις διαστάσεις τους. Οι ημερομηνίες μετατρέπονται σε συμβολοσειρές, ωστόσο δεν μπορούν να χρησιμοποιηθούν μέσα στους Πίνακες. Άλλοι τύποι δεδομένων μετατρέπονται στην αναπαράσταση συμβολοσειράς τους χρησιμοποιώντας την υπηρεσία SF_String.Represent.

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

indent (εσοχή): Όταν η indent είναι θετικός αριθμός ή κείμενο, τα στοιχεία του πίνακα JSON και τα μέλη αντικειμένων εκτυπώνονται όμορφα με αυτό το επίπεδο εσοχής. Μια αρνητική τιμή indent θα προσθέσει νέες γραμμές χωρίς εσοχή. Η προεπιλεγμένη τιμή είναι μια κενή συμβολοσειρά "" που επιλέγει την πιο συμπαγή αναπαράσταση.Η χρήση ενός θετικού ακέραιου για indent δημιουργεί εσοχή τόσων κενών ανά επίπεδο. Όταν η indent είναι μια συμβολοσειρά, όπως Chr(9) ή Tab(1), ο χαρακτήρας Tab χρησιμοποιείται για την εσοχή κάθε επιπέδου.

      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

Αποθηκεύει τα περιεχόμενα του λεξικού σε έναν πίνακα PropertyValues.

Κάθε καταχώρηση στον πίνακα είναι μια com.sun.star.beans.PropertyValue. Το κλειδί αποθηκεύεται στο Name (Όνομα), το στοιχείο αποθηκεύεται στο Value (Τιμή).

Εάν ένα από τα στοιχεία έχει τύπο Date (Ημερομηνία), μετατρέπεται σε δομή com.sun.star.util.DateTime. Εάν ένα από τα στοιχεία είναι κενός πίνακας, μετατρέπεται σε Null. Ο πίνακας που προκύπτει είναι κενός όταν το λεξικό είναι κενό.

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

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Προσθέτει κάποιες ιδιότητες στο λεξικό
    myDict.Add("Color", "Blue")
    myDict.Add("Width", 20)
    'Μετατρέπεται σε έναν πίνακα αντικειμένων PropertyValue
    Dim prop as Variant
    prop = myDict.ConvertToPropertyValues()
  

Σημειώστε στο παρακάτω παράδειγμα ότι ένα λεξικό Python πρέπει να μεταβιβαστεί ως το δεύτερο όρισμα της μεθόδου CreateScriptService.

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

Πολλές υπηρεσίες και μέθοδοι στη βιβλιοθήκη UNO λαμβάνουν παραμέτρους που αντιπροσωπεύονται με τη χρήση της δομής PropertyValue, η οποία αποτελεί μέρος του LibreOffice API.

Exists

Καθορίζει εάν υπάρχει ένα κλειδί στο λεξικό.

dict.Exists(key: str): bool

key (κλειδί): Το κλειδί που πρέπει να αναζητηθεί στο λεξικό.

    Dim myDict as Variant
    myDict = CreateScriptService("Dictionary")
    'Προσθέτει κάποιες ιδιότητες στο λεξικό
    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

Προσθέτει το περιεχόμενο μιας συμβολοσειράς JSON (JavaScript Object Notation) στο τρέχον λεξικό. Επιστρέφει True εάν είναι επιτυχής.

Περιορισμοί

Η συμβολοσειρά JSON μπορεί να περιέχει αριθμούς, κείμενο, τιμές Μπουλ, μηδενικές τιμές και πίνακες που περιέχουν αυτούς τους τύπους. Δεν πρέπει να περιέχει αντικείμενα JSON και συγκεκριμένα υπολεξικά.

Γίνεται προσπάθεια μετατροπής κειμένου σε ημερομηνία, εάν το στοιχείο ταιριάζει με ένα από αυτά τα μοτίβα: ΕΕΕΕ-ΜΜ-ΗΗ, ΩΩ:ΛΛ:ΔΔ, ή ΕΕΕΕ-ΜΜ-ΗΗ ΩΩ:ΛΛ:ΔΔ.

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

inputstr: Η συμβολοσειρά προς εισαγωγή.

overwrite: Όταν είναι True, καταχωρήσεις με το ίδιο όνομα ενδέχεται να υπάρχουν στο λεξικό και οι τιμές τους αντικαθίστανται. Όταν είναι False (προεπιλογή), τα επαναλαμβανόμενα πλήκτρα θα προκαλέσουν σφάλμα. Λάβετε υπόψη ότι τα κλειδιά του λεξικού δεν κάνουν διάκριση πεζών-κεφαλαίων, ενώ τα ονόματα έχουν διάκριση πεζών-κεφαλαίων στις συμβολοσειρές 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)
    'Τα (υπο)-λεξικά "address" και "phoneNumbers" (0) και (1) εισάγονται ως κενές τιμές (Empty).
  

ImportFromPropertyValues

Εισάγει τα περιεχόμενα ενός πίνακα αντικειμένων PropertyValue στο τρέχον λεξικό. Τα ονόματα PropertyValue χρησιμοποιούνται ως κλειδιά στο λεξικό, ενώ οι Values (τιμές) περιέχουν τις αντίστοιχες τιμές. Επιστρέφει True εάν είναι επιτυχής.

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

propertyvalues (τιμές ιδιοτήτων): Ένας μηδενικός πίνακας 1 διάστασης που περιέχει αντικείμενα com.sun.star.beans.PropertyValue. Αυτή η παράμετρος μπορεί επίσης να είναι ένα μεμονωμένο αντικείμενο PropertyValue που δεν περιέχεται σε έναν πίνακα.

overwrite (αντικατάσταση): Όταν είναι True, καταχωρήσεις με το ίδιο όνομα ενδέχεται να υπάρχουν στο λεξικό και οι τιμές τους αντικαθίστανται. Όταν είναι False (προεπιλογή), τα επαναλαμβανόμενα κλειδιά θα προκαλέσουν σφάλμα. Σημειώστε ότι τα κλειδιά του λεξικού δεν κάνουν διάκριση πεζών-κεφαλαίων στο Basic, ενώ τα ονόματα έχουν διάκριση πεζών-κεφαλαίων σε σύνολα τιμών ιδιοτήτων και σε λεξικά Python.

Τα παρακάτω παραδείγματα δημιουργούν πρώτα έναν πίνακα με δύο αντικείμενα PropertyValue και μετά τον μετατρέπουν σε λεξικό.

    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

Ανακτά μια υπάρχουσα καταχώρηση λεξικού με βάση το κλειδί της. Επιστρέφει την τιμή του στοιχείου εάν είναι επιτυχές, διαφορετικά επιστρέφει Empty (Κενό).

dict.Item(key: str): any

key (κλειδί): Δεν γίνεται διάκριση πεζών-κεφαλαίων. Εάν δεν υπάρχει, επιστρέφεται η τιμή Empty.

Το παρακάτω παράδειγμα επαναλαμβάνεται σε όλα τα κλειδιά του λεξικού και χρησιμοποιεί τη μέθοδο Item (στοιχείο) για πρόσβαση στις τιμές τους.

    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

Καταργεί μια υπάρχουσα καταχώρηση λεξικού με βάση το κλειδί της. Επιστρέφει True εάν είναι επιτυχής.

dict.Remove(key: str): bool

key (κλειδί): Δεν γίνεται διάκριση πεζών-κεφαλαίων. Πρέπει να υπάρχει στο λεξικό, διαφορετικά δημιουργείται σφάλμα UNKNOWNKEYERROR.

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

RemoveAll

Αφαιρεί όλες τις καταχωρήσεις από το λεξικό. Επιστρέφει True εάν είναι επιτυχής.

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

Αντικαθιστά μια υπάρχουσα τιμή στοιχείου με βάση το κλειδί του. Επιστρέφει True εάν είναι επιτυχής.

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

key (κλειδί): Τιμή συμβολοσειράς που αντιπροσωπεύει το κλειδί του οποίου η τιμή θα αντικατασταθεί. Χωρίς διάκριση πεζών-κεφαλαίων. Εάν το κλειδί δεν υπάρχει στο λεξικό, εμφανίζεται ένα σφάλμα UNKNOWNKEYERROR.

value (τιμή): Η νέα τιμή του στοιχείου που αναφέρεται με την παράμετρο key.

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

ReplaceKey

Αντικαθιστά ένα υπάρχον κλειδί στο λεξικό με ένα νέο κλειδί. Η τιμή του στοιχείου παραμένει αμετάβλητη. Επιστρέφει True εάν είναι επιτυχής.

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

key (κλειδί): Τιμή συμβολοσειράς που αντιπροσωπεύει το κλειδί που πρόκειται να αντικατασταθεί. Χωρίς διάκριση πεζών-κεφαλαίων. Εάν το κλειδί δεν υπάρχει στο λεξικό, εμφανίζεται ένα σφάλμα UNKNOWNKEYERROR.

value (τιμή): Τιμή συμβολοσειράς για το νέο κλειδί. Χωρίς διάκριση πεζών-κεφαλαίων. Εάν το νέο κλειδί υπάρχει ήδη στο λεξικό, εμφανίζεται ένα σφάλμα DUPLICATEKEYERROR.

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

Όλες οι ρουτίνες ή αναγνωριστικά του ScriptForge στη Basic που έχουν το πρόθεμα χαρακτήρα υπογράμμισης "_" δεσμεύονται για εσωτερική χρήση. Δεν προορίζονται να χρησιμοποιηθούν σε μακροεντολές Basic ή σενάρια Python.