In this topic:
A dictionary is a variable that could contains several values associated with unique keys.
In AskiaScript, all dictionary keys are case sensitive String and all values are Variant.
The creation of a dictionary is done by the assignment of a literal notation of a dictionary to a variable or by declaring a variable as a dictionary.
{} which represent the AskiaScript NumberArray, we've decide to prefix the first open curly-brace by a @ character.{} and square-bracket [] doesn't require to be prefix by the @ characters and will always refer resepectively to the Dictionary and Array.Declaring a Dictionary
Dim myValue As Dictionary
Assign a Dictionary to a variable
Dim myValue = @{
"key1" : "value1",
"key2" : 2,
"key3" : [ "a", "b", "c" ],
"key4" : True,
"key5" : #31/12/2016#,
"key5" : Null,
"key6" : {
"subKey1" : 12,
"subKey2" : False
}
}
#31/12/2016#) is still allowed, and the case-insensitive nature of the AskiaScript is preserved, meaning that True / False / Null (with first letter in capital) is allowed.The accessor of data returns the data associated with the specified Key.
This accessor property is used without the dot period (.)
Return the Variant value associated with the specified Key.
- key {String} Key of the data to access.
Be careful, a key is case-sensitive string.
key, Key and KEY are 3 different keys.
Using a non-existing key, the accessor returns the Null value.
To make a difference between an explicit Null value and the absence of the key, please use the ContainsKey() method.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user["Name"].TypeOf() ' => "variant"
user["Name"].InnerTypeOf() ' => "string"
user["Name"] ' => "John Doe"
user["Gender"].TypeOf() ' => "variant"
user["Gender"].InnerTypeOf() ' => "number"
user["Gender"] ' => 1
user["Birthday"].TypeOf() ' => "variant"
user["Birthday"].InnerTypeOf() ' => "date"
user["Birthday"] ' => #31/12/1975#
user["Married"].TypeOf() ' => "variant"
user["Married"].InnerTypeOf() ' => "boolean"
user["Married"] ' => True
user["Used browsers"].TypeOf() ' => "variant"
user["Used browsers"].InnerTypeOf() ' => "array"
user["Used browsers"] ' => ["Google Chrome", "Firefox"]
user["Contact info"].TypeOf() ' => "variant"
user["Contact info"].InnerTypeOf() ' => "dictionary"
user["Contact info"]["address"] ' => "Street Unknown, 1st. 99999 Fake city"
user["Details"].TypeOf() ' => "variant"
user["Details"].InnerTypeOf() ' => "null"
user["Details"] ' => Null
user["unavailable key"].TypeOf() ' => "variant"
user["unavailable key"].InnerTypeOf() ' => "null"
user["unavailable key"] ' => Null
' Case sensitive: "name" <> "Name"
user["name"].TypeOf() ' => "variant"
user["name"].InnerTypeOf() ' => "null"
user["name"] ' => Null
When a value associated to a key is a Dictionary or an Array, the accessor returns the object itself (reference) and not a copy it (value).
It means that modifying the object itself, will modify the value associated with the key.
Be careful, the modification is different than a re-assigment.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
Dim browsers = user["Used browsers"]
' Modification
browsers.Push("MS Edge") '=> @["Google Chrome", "Firefox", "MS Edge"]
' user["Used browsers"] '=> @["Google Chrome", "Firefox", "MS Edge"]
Dim browsers2 = user["Used browsers"]
' Modification
browsers2.Push("Safari") '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
' browsers '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
' browsers2 '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
' user["Used browsers"] '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
' Re-assigment
browsers2 = @["Internet Explorer"]
' browsers '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
' browsers2 '=> @["Internet Explorer"]
' user["Used browsers"] '=> @["Google Chrome", "Firefox", "MS Edge", "Safari"]
Dim contactInfo = user["Contact info"]
contactInfo.Set("mobile", "+00 01 01 99 01 99 99")
' user["Contact info"] ' => @{
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00",
' "mobile : "+00 01 01 99 01 99 99"
' }
Dim name = user["Name"] ' The string "John Doe" is copy
name = "Anonymous" ' => Re-assignment
user["Name"] ' => "John Doe"
' user '=> @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Used browsers" : ["Google Chrome", "Firefox", "MS Edge", "Safari"],
' "Contact info" : {
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00"
' "mobile : "+00 01 01 99 01 99 99"
' },
' "Details" : Null
' }
Returns the number of key/value pairs within the dictionary.
Return a Number.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.Count ' => 7
Returns the list of sorted keys within the dictionary.
Return an Array of Strings.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.Keys ' => {"Birthday"; "Contact info"; "Details"; "Gender"; "Married"; "Name"; "Used browsers"}
user.keys.Count ' => 7
user.Keys.TypeOf() ' => "stringarray"
user.Keys[1].TypeOf() ' => "string"
user.Keys[1] ' => "Name"
Returns the list of values within the dictionary.
Return an Array.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.Values ' => @["John Doe", 1, #31/12/1975#, True, ["Google Chrome", "Firefox"], {
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00" }, Null]
user.Values.Count ' => 7
user.Values.TypeOf() ' => "array"
user.Values[1].TypeOf() ' => "variant"
user.Values[1].InnerTypeOf() ' => "string"
user.Values[1] ' => "John Doe"
Indicates if the key exist in the dictionary.
Return a Boolean
- key {String} Key to test.
Be careful, a key is case-sensitive string.
key, Key and KEY are 3 different keys.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.ContainsKey("Name") ' => True
user.ContainsKey("Non-existing-key") ' => False
' Case sensitive "name" <> "Name"
user.ContainsKey("name") ' => False
This method modify the object in place
Remove the key/value pair associated with the specified key.
Return the Dictionary
- key {String} Key to remove.
Be careful, a key is case-sensitive string.
key, Key and KEY are 3 different keys.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.RemoveKey("Contact info") ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Used browsers" : ["Google Chrome", "Firefox"],
' "Details" : Null
' }
user.RemoveKey("Used browsers") ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Details" : Null
' }
' Case sensitive "name" <> "Name" (Do nothing)
user.RemoveKey("name") ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Details" : Null
' }
This method modify the object in place
Add or update the dictionary with the specified key and value.
Return the Dictionary
- key {String} Key to add or update.
- value {Variant|Null|Number|String|Boolean|Date|Array|Dictionary} Value to set.
Be careful, a key is case-sensitive string.
key, Key and KEY are 3 different keys.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
' Add a new key
user.Set("HasChildren", True) ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Used browsers" : ["Google Chrome", "Firefox"],
' "Contact info" : {
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00"
' },
' "Details" : Null,
' "HasChildren" : True
' }
' Update an existing key
user.Set("Used browsers", @["Google Chrome", "Firefox", "MS Edge"]) ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Used browsers" : ["Google Chrome", "Firefox", "MS Edge"],
' "Contact info" : {
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00"
' },
' "HasChildren" : True,
' "Details" : Null
' }
' Case sensitive "name" <> "Name"
user.Set("name", "Mistakes") ' => @{
' "Name" : "John Doe",
' "Gender" : 1,
' "Birthday" : #31/12/1975#,
' "Married" : True,
' "Used browsers" : ["Google Chrome", "Firefox", "MS Edge"],
' "Contact info" : {
' "address" : "Street Unknown, 1st. 99999 Fake city",
' "email" : "johndoe@anonymous.com",
' "phone" : "+00 01 99 01 99 00 00"
' },
' "HasChildren" : True,
' "Details" : Null,
' "name" : "Mistakes"
' }
Use the XML string in argument to set or reset all the dictionary keys.
To be user-friendly as much as possible, the conversion of XML to a dictionary uses the following simple rules:
"tagname": The tag name is used as it isDictionary or Array."@attr": The tag attribute is prefix by the @ characterString which represent the value of the attribute."#text": The special key #text represent the text value inside the tag.Returns a successful value if the operation succeeds, otherwise it returns a failed value.
Returns a MethodResult.
- xmlString {String} String in XML format.
Dim xml As Dictionary
Dim result = xml.LoadXml("invalid xml format")
' result.Success ' => False
' result.ErrorMessage ' => "SyntaxError: Unexpected token i in XML at position : 0"
' xml.Count ' => 0
Dim xml As Dictionary
Dim result = items.LoadXml("<root><items><item id="1">ABC</item></items></root>")
' result.Success ' => True
' xml.Count ' => 1
' xml ' => @{
' "root" : {
' "items" : {
' "item" : {
' "@id" : "1",
' "#text" : "ABC"
' }
' }
' }
' }
'
' xml["root"]["items"]["item"]["@id"] ' => "1"
' xml["root"]["items"]["item"]["#text"] ' => "ABC"
Dim xml As Dictionary
Dim result = items.LoadXml("<root><items><item id="1">ABC</item><item id="2">DEF</item></items></root>")
' result.Success ' => True
' xml.Count ' => 1
' xml ' => @{
' "root" : {
' "items" : {
' "item" : [
' {
' "@id" : "1",
' "#text" : "ABC"
' },
' {
' "@id" : "2",
' "#text" : "DEF"
' },
' ]
' }
' }
' }
'
' xml["root"]["items"]["item"][1]["@id"] ' => "1"
' xml["root"]["items"]["item"][1]["#text"] ' => "ABC"
'
' xml["root"]["items"]["item"][2]["@id"] ' => "2"
' xml["root"]["items"]["item"][2]["#text"] ' => "DEF"
In the both previous examples, the "item" key doesn't returns the same object type.
The first example return a Dictionary while the second return an Array.
But using the "magical" automatic casting / conversion of the Variant and the rule of conversion from Dictionary to Array, you can always treat a Dictionary as it is an Array.
Dim dict As Variant = @{ "key" : "value" }
' The conversion rule from Dictionary to Array produce:
' dict.ToArray() ' => @[{ "key" : "value"}]
'
' The automatic casting / conversion rules, using a method / property
' of Array, first convert the dictionary to array and then apply the method / property, so:
' dict[1] ' => @{"key" : "value"}
Applying it to the second examples:
Dim xml As Dictionary
Dim result = items.LoadXml("<root><items><item id="1">ABC</item></items></root>")
' result.Success ' => True
' xml.Count ' => 1
' xml ' => @{
' "root" : {
' "items" : {
' "item" : {
' "@id" : "1",
' "#text" : "ABC"
' }
' }
' }
' }
'
' xml["root"]["items"]["item"]["@id"] ' => "1"
' xml["root"]["items"]["item"]["#text"] ' => "ABC"
' Equivalent to:
' xml["root"]["items"]["item"][1]["@id"] ' => "1"
' xml["root"]["items"]["item"][1]["#text"] ' => "ABC"
Use the JSON string in argument to initialize the value of the dictionary.
Returns a successful value if the operation succeeds, otherwise it returns a failed value.
If the type of the JSON object doesn't match the Dictionary, the method will return a failed value.
Returns a MethodResult.
Dim items As Dictionary
Dim result = items.LoadJSON("invalid json format")
' result.Success ' => False
' result.ErrorMessage ' => "SyntaxError: Unexpected token i in JSON at position : 0"
' items ' => Null
' items.InnerTypeOf() ' => "null"
Dim items As Dictionary Dim result = items.LoadJSON(@["Array", "is not", "Dictionary"]) ' result.Success ' => False ' result.ErrorMessage ' => "Type mismatch: Expected Dictionary matching type" ' items ' => Null ' items.InnerTypeOf() ' => "null"
Dim items as Dictionary
Dim result = items.LoadJSON("{"key1":"value1", "key2":12}")
' result.Success ' => True
' result.ErrorMessage ' => ""
' items ' => @{"key1" : "value1", "key2", 12}
' items.InnerTypeOf() ' => "dictionary"
Returns a string which represent the dictionary (express in JSON format, all keys are sorted).
Return a String.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
' Output in a single line (it's break here for the readability)
user.ToString() ' => "{
'"Birthday":"1975-12-31T23:00:00.000Z",
'"Contact info":{
'"address":"Street Unknown, 1st. 99999 Fake city",
'"email":"johndoe@anonymous.com",
'"phone":"+00 01 99 01 99 00 00"
'},
'"Details":null,
'"Gender":1,
'"Married":true,
'"Name":"John Doe",
'"Used browsers":["Google Chrome","Firefox"],
'}"
Always returns "dictionary".
Return a String.
Dim user As Dictionary = @{
"Name" : "John Doe",
"Gender" : 1,
"Birthday" : #31/12/1975#,
"Married" : True,
"Used browsers" : ["Google Chrome", "Firefox"],
"Contact info" : {
"address" : "Street Unknown, 1st. 99999 Fake city",
"email" : "johndoe@anonymous.com",
"phone" : "+00 01 99 01 99 00 00"
},
"Details" : Null
}
user.TypeOf() ' => "dictionary"
=, <>, <, <=, >, >=
All operators use the result of the .ToString() method of the dictionary to compare
Dim obj1 As Dictionary = @{
"c" : "aa",
"b" : "bb",
"a" : "cc",
}
Dim obj2 As Dictionary = @{
"a" : "cc",
"b" : "bb",
"c" : "aa",
}
Dim obj3 As Dictionary = @{
"d" : "dd",
"e" : "ee",
"f" : "ff",
}
(obj1 = obj2) ' => True;
(obj1 = obj3) ' => False;
(obj1 > obj3) ' => False;