Edukiak

# ScriptForge.Dictionary zerbitzua

Hiztegi bat gako-elementu bikoteen bilduma bat da

- Gakoa maiuskulukak/minuskulak kontuan hartzen ez dituen kate bat da

- Elementuak edozein motatakoak izan daitezke

Gakoak eta elementuak atzitu, zenbatu eta eguneratu daitezke, eta beste hainbat ekintza gauzatu daitezke haiekin.

Dictionary zerbitzua LibreOffice Basic lengoaiak integratuta duen Collection objektuaren antzekoa da, baina eginbide gehiago eskaintzen ditu. Adibidez, Collection objektuek ez dute onartzen gakoak atzitzea. Are gehiago, hiztegiek gaitasun gehiago dituzte gakoak ordezteko, gako zehatz bat lehendik badagoen egiaztatzen baitute eta Dictionary elementua Array objektu edo JSON kate bihurtzen baitute.

## Zerbitzuari deitzea

##### Basic lengoaian

Hurrengo adibideak myDict izeneko hiztegi hutsa sortzen du.

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

Gomendagarria da baliabideak askatzea haiek erabili ondoren:

         Set myDict = myDict.Dispose()

##### Python lengoaian

Beheko adibideak Dictionary zerbitzu baten instantzia huts bat sortzen du eta Pythonen jatorrizko update metodoa erabiltzen du hura Python dict objektu bateko edukiekin betetzeko.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Hasieratu myDict hutsik dagoen dict objektu gisa
        myDict = CreateScriptService('Dictionary')
        # dico aldagaiko balioak myDict hiztegian kargatzen ditu
        myDict.update(dico)
        myDict['D'] = 4
        print(myDict)   # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Posible da Dictionary zerbitzuaren instantzia bat Pythonen dict objektua argumentu gisa erabilita sortzea, hurrengo adibidean ikus daitekeen moduan.

        dico = dict('A' = 1, 'B' = 2, 'C' = 3)
        # Hasieratu myDict hiztegia dico aldagaiaren edukia erabilita
        myDict = CreateScriptService('Dictionary', dico)
        myDict['D'] = 4
        print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}
        propval = myDict.ConvertToPropertyValues()

Python lengoaiak hiztegien euskarri integratua duenez, Dictionary zerbitzuko metodoetako asko Basic scriptetan soilik erabili daitezke. Salbuespen dira ConvertToPropertyValues eta ImportFromPropertyValues, bi lengoaietan onartzen baitira.

## Propietateak

Izena | Irakurtzeko soilik | Mota | Deskribapena
--- | --- | --- | ---
Count | Bai | Long | Hiztegiaren sarrera kopurua
Items | Bai | Aldagaien matrizea | Elementu kopurua dimentsio bakarreko matrize gisa
Keys | Bai | Kate-matrizea | Gakoen zerrenda dimentsio bakarreko matrize gisa

Keys eta Items propietateek bakoitzak bere edukiak itzultzen dituzte, ordena berdina erabilita. Ordenak ez du zerikusirik sorrera-sekuentziarekin.

### Adibidea:

Hurrengo adibideak Keys propietatea darabil myDict hiztegiko gako guztietan iteratzeko.

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

List of Methods in the Dictionary Service
Add ConvertToArray ConvertToJson ConvertToPropertyValues | Exists ImportFromJson ImportFromPropertyValues Item | Remove RemoveAll ReplaceItem ReplaceKey

## Add

Gako-elementu bikote berria gehitzen dio hiztegiari. True itzultzen du eragiketa ongi gauzatzen bada.

### Sintaxia:

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

### Parametroak:

key : Elementua identifikatzeko erabiliko den kate-balioa. Ez ditu maiuskulak eta minuskulak bereizten.

item : Edozein balio: matrize bat, Basic objektu bat, UNO objektu bat, hiztegi bat...

### Adibidea:

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

Gako bakoitzak bakarra izan behar du hiztegi berean. Gakoa lehendik badago hiztegian, DUPLICATEKEYERROR errore bat sortuko da. Zuriuneekin egindako gakoek INVALIDKEYERROR errorea sortuko dute.

## ConvertToArray

Hiztegiaren edukiak zeron oinarritutako bi zutabeko matrize baten biltegiratzen ditu. Gakoak lehen zutabean biltegiratuko dira eta elementuak bigarren zutabean.

Hiztegia hutsik badago, metodo honek hutsik dagoen Array bat itzuliko du.

### Sintaxia:

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

### Adibidea:

          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

Hiztegi bateko edukiak JSON (JavaScript Object Notation) testu bihurtzen ditu.

### Mugak

Metodo honek honako datu motak onartzen ditu: String, Boolean, zenbakiak, Null eta Empty. Mota horretako elementuak dituzten matrizeak ere onartzen dira, berdin dio haien dimentsioak zein diren. Datak kate bihurtzen dira, baina ezin dira matrizeen barruan erabili. Beste datu motak kate modura duten ordezkapenera bihurtzen dira, SF_String.Represent zerbitzuaren bidez.

### Sintaxia:

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

### Parametroak:

indent: indent zenbaki positiboa edo testua denean, JSON matrize-elementuak eta objektu-kideak ondo inprimatzen dira koskatze-maila horrekin. indent balioa negatiboa bada, koskarik gabeko lerro berriak erantsiko dira. Balio lehenetsia kate huts bat da, "" alegia, adierazpen trinkoena hautatzen duena. Osoko zenbaki positiboa erabiltzen bada indent parametroan, zenbaki horrek adierazten duen espazio kopurua koskatuko da testua maila bakoitzeko. indent kate bat bada, adibidez Chr(9) edo Tab(1), tabulazioaren karakterea erabiliko da maila bakoitza koskatzeko.

### Adibidea:

          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

Gorde hiztegiaren edukiak PropertyValues elementuen matrize batean.

Matrizeko sarrera bakoitza com.sun.star.beans.PropertyValue bat da. Gakoa Name aldean biltegiratzen da, eta elementua Value aldean.

Elementuren bat Date motakoa bada, com.sun.star.util.DateTime egitura bihurtuko da. Elementuren bat matrize huts bat bada, Null bihurtuko da. Emaitza gisa sortutako matrizea hutsik egongo da hiztegia hutsik badago.

### Sintaxia:

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

### Adibidea:

##### Basic lengoaian

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Zenbait propietate gehitzen dizkio hiztegiari
        myDict.Add("Color", "Blue")
        myDict.Add("Width", 20)
        'PropertyValue objektuen matrize bihurtzen du
        Dim prop as Variant
        prop = myDict.ConvertToPropertyValues()

##### Python lengoaian

Ikusi nola, beheko adibidean, Python hiztegi bat pasatu behar den CreateScriptService metodoaren bigarren argumentu gisa.

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

UNO liburutegiaren zerbitzu eta metodo askok LibreOffice APIaren barruan dagoen PropertyValue struct-aren bidez adierazitako parametroak hartzen dituzte.

## Exists

Gako bat hiztegian badagoen ala ez zehazten du.

### Sintaxia:

dict.Exists(key: str): bool

### Parametroak:

key: Hiztegian dagoen ala ez begiratuko den gakoa.

### Adibidea:

        Dim myDict as Variant
        myDict = CreateScriptService("Dictionary")
        'Zenbait propietate gehitzen dizkio hiztegiari
        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) kate bateko edukia uneko hiztegiari gehitzen dio. True itzultzen du ongi gauzatzen bada.

### Mugak

JSON kateak eduki ditzake zenbakiak, testua, boolearrak, balio nuluak eta mota horiek dituzten matrizeak. Ez ditu eduki behar azpihiztegi deituriko JSON objektuak.

Testua data bihurtzeko saiakera egiten da elementuak honako ereduetako bat badu: UUUU-HH-EE, OO:MM:SS edo UUUU-HH-EE OO:MM:SS.

### Sintaxia:

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

### Parametroak:

inputstr: Inportatuko den katea.

overwrite: True (egia) denean, izen bereko sarrerak egon daitezke hiztegian eta beren balioak gainidatzi egingo dira. False (faltsua, balio lehenetsia) denean, gako errepikatuek errorea sortuko dute. Kontuan izan hiztegiko gakoak ez dituztela maiuskulak/minuskulak kontuan hartzen eta izenek bai JSON kateetan.

### Adibidea:

        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" eta "phoneNumbers" (0) eta (1) azpi-hiztegiak balio huts gisa inportatuko dira.

## ImportFromPropertyValues

PropertyValue objektuen matrize baten balioak uneko hiztegian txertatzen ditu. PropertyValue izenak gako modura erabiltzen dira hiztegian, eta balioak balio gisa. True itzultzen du eragiketa ongi gauzatu bada.

### Sintaxia:

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

### Parametroak:

propertyvalues: Zeron oinarritutako dimentsio bakarreko matrize bat, com.sun.star.beans.PropertyValue objektuak dituena. Parametro hau matrize batean ez dagoen PropertyValue objektu bat ere izan daiteke.

overwrite: Parametro hau True bada, izen bereko sarrerak egon daitezke hiztegian, eta haien balioak gainidatzi egingo dira. False (balio lehenetsia) bada, gako errepikatuek errore bat sortuko dute. Kontuan izan hiztegiko gakoetarako ez direla maiuskulak/minuskulak bereizten Basic lengoaian, baina propietate-balioen multzoetako izenetan eta Python lengoaian bai.

### Adibidea:

Beheko adibideak lehenengo matrize bat sortzen du bi PropertyValue objektu erabiliz, eta ondoren hiztegi bihurtzen du.

##### Basic lengoaian

        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

##### Python lengoaian

        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

Hiztegi batean dagoen sarrera bat atzitzen du, bere gakoa erabilita. Elementuaren balioa itzultzen du eragiketa ongi gauzatu bada, bestela Empty itzultzen du.

### Sintaxia:

dict.Item(key: str): any

### Parametroak:

key: Ez ditu maiuskulak/minuskulak bereizten. Ez badago, Empty balioa itzuliko da.

### Adibidea:

Hurrengo adibidean, hiztegiko gako guztien iterazio bat egiten da eta Item metodoa erabiltzen da beren balioak atzitzeko.

        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

Hiztegiko sarrera bat kentzen du bere gakoan oinarrituta. True itzultzen du eragiketa ongi gauzatzen bada.

### Sintaxia:

dict.Remove(key: str): bool

### Parametroak:

key: Ez ditu maiuskulak/minuskulak bereizten. Hiztegian egon behar du, bestela UNKNOWNKEYERROR errorea sortuko da.

### Adibidea:

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

## RemoveAll

Hiztegiko sarrera guztiak kentzen ditu. True (egia) itzultzen du ongi gauzatzen bada.

### Sintaxia:

dict.RemoveAll(): bool

### Adibidea:

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

## ReplaceItem

Elementu-balio bat ordezten du bere gakoan oinarrituta. True (egia) itzultzen du ongi gauzatzen bada.

### Sintaxia:

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

### Parametroak:

key: Ordeztuko den balioaren gakoa adierazten duen kate-balioa. Ez ditu maiuskulak/minuskulak bereizten. Gakoa hiztegian ez badago, UNKNOWNKEYERROR errorea sortuko da.

value: key parametroak erreferentzia egiten dion elementuaren balio berria.

### Adibidea:

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

## ReplaceKey

Hiztegiko gako bat beste gako batekin ordezten du. Elementuaren balioa ez da aldatuko. True itzultzen du eragiteka ongi gauzatzen bada.

### Sintaxia:

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

### Parametroak:

key: Ordeztuko den gakoa adierazten duen kate-balioa. Ez ditu maiuskulak/minuskulak bereizten. Gakoa hiztegian ez badago, UNKNOWNKEYERROR errorea sortuko da.

value: Gako berrirako kate-balioa. Ez ditu maiuskulak/minuskulak bereizten. Gako berria lehendik badago hiztegian, DUPLICATEKEYERROR errorea sortuko da.

### Adibidea:

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

Azpimarraren karaktere bat, "_", aurrizki gisa duten ScriptForge Basic errutina edo identifikatzaile guztiak barneko erabilerarako erreserbatuta daude. Ez dira Basic makroetan edo Python scriptetan erabili behar.

Erlazionatutako gaiak

ScriptForge.Array zerbitzua

Collection objektua