AddMapElement()

Syntax

Result = AddMapElement(Map(), Key$ [, Flags])
Description
Adds a new empty element in the Map() using the specified key. This new element becomes the current element of the map.

Parameters

Map() The map to which to add the element.
Key$ The key for the new element.
Flags (optional) Flags can be one of the following values:
  #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, unreachable 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.

Return value

Returns nonzero on success and zero on failure. The value returned is a pointer to the new element data.

Remarks

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 States"
  
  ; The same using AddMapElement()
  AddMapElement(Country(), "FR")
  Country() = "France"
  
  ForEach Country()
    Debug Country()
  Next

See Also

DeleteMapElement(), ClearMap(), MapSize()

Supported OS

All

Map Index - ClearMap() ->