Maps (beta)

[JohnOne]

beta 3.3.13.17 is the first beta I've installed since 3.3.12.0 was released.

How do Maps work?

Seems from the help file that it's a scripting dictionary object with some methods coded into it already.

I'm probably wrong though.

[jchd]

Kinda. Map keys can be integers or case-sensitive strings and values can be any AutoIt datatype. Maps are not objects but internal datatype and retain insertion order.

[Ascend4nt]

Are there beta docs up on this site that can be linked to?  That could be a start.  Not everyone is going to touch the betas, but some interest can be generated by showing what the current documentation says without copying-and-pasting it here (and then keeping up with updates).

By the way, the current implementation looks like other language implementations of maps, hashtables, and associative arrays  (Javascript objects, PHP arrays, C++ sets/maps, C# Dictionary/Hash tables, D associative arrays) etc.

[Melba23]

Ascend4nt,

As I explained before, everything that is known about maps is in the Beta Help file. There are a few native functions under <Map management> and some explanation on the <Language Reference - Variables> page. We are not holding back on anything - there are no secret functions or functionality that will suddenly appear.

There is a very early Alpha Map UDF, but as we have no idea what people might want to do with the new datatype there seems little point in developing it past that stage for the moment. The content at present is:

; _MapConcatenate
; _MapDisplay
; _MapFindAll
; _MapMaxKey
; _MapMaxValue
; _MapMinKey
; _MapMinValue
; _MapRenameKey
; _MapSearch
; _MapToArray
; _MapToClip
; _MapToString

and if it looks a lot like the Array library it should!

Maps were announced some 5 weeks ago in the Beta 3.3.13.3 thread and subsequent Betas have made reference to any changes made to syntax and function names. But the usual complete indifference of most people to testing new additions seems to have occurred - they seem to like waiting until a full release before announcing that they have found problems. >

So there you have the current state of play - enjoy.

M23

[Ascend4nt]

As I explained before, everything that is known about maps is in the Beta Help file.

 

As I said:

Not everyone is going to touch the betas, but some interest can be generated by showing what the current documentation says

 

If you don't at least expose that information on the site (beta documentation), people may just well skip the betas not knowing what new features are brought to the table or how they can be used.  Again, to give features exposure you need to generate interest in them.  Noone's done a good job in that respect. JohnOne can at least be commended for posting this thread, which is a step forward.

However, thanks for the other information.

[Jon]

By the way, the current implementation looks like other language implementations of maps, hashtables, and associative arrays  (Javascript objects, PHP arrays, C++ sets/maps, C# Dictionary/Hash tables, D associative arrays) etc.

Pretty much. I liked the way you could have integer and strings keys and also liked the idea of it staying in order of insertion when iterated.

For background, the way I implemented it internally was by creating a generic AObject class that allows something to have properties and methods and then derived the Map class from this. Then the COM parser code is used to process it and can have a simple check in it of "is it a COM object or a generic AObject" then uses polymorphism to just "check for method", "call method" etc. Makes it easy to add object types in the future or add the lua-like table that trancexx was looking at.

This is where the .Add() and .Keys() methods came in along with the .properties. But we had some discussions amongst ourselves and a lot of languages look really ugly when they try and mix procedural syntax and object-like syntax. I rewrote some function code to allow built-in functions to pass by reference so that functions like MapAdd() can now exist properly. So that's the main decision to be made. Pure object methods and properties, or remove the methods and properties and just use the Map...() functions and array-like access like $map["key"]. That's why both are still there at the mo - just can't decide. Even though it's implemented as an object internally, we don't have to expose that with .Methods if we don't like it.

I implemented it as a value-type as well (like Array) but there were some discussions about having it behave like a reference type instead so that you could reference maps inside maps rather than just copies of maps. But I thought that it makes sense that arrays and maps should behave the same in that respect and it would be more useful to create a way in the language of creating a reference. I've not been able to get it to work though - the parser design just isn't up to it.

At the mo I'm planning to do a stable release soon because there's been some big bugs fixed that I want out there, but that will almost certainly have maps disabled and then roll them into the next beta.

[Ascend4nt]

Jon, thanks for taking the time out to describe what the status of Map is, as well as how it works internally.

I suppose the safe bet for people experimenting would be to use array-like access $mMap["property"] as that would be easier to use a RegEx on to fix it up.

From some simple tests, it appears that array-access function call syntax works, while property access doesn't.

Here's just a random experiment I've created:

expandcollapse popup

Func MyFunc()
    ConsoleWrite("Called MyFunc"&@LF)
EndFunc

Func ShowString(Const ByRef $mMap)
    If MapExists($mMap, "myString") Then ConsoleWrite("Map string = " & $mMap.myString & @LF)
EndFunc

Func TestMaps()
    Local $aArr[1], $mMap[], $mMap2[]

    ; Indirect function call using array
    $aArr[0] = MyFunc
    $aArr[0]()

    ; Indirect function call using Map & array-style access
    $mMap["func"] = MyFunc
    $mMap["func"]()

    ; Indirect function call using Map & member/property access
    $mMap2.func = MyFunc
    ;$mMap2.func()  ; Fails currently

    ; Value assign & access:
    $mMap["val"] = 1
    ConsoleWrite("Map1 value = " & $mMap.val & @LF)

    ; member/property version
    $mMap2.val = 4
    ConsoleWrite("Map2 value = " & $mMap2.val & @LF)

    ; More values
    $mMap["myString"] = "aMap string"
    $mMap2.myString = "aMap2 string"

    ; Passing maps as parameters
    ShowString($mMap)
    ShowString($mMap2)
EndFunc

TestMaps()

There's obviously great potential here for creating simple interfaces and pseudo-objects, but for now I'm going to start light..

*edit: see >this post for an extended example, plus Beta docs links

Edited August 25, 2014 by Ascend4nt

[Mat]

Calling a member function with dot access works, but you have to surround it in parenthesis: 

($mMap2.func)()

[jpm]

 

Calling a member function with dot access works, but you have to surround it in parenthesis: 

($mMap2.func)()

I don't think this syntax will be supported by Au3Check but who knows ...

[JohnOne]

I don't think this syntax will be supported by Au3Check but who knows ...

Hey jpm are there any ignore options in au3check for certain parts of code such as the one above, instead of disabling it?

[jpm]

If you know how the Au3Check is written, you could understand my remarks.

We don't intend to rewrite Au3Check from scratch

Sorry

[JohnOne]

I don't know how it's written, but I'll have to take that as a no.

[jpm]

I don't know how it's written, but I'll have to take that as a no.

Unless Some Dev as Jos find soultion ...

[JohnOne]

You mean if the encompassing braces were not required, au3check could handle that?

[jpm]

Will see what Jos can say about

[Ascend4nt]

 

Calling a member function with dot access works, but you have to surround it in parenthesis: 

($mMap2.func)()

Thanks for that. That's pretty ugly syntax, but I get that the parser has issues with it otherwise.

Anyway, I've updated my example after testing it on various embedded datatypes.  I was actually surprised to find out that DLLStructs are passed by reference (in stable and beta), rather than a copy being made..  interesting.  Also, the embedded-array access issue is a bit annoying, but that problem has been present with arrays-within-arrays as well.

Also, since Jon was cool enough to update the Beta docs, here's a link for anyone that hasn't played with the Beta's yet:

Overall: https://www.autoitscript.com/autoit3/files/beta/autoit/docs/

(currently, the Variables section has an overview of Maps, and Functions lists the Mapxx functions)

Also, the Map Management section: https://www.autoitscript.com/autoit3/files/beta/autoit/docs/functions/Map%20Management.htm

 

expandcollapse popup

#Region ;**** Directives created by AutoIt3Wrapper_GUI ****
#AutoIt3Wrapper_Version=Beta
#AutoIt3Wrapper_Outfile=MapTests.exe
#AutoIt3Wrapper_Change2CUI=y
#AutoIt3Wrapper_Run_AU3Check=n
#EndRegion ;**** Directives created by AutoIt3Wrapper_GUI ****
; -------------------------------------------------------------------------------------------
; Map Tests
;
; Requires AutoIt beta (v3.3.13.18 tested)
; -------------------------------------------------------------------------------------------
; NOTES:
; -----
; - Embedding other complex datatypes:
;   Anything inserted in Arrays and Maps are COPIES of the objects,
;   EXCEPT for DLLStruct's, which are reference types (at least in current AutoIt versions)
;   So, modifying embedded Arrays and Maps will NOT alter the originals
;
; - Calling functions:
;   Must be done using Map["func"]() or (Map.func)()
;   Functions in Arrays work with Arr[i]()
;
; - Arrays within Maps/Arrays:
;   Write access:
;    No manner of subscript access works, and parentheses around an expression causes a copy
;    to be made, which discards the value at the end of the statement
;    A function taking an Array ByRef can be used to workaround the problem, however
;
;   Read access:
;    dot-member access works:
;     Map.arr[0]
;    However for both Maps and arrays, using subscript operators requires parentheses:
;     (Map["arr"])(0)
;     (Arr[0])[0]
;
; - Maps inside maps:
;   Read/Write access:
;     Map["map"]["val"]
;     Map.map.val
;
; - Maps within Arrays:
;   Write access:
;     Arr[3].data
;   Read access:
;     Arr[3].data
;     (Arr[3])["data"]
;
; - DLLStructs' produce references to the original structure (in current AutoIt versions)
;   Read/Write access depends on Array or Map container:
;     Arr[i].stVal
;     Map["struct"].stVal
;     Map.struct.stVal
;
; -------------------------------------------------------------------------------------------

Func MyFunc()
    ConsoleWrite("Called MyFunc"&@LF)
EndFunc

Func ShowString(Const ByRef $mMap)
    If MapExists($mMap, "myString") Then ConsoleWrite("Map string = " & $mMap.myString & @LF)
EndFunc

Func ModifyArrayValue(ByRef $aArr, Const $i, Const ByRef $vData)
    If IsArray($aArr) Then $aArr[$i] = $vData
EndFunc

Func TestMaps()
    Local $aArr[4], $mMap[], $mMap2[]
    ;Dim $mMap2[]    ; Also works for declaring/redeclaring variable as Map

    ;; -= Function call Tests -=

    ; Indirect function call using array
    $aArr[0] = MyFunc
    $aArr[0]()

    ; Indirect function call using Map & array-style access
    $mMap["func"] = MyFunc
    $mMap["func"]()

    ; Indirect function call using Map & member/property access
    $mMap2.func = MyFunc
    ; Awkward syntax which works (Au3Check fails to handle this, however)
    ($mMap2.func)()
    ;$mMap2.func()  ; Preferred syntax (which doesn't work)

    ;; -= Value assignment Tests =-

    ; array-style assign & access:
    $mMap["val"] = 1
    ConsoleWrite("Map1 value = " & $mMap["val"] & @LF)

    ; member/property version
    $mMap2.val = 4
    ConsoleWrite("Map2 value = " & $mMap2.val & @LF)

    ; More values
    $mMap["myString"] = "aMap string"
    $mMap2.myString = "aMap2 string"

    ; Passing maps as parameters
    ShowString($mMap)
    ShowString($mMap2)

    ;; -= Embedded Array tests =-

    Local $aEmbedArr[2] = [1, 2]

    ; Makes *COPY* of array inside Map
    $mMap.arr = $aEmbedArr

    ; Modifying embedded array:

    ; Member/property access doesn't work:
    ;$mMap.arr[0] = 20

    ; Parentheses around a value forces a copy to be made [per Jon], not a reference:
;~     ($mMap.arr)[0] = 20    ; copy is made, and discarded

    ; array-style access doesn't work either:
    ;$mMap["arr"][0] = 20

    ; Indirect workaround (pass array as reference):
    ModifyArrayValue($mMap.arr, 0, 20)


    ConsoleWrite("Map:Embedded-Array elements:"&@LF)
    ; array-style access
    For $i = 0 To UBound($mMap["arr"]) - 1
        ; Note Awkward syntax for getting internal array element:
        ; ($mMap["arr"])($i)
        ConsoleWrite("#" & $i & " = " & ($mMap["arr"])[$i] & @LF)
    Next

    ; Member/property access:
    ConsoleWrite("[alternate member/property access]:"&@LF)
    For $i = 0 To UBound($mMap.arr) - 1
        ConsoleWrite("#" & $i & " = " & $mMap.arr[$i] & @LF)
    Next

    ; .. 'EmbeddedArray' value remains the same as its initial assignment:
    ConsoleWrite("..aEmbedArr[0] = " & $aEmbedArr[0] & @LF)

    ;; - Embedded array in array (no Map) -

    ; Makes *COPY* of EmbedArray inside Array
    $aArr[1] = $aEmbedArr

    ; Doesn't work:
    ;$aArr[1]0] = 40

    ; Parentheses around a value forces a copy to be made [per Jon], not a reference:
;~     ($aArr[1])[0] = 40 ; copy is made, and discarded

    ; Indirect workaround (pass array as reference):
    ModifyArrayValue($aArr[1], 0, 40)

    ConsoleWrite("Array:Embedded-Array elements:"&@LF)
    ; array-style access
    For $i = 0 To UBound($aArr[1]) - 1
        ; Note Awkward syntax for getting internal array element:
        ; ($aArr[1])[$i]
        ConsoleWrite("#" & $i & " = " & ($aArr[1])[$i] & @LF)
    Next


    ; .. 'EmbeddedArray' value remains the same as its initial assignment:
    ConsoleWrite("..aEmbedArr[0] = " & $aEmbedArr[0] & @LF)

    ;; -= Structures =-

    Local $tStruct = DllStructCreate("int MyInt;")
    ; Structure normal access:
    DllStructSetData($tStruct, "MyInt", 10)

    ; Structure property-access:
    $tStruct.myInt = 20

    ; Assign structure to Map (actually creates a reference rather than a copy)
    $mMap.struct = $tStruct

    ; Modify structure data (both ways work)
    $mMap.struct.myInt = 40
    $mMap["struct"].myInt = 60

    ConsoleWrite("mMap.struct.myInt = " & $mMap.struct.myInt & @LF)

    ; Struct Inside array (creates reference to original struct)

    $aArr[3] = $tStruct
    $aArr[3].myInt = 80
    ConsoleWrite("aArr[3].myInt = " & $aArr[3].myInt & @LF)

    ; Original Structure is modified by all operations above (even embedded in Maps or Arrays)
    ConsoleWrite("tStruct.myInt = " & $tStruct.myInt & @LF)
    ConsoleWrite("DLLStructGetData($tStruct, 'myInt') = " & DllStructGetData($tStruct, "myInt") &@LF)


    ;; -= Maps within Maps =-

    Local $mEmbedMap[]
    $mEmbedMap.innerVal = 4

    ; This causes a *COPY* of $mEmbedMap to be added to $mMap:
    $mMap.embeddedMap = $mEmbedMap

    ; Modifying the embedded map doesn't affect the external one
    $mMap.embeddedMap.innerVal = 10
    ConsoleWrite("Map.embeddedMap.innerVal = " & $mMap.embeddedMap.innerVal & @LF)
    ; Alternate ways of writing the above line:
    ; (Note how 2 subscripts can be used here, as opposed to embedded arrays):
    ConsoleWrite("Map[embeddedMap][innerVal] = " & $mMap["embeddedMap"]["innerVal"] & @LF)
    ConsoleWrite("Map[embeddedMap].innerVal = " & $mMap["embeddedMap"].innerVal & @LF)


    ; .. 'EmbedMap' value remains the same as its initial assignment:
    ConsoleWrite("..EmbedMap.innerVal = " & $mEmbedMap.innerVal & @LF)

    ;; -= Maps within Arrays =-

    ; Creates a *COPY* of Map inside array
    $aArr[3] = $mEmbedMap

    $aArr[3].innerVal = 20
    ; Parentheses around a value forces a copy to be made [per Jon], not a reference:
;~     ($aArr[3])["innerVal"] = 40 ; copy is made, and discarded

    ConsoleWrite("Arr[embeddedMap].innerVal = " & $aArr[3].innerVal &@LF)
    ; Note Awkward syntax for getting internal array element:
    ; ($aArr[3])["innerVal"]
    ConsoleWrite("(Arr[embeddedMap])[innerVal] = " & ($aArr[3])["innerVal"] &@LF)

    ; .. 'EmbedMap' value remains the same as its initial assignment:
    ConsoleWrite("..EmbedMap.innerVal = " & $mEmbedMap.innerVal & @LF)

EndFunc

TestMaps()

[JohnOne]

What I'm struggling to understand about array access within a map is that if the value can be retrieved I'd have thought it could be set.

With an array in an array, you cannot even get a value of an element.

[guinness]

Here...

Local $aInternal = [99, "Problems"]
Local $aArray = [$aInternal]
ConsoleWrite(($aArray[0])[0] & " " & ($aArray[0])[1] & @CRLF)

[Ascend4nt]

So, for the Map types to become a really well integrated part of the language, there needs to be some support for string literal assignments. Without this kind of support, its very tedious to use Maps in many situations.

When I talk literals, I mean something like this:

$mMap [] = { "val" : 1, "valB" : $nVal, "name" : "Bob Smith", "array" : $myArray}

There's other ways to do the above, depending on the language, but I think that is one of the easiest ways to format it.

Anyway, for anyone looking to add *very* simplistic Map-literal assignment/addition to a Map, here's an example of how it could be done for the simplest of types (alphanumeric kinds of assignments):

expandcollapse popup

; =================================================================================================
; Func _MapCreateFromStringLiteral($sMapLits)
;
; Given a string literal, creates and adds key/values to a new map which is returned.
; Note this is VERY simplistic and is really more for alphanumeric types of assignments.
;
; String literal for Maps is in the form of Javascript & D, except with quotes in place of brackets
; Example:
;  "[valA : mapVal, valB : 123, 3 : 4]" is the equivalent of:
;    Map["valA"] = "mapVal"
;    Map["valB"] = "123"
;    Map["3"] = "4"
;
; Note that currently there is no numeric conversion ("123" doesn't get converted to 123),
; however comparisons like ("123" = 123" work in AutoIt
;
; Returns:
;  Success: new Map
;  Failure: "" with @error set
;
; Author: Ascend4nt
; =================================================================================================
Func _MapCreateFromStringLiteral($sMapLits)
    Local $mMap []
    If Not _MapAddFromStringLiteral($mMap, $sMapLits) Then Return SetError(@error, @extended, "")
    Return $mMap
EndFunc
; =================================================================================================
; Func _MapAddFromStringLiteral(ByRef $mMap, $sMapLits)
;
; Given a string literal, creates and adds key/values to the given Map parameter.
; Note this is VERY simplistic and is really more for alphanumeric types of assignments.
;
; String literal for Maps is in the form of Javascript & D, except with quotes in place of brackets
; Example:
;  "{valA : mapVal, valB : 123, 3 : 4}" is the equivalent of:
;    Map["valA"] = "mapVal"
;    Map["valB"] = "123"
;    Map["3"] = "4"
;
; Note that currently there is no numeric conversion ("123" doesn't get converted to 123),
; however comparisons like ("123" = 123") work in AutoIt
;
; Returns True on success, False on failure with @error set
;
; Author: Ascend4nt
; =================================================================================================
Func _MapAddFromStringLiteral(ByRef $mMap, $sMapLits)
    If Not IsString($sMapLits) Or $sMapLits = "" Or Not IsMap($mMap) Then Return SetError(1, 0, False)
    ; Pull out "key:val" pairs. Optional whitespace surrounds each element (comma typically separates the pairs)
    Local $aMapVals = StringRegExp($sMapLits, "(\w+)\s*:\s*(\w+)", 3)
    If @error Then Return SetError(1, 0, False)
    For $i = 0 To (UBound($aMapVals) - 1) Step 2
        ;ConsoleWrite("Next assignment: Key '" & $aMapVals[$i] & "' = " & $aMapVals[$i + 1] & @CRLF)
        $mMap[$aMapVals[$i]] = $aMapVals[$i + 1]
    Next
    Return True
EndFunc

  ;; -= Map from Literals =-

  Local $mMapFromLits = _MapCreateFromStringLiteral("{byte:1, short:2, int:4, int64:8, float:4, double:8}")

  _MapAddFromStringLiteral($mMapFromLits, "{  char  :  1 ,  wchar  :  2  }")

  ConsoleWrite("# of Keys in $mMapFromLits = " & UBound($mMapFromLits) & ":" & @CRLF)

  For $kKey In MapKeys($mMapFromLits)
      ConsoleWrite("Map['" & $kKey & "'] = " & $mMapFromLits[$kKey] & @CRLF)
  Next

[TheDcoder]

Maps accepts any datatype as an key?

Local $mMap[]

$mMap["String"] = "String Map"
$mMap[0] = "Integer Map"
$mMap[0.1] = "Float Map"
$mMap[True] = "Bool Map"

MsgBox(0, 0, $mMap["String"] & @CRLF & $mMap[0] & @CRLF & $mMap[0.1] & @CRLF & $mMap[True])

 

Edited October 20, 2015 by TheDcoder
Forgot to declare $mMap :P