AddMapElement()

Syntax

Result = AddMapElement(Map(), Key$ [, Flags])

Adds a new empty element in the Map() using the specified 'Key$'. This new element becomes the current element of the map. If Result is 0, then the element has not been created (out of memory), else it returns the pointer to the element data (for advanced use only).

'Flags' is an optional parameter which can be one of the following value:

  #PB_Map_ElementCheck  : Checks if an element with a same key already exists, and replaces it (default).
  #PB_Map_NoElementCheck: No element check, so if a previous element with the same key was already present, it 
                      will be not replaced but kept in the map without be reachable with direct access. It will remain unreachable 
                      until the newly added element has been deleted. Such unreachable elements will still be listed when enumerating
                      all the map elements with ForEach or NextMapElement(). This mode is faster but also more 
                      error prone, so use it with caution.

Note: This function isn't mandatory when dealing with maps, as elements are automatically added when affecting a value to them.

Example:

  NewMap Country.s()
  
  ; Regular way to add an element
  Country("US") = "United State"
  
  ; The same using AddMapElement()
  AddMapElement(Country(), "FR")
  Country() = "France"
  
  ForEach Country()
    Debug Country()
  Next

Supported OS

All