map
The file builtins\map.e (not an autoinclude) provides partial compatibility for Euphoria’s std\map.e
It is based on builtins\dict.e, rather than hashing.
There is no notion of large/small maps, and hence no threshold() or type_of() routines.
A map (-id) is just a small integer index (as per new_dict).
There is none of that ADD/SUBTRACT/MULTIPLY/DIVIDE/APPEND/CONCAT/LEAVE nonsense.
There is no nested_get or nested_put (for which someone should be shot?).
There is no "new_extra" - don’t really understand that, besides initial_size_p would be ignored.
There is no "rehash" (obviously) or "optimise" (simply no need, period).
There is no compare or copy (would probably be pretty trivial if needed).
There is no "new_from_kvpairs" (ditto) or "new_from_string" (ugh, but do-able).
for_each has no sorted order option (it alway is), nor any of that signal_boundary nonsense
(that someone put in and then added the signal_boundary parameter [which this does not have] to get rid of).
There is no such thing as "raw mode"; save_map and load_map only operate on plain text files.
Likewise there is no special handling of ,/$ but instead strings cannot be split, whereas sequences that span several lines are handled quite naturally.
Also, load_map does not support "bare strings": instead of this=that the input file must contain "this"="that".
It returns a string error message (rather than an integer map) if it was unable to decipher anything in the input file.
Offending items have been moved to the .syn "incompatible" section (ie nested_get/nested_put/new_extra/new_from_kvpairs/new_from_string/optimize/rehash).
Finally, while clear(map m) is fine, you should really invoke destroy_dict(map m) when you have no further use for map m.
Despite such differences, you should be able to achieve anything you can with std\map.e on Euphoria, with builtins\map.e on Phix.
Personally, however, I would recommend using builtins\dict.e directly.
(You can legally pass the result from load_map as a tid to the dict routines, and use it or a tid from new_dict() when invoking save_map.)
There is NOT even the SLIGHTEST nod to making these things thread-safe, except (perhaps) as documented for the dict.e routines. Certainly the routines pairs/keys/values/for_each/save_map/load_map would all require an exclusive system-wide lock for their entire duration.
These routines are fully supported by pwa/p2js, with the exception of save_map() and load_map().
There is also a JavaScript Array.map() routine, which is not further documented here.
Quick Summary (omitting any "map:" qualifiers):
Note that size() is deliberately not syntax-coloured, because that identifier is too commonly used for other things - however F1 help (on "size") does link here, but then again remove() [and copy()/compare() if they existed] do not, and if map.e was anything but a compatibility shim, I would[/will] rename them as something that does not clash.
It is based on builtins\dict.e, rather than hashing.
There is no notion of large/small maps, and hence no threshold() or type_of() routines.
A map (-id) is just a small integer index (as per new_dict).
There is none of that ADD/SUBTRACT/MULTIPLY/DIVIDE/APPEND/CONCAT/LEAVE nonsense.
There is no nested_get or nested_put (for which someone should be shot?).
There is no "new_extra" - don’t really understand that, besides initial_size_p would be ignored.
There is no "rehash" (obviously) or "optimise" (simply no need, period).
There is no compare or copy (would probably be pretty trivial if needed).
There is no "new_from_kvpairs" (ditto) or "new_from_string" (ugh, but do-able).
for_each has no sorted order option (it alway is), nor any of that signal_boundary nonsense
(that someone put in and then added the signal_boundary parameter [which this does not have] to get rid of).
There is no such thing as "raw mode"; save_map and load_map only operate on plain text files.
Likewise there is no special handling of ,/$ but instead strings cannot be split, whereas sequences that span several lines are handled quite naturally.
Also, load_map does not support "bare strings": instead of this=that the input file must contain "this"="that".
It returns a string error message (rather than an integer map) if it was unable to decipher anything in the input file.
Offending items have been moved to the .syn "incompatible" section (ie nested_get/
Finally, while clear(map m) is fine, you should really invoke destroy_dict(map m) when you have no further use for map m.
Despite such differences, you should be able to achieve anything you can with std\map.e on Euphoria, with builtins\map.e on Phix.
Personally, however, I would recommend using builtins\dict.e directly.
(You can legally pass the result from load_map as a tid to the dict routines, and use it or a tid from new_dict() when invoking save_map.)
There is NOT even the SLIGHTEST nod to making these things thread-safe, except (perhaps) as documented for the dict.e routines. Certainly the routines pairs/keys/values/for_each/save_map/load_map would all require an exclusive system-wide lock for their entire duration.
These routines are fully supported by pwa/p2js, with the exception of save_map() and load_map().
There is also a JavaScript Array.map() routine, which is not further documented here.
Quick Summary (omitting any "map:" qualifiers):
map m
bool r = map(object o)
map m = new_map() -- (renamed from new() 17/01/20 as part of the new struct handling)
put(map m, object key, object val)
bool b = has(map m, object key)
object val = map_get(map m, object key, object defval=0) -- (renamed from get() 29/12/21)
remove(map m, object key)
sequence full_map = pairs(map m=1)
sequence all_keys = keys(map m=1)
sequence all_vals = values(map m=1)
object res = for_each(map m, integer rid, object user_data=0)
-- [a res of 0 indicates that all items were processed]
integer count = size(map m=1)
integer count = save_map(map m, object file)
map m = load_map(object file)
clear(map m)
destroy_dict(map m) -- [part of dict.e]
These routines are provided for compatibility only, and any further detail is beyond the remit of such a simple wrapper shim.Note that size() is deliberately not syntax-coloured, because that identifier is too commonly used for other things - however F1 help (on "size") does link here, but then again remove() [and copy()/compare() if they existed] do not, and if map.e was anything but a compatibility shim, I would[/will] rename them as something that does not clash.