OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.32 Hashing Algorithms | Up: 8 API Reference | 8.34 Stack > | 9 Release Notes >>

## 8.33 Map (Hash Table)

A map is a special array, often called an associative array or dictionary; in a map the data values (any Euphoria object) are indexed by keys (also any Euphoria object).

When programming think in terms of key:value pairs. For example we can code things like this:

    custrec = new() -- Create a new map
       put(custrec, "Name", "Joe Blow")
       put(custrec, "Address", "555 High Street")
       put(custrec, "Phone", 555675632)

This creates three elements in the map, and they are indexed by `"Name"`, `"Address"` and `"Phone"`, meaning that to get the data associated with those keys we can code:

    object data = get(custrec, "Phone")
       -- data now set to 555675632

Note that only one instance of a given key can exist in a given map, meaning for example, we could not have two separate `"Name"` values in the above `custrec` map.

Maps automatically grow to accommodate all the elements placed into it.

Associative arrays can be implemented in many different ways, depending on what efficiency trade-offs have been made. This implementation allows you to specify how many items you expect the map to hold, or simply start with the default size.

As the number of items in the map grows, the map may increase its size to accommodate larger numbers of items.

### 8.33.1 Operation Codes for Put

#### 8.33.1.1 PUT

    include std/map.e
    namespace map
    public enum PUT

#### 8.33.1.2 ADD

    include std/map.e
    namespace map
    public enum ADD

#### 8.33.1.3 SUBTRACT

    include std/map.e
    namespace map
    public enum SUBTRACT

#### 8.33.1.4 MULTIPLY

    include std/map.e
    namespace map
    public enum MULTIPLY

#### 8.33.1.5 DIVIDE

    include std/map.e
    namespace map
    public enum DIVIDE

#### 8.33.1.6 APPEND

    include std/map.e
    namespace map
    public enum APPEND

#### 8.33.1.7 CONCAT

    include std/map.e
    namespace map
    public enum CONCAT

#### 8.33.1.8 LEAVE

    include std/map.e
    namespace map
    public enum LEAVE

### 8.33.2 Types

#### 8.33.2.1 map

    include std/map.e
    namespace map
    public type map(object m)

defines the datatype 'map'.

##### Comments:

Used when declaring a map variable.

##### Example 1:

    map SymbolTable = new() -- Create a new map to hold the symbol table.

### 8.33.3 Routines

#### 8.33.3.1 calc_hash

    include std/map.e
    namespace map
    public function calc_hash(object key_p, integer max_hash_p)

calculates a Hashing value from the supplied data.

##### Parameters:

1. `key_p` : The data for which you want a hash value calculated.
2. `max_hash_p` : The returned value will be no larger than this value.

##### Returns:

An integer, the value of which depends only on the supplied data.

##### Comments:

This is used whenever you need a single number to represent the data you supply. It can calculate the number based on all the data you give it, which can be an atom or sequence of any value.

##### Example 1:

    integer h1
    -- calculate a hash value and ensure it will be a value from 1 to 4097.
    h1 = calc_hash( symbol_name, 4097 )

#### 8.33.3.2 threshold

    include std/map.e
    namespace map
    public function threshold(integer new_value_p = 0)

deprecated.

##### Parameters:

1. `new_value_p` : unused value.

##### Returns:

Zero..

#### 8.33.3.3 type_of

    include std/map.e
    namespace map
    public function type_of(map the_map_p)

deprecated

##### Parameters:

1. `m` : A map

##### Returns:

Zero.

#### 8.33.3.4 rehash

    include std/map.e
    namespace map
    public procedure rehash(map the_map_p, integer requested_size_p = 0)

changes the width (that is the number of buckets) of a map.

##### Parameters:

1. `m` : the map to resize
2. `requested_size_p` : a lower limit for the new size.

##### Comments:

If `requested_size_p` is not greater than zero, a new width is automatically derived from the current one.

##### See Also:

statistics, optimize

#### 8.33.3.5 new

    include std/map.e
    namespace map
    public function new(integer initial_size_p = DEFAULT_SIZE)

creates a new map data structure.

##### Parameters:

1. `initial_size_p` : An estimate of how many initial elements will be stored in the map.

##### Returns:

An empty map.

##### Comments:

A new object of type map is created. The resources allocated for the map will be automatically cleaned up if the reference count of the returned value drops to zero, or if passed in a call to delete.

##### Example 1:

    map m = new()  -- m is now an empty map
    x = new()    -- the resources for the map previously stored in x are released automatically
    delete( m )  -- the resources for the map are released

#### 8.33.3.6 new_extra

    include std/map.e
    namespace map
    public function new_extra(object the_map_p, integer initial_size_p = 8)

returns either the supplied map or a new map.

##### Parameters:

1. `the_map_p` : An object, that could be an existing map
2. `initial_size_p` : An estimate of how many initial elements will be stored in a new map.

##### Returns:

A map, If `m` is an existing map then it is returned otherwise this returns a new empty map.

##### Comments:

This is used to return a new map if the supplied variable isn't already a map.

##### Example 1:

    map m = new_extra( foo() ) -- If foo() returns a map it is used, otherwise
                               --  a new map is created.

#### 8.33.3.7 compare

    include std/map.e
    namespace map
    public function compare(map map_1_p, map map_2_p, integer scope_p = 'd')

compares two maps to test equality.

##### Parameters:

1. `map_1_p` : A map
2. `map_2_p` : A map
3. `scope_p` : An integer that specifies what to compare.
   - 'k' or 'K' to only compare keys.
   - 'v' or 'V' to only compare values.
   - 'd' or 'D' to compare both keys and values. This is the default.

##### Returns:

An integer,

- -1 if they are not equal.
- 0 if they are literally the same map.
- 1 if they contain the same keys and/or values.

##### Example 1:

    map map_1_p = foo()
    map map_2_p = bar()
    if compare(map_1_p, map_2_p, 'k') >= 0 then
         ... -- two maps have the same keys

#### 8.33.3.8 has

    include std/map.e
    namespace map
    public function has(map the_map_p, object key)

checks whether map has a given key.

##### Parameters:

1. `the_map_p` : the map to inspect
2. `the_key_p` : an object to be looked up

##### Returns:

An integer, 0 if not present, 1 if present.

##### Example 1:

    map the_map_p
    the_map_p = new()
    put(the_map_p, "name", "John")
    ? has(the_map_p, "name") -- 1
    ? has(the_map_p, "age")  -- 0

##### See Also:

get

#### 8.33.3.9 get

    include std/map.e
    namespace map
    public function get(map the_map_p, object key, object default = 0)

retrieves the value associated to a key in a map.

##### Parameters:

1. `the_map_p` : the map to inspect
2. `the_key_p` : an object, the the_key_p being looked tp
3. `default_value_p` : an object, a default value returned if `the_key_p` not found. The default is 0.

##### Returns:

An object, the value that corresponds to `the_key_p` in `the_map_p`. If `the_key_p` is not in `the_map_p`, `default_value_p` is returned instead.

##### Example 1:

    map ages
    ages = new()
    put(ages, "Andy", 12)
    put(ages, "Budi", 13)

    integer age
    age = get(ages, "Budi", -1)
    if age = -1 then
        puts(1, "Age unknown")
    else
        printf(1, "The age is %d", age)
    end if

##### See Also:

has

#### 8.33.3.10 nested_get

    include std/map.e
    namespace map
    public function nested_get(map the_map_p, sequence the_keys_p, object default_value_p = 0)

returns the value given a nested key.

##### Comments:

Returns the value that corresponds to the object `the_keys_p` in the nested map the_map_p. `the_keys_p` is a sequence of keys. If any key is not in the map, the object default_value_p is returned instead.

#### 8.33.3.11 put

    include std/map.e
    namespace map
    public procedure put(map the_map_p, object key, object val, object op = PUT,
            object deprecated = 0)

adds or updates an entry on a map.

##### Parameters:

1. `the_map_p` : the map where an entry is being added or updated
2. `the_key_p` : an object, the the_key_p to look up
3. `the_value_p` : an object, the value to add, or to use for updating.
4. `operation` : an integer, indicating what is to be done with `the_value_p`. Defaults to PUT.
5. `trigger_p` : Deprecated. This parameter defaults to zero and is not used.

##### Comments:

- The operation parameter can be used to modify the existing value. Valid operations are:

- - `PUT` -- This is the default, and it replaces any value in there already
  - `ADD` -- Equivalent to using the += operator
  - `SUBTRACT` -- Equivalent to using the -= operator
  - `MULTIPLY` -- Equivalent to using the *= operator
  - `DIVIDE` -- Equivalent to using the /= operator
  - `APPEND` -- Appends the value to the existing data
  - `CONCAT` -- Equivalent to using the &= operator
  - `LEAVE` -- If it already exists, the current value is left unchanged otherwise the new value is added to the map.

##### Example 1:

    map ages
    ages = new()
    put(ages, "Andy", 12)
    put(ages, "Budi", 13)
    put(ages, "Budi", 14)

    -- ages now contains 2 entries: "Andy" => 12, "Budi" => 14

##### See Also:

remove, has, nested_put

#### 8.33.3.12 nested_put

    include std/map.e
    namespace map
    public procedure nested_put(map the_map_p, sequence the_keys_p, object the_value_p,
            integer operation_p = PUT, object deprecated_trigger_p = 0)

adds or updates an entry on a map.

##### Parameters:

1. `the_map_p` : the map where an entry is being added or updated
2. `the_keys_p` : a sequence of keys for the nested maps
3. `the_value_p` : an object, the value to add, or to use for updating.
4. `operation_p` : an integer, indicating what is to be done with `value`. Defaults to PUT.
5. `deprecated_trigger_p` : Deprecated. This parameter defaults to zero and is not used.

##### Comments:

Valid operations are:

- `PUT` -- This is the default, and it replaces any value in there already
- `ADD` -- Equivalent to using the += operator
- `SUBTRACT` -- Equivalent to using the -= operator
- `MULTIPLY` -- Equivalent to using the *= operator
- `DIVIDE` -- Equivalent to using the /= operator
- `APPEND` -- Appends the value to the existing data
- `CONCAT` -- Equivalent to using the &= operator

- If existing entry with the same key is already in the map, the value of the entry is updated.

##### Example 1:

    map city_population
    city_population = new()
    nested_put(city_population, {"United States", "California", "Los Angeles"},
        3819951 )
    nested_put(city_population, {"Canada",        "Ontario",    "Toronto"},
        2503281 )

##### See Also:

put

#### 8.33.3.13 remove

    include std/map.e
    namespace map
    public procedure remove(map the_map_p, object key)

removes an entry with given key from a map.

##### Parameters:

1. `the_map_p` : the map to operate on
2. `key` : an object, the key to remove.

##### Comments:

- If `key` is not on `the_map_p`, the `the_map_p` is returned unchanged.
- If you need to remove all entries, see clear

##### Example 1:

    map the_map_p
    the_map_p = new()
    put(the_map_p, "Amy", 66.9)
    remove(the_map_p, "Amy")
    -- the_map_p is now an empty map again

##### See Also:

clear, has

#### 8.33.3.14 clear

    include std/map.e
    namespace map
    public procedure clear(map the_map_p)

removes all entries in a map.

##### Parameters:

1. `the_map_p` : the map to operate on

##### Comments:

- This is much faster than removing each entry individually.
- If you need to remove just one entry, see remove

##### Example 1:

    map the_map_p
    the_map_p = new()
    put(the_map_p, "Amy", 66.9)
    put(the_map_p, "Betty", 67.8)
    put(the_map_p, "Claire", 64.1)
    ...
    clear(the_map_p)
    -- the_map_p is now an empty map again

##### See Also:

remove, has

#### 8.33.3.15 size

    include std/map.e
    namespace map
    public function size(map the_map_p)

returns the number of entries in a map.

##### Parameters:

`the_map_p` : the map being queried

##### Returns:

An integer, the number of entries it has.

##### Comments:

For an empty map, size will be zero

##### Example 1:

    map the_map_p
    put(the_map_p, 1, "a")
    put(the_map_p, 2, "b")
    ? size(the_map_p) -- outputs 2

##### See Also:

statistics

#### 8.33.3.16 NUM_ENTRIES

    include std/map.e
    namespace map
    public enum NUM_ENTRIES

#### 8.33.3.17 NUM_IN_USE

    include std/map.e
    namespace map
    public enum NUM_IN_USE

#### 8.33.3.18 NUM_BUCKETS

    include std/map.e
    namespace map
    public enum NUM_BUCKETS

#### 8.33.3.19 LARGEST_BUCKET

    include std/map.e
    namespace map
    public enum LARGEST_BUCKET

#### 8.33.3.20 SMALLEST_BUCKET

    include std/map.e
    namespace map
    public enum SMALLEST_BUCKET

#### 8.33.3.21 AVERAGE_BUCKET

    include std/map.e
    namespace map
    public enum AVERAGE_BUCKET

#### 8.33.3.22 STDEV_BUCKET

    include std/map.e
    namespace map
    public enum STDEV_BUCKET

#### 8.33.3.23 statistics

    include std/map.e
    namespace map
    public function statistics(map the_map_p)

retrieves characteristics of a map.

##### Parameters:

1. `the_map_p` : the map being queried

##### Returns:

A sequence, of 7 integers:

- `NUM_ENTRIES` -- number of entries
- `NUM_IN_USE` -- number of buckets in use
- `NUM_BUCKETS` -- number of buckets
- `LARGEST_BUCKET` -- size of largest bucket
- `SMALLEST_BUCKET` -- size of smallest bucket
- `AVERAGE_BUCKET` -- average size for a bucket
- `STDEV_BUCKET` -- standard deviation for the bucket length series

##### Example 1:

    sequence s = statistics(mymap)
    printf(1, "The average size of the buckets is %d", s[AVERAGE_BUCKET])

#### 8.33.3.24 keys

    include std/map.e
    namespace map
    public function keys(map the_map_p, integer sorted_result = 0)

returns all keys in a map.

##### Parameters:

1. `the_map_p`: the map being queried
2. `sorted_result`: optional integer. 0 [default] means do not sort the output and 1 means to sort the output before returning.

##### Returns:

A sequence made of all the keys in the map.

##### Comments:

If `sorted_result` is not used, the order of the keys returned is not predicable.

##### Example 1:

    map the_map_p
    the_map_p = new()
    put(the_map_p, 10, "ten")
    put(the_map_p, 20, "twenty")
    put(the_map_p, 30, "thirty")
    put(the_map_p, 40, "forty")

    sequence keys
    keys = keys(the_map_p) -- keys might be {20,40,10,30} or some other order
    keys = keys(the_map_p, 1) -- keys will be {10,20,30,40}

##### See Also:

has, values, pairs

#### 8.33.3.25 values

    include std/map.e
    namespace map
    public function values(map the_map, object keys = 0, object default_values = 0)

returns values, without their keys, from a map.

##### Parameters:

1. `the_map` : the map being queried
2. `keys` : optional, key list of values to return.
3. `default_values` : optional default values for keys list

##### Returns:

A sequence, of all values stored in `the_map`.

##### Comments:

- The order of the values returned may not be the same as the putting order.
- Duplicate values are not removed.
- You use the `keys` parameter to return a specific set of values from the map. They are returned in the same order as the `keys` parameter. If no `default_values` is given and one is needed, 0 will be used.
- If `default_values` is an atom, it represents the default value for all values in `keys`.
- If `default_values` is a sequence, and its length is less than `keys`, then the last item in `default_values` is used for the rest of the `keys`.

##### Example 1:

    map the_map_p
    the_map_p = new()
    put(the_map_p, 10, "ten")
    put(the_map_p, 20, "twenty")
    put(the_map_p, 30, "thirty")
    put(the_map_p, 40, "forty")

    sequence values
    values = values(the_map_p)
    -- values might be {"twenty","forty","ten","thirty"}
    -- or some other order

##### Example 2:

    map the_map_p
    the_map_p = new()
    put(the_map_p, 10, "ten")
    put(the_map_p, 20, "twenty")
    put(the_map_p, 30, "thirty")
    put(the_map_p, 40, "forty")

    sequence values
    values = values(the_map_p, { 10, 50, 30, 9000 })
    -- values WILL be { "ten", 0, "thirty", 0 }
    values = values(the_map_p, { 10, 50, 30, 9000 }, {-1,-2,-3,-4})
    -- values WILL be { "ten", -2, "thirty", -4 }

##### See Also:

get, keys, pairs

#### 8.33.3.26 pairs

    include std/map.e
    namespace map
    public function pairs(map the_map, integer sorted_result = 0)

returns all key:value pairs in a map.

##### Parameters:

1. `the_map_p` : the map to get the data from
2. `sorted_result` : optional integer. 0 [default] means do not sort the output and 1 means to sort the output before returning.

##### Returns:

A sequence, of all key:value pairs stored in `the_map_p`. Each pair is a sub-sequence in the form `{key, value}`

##### Comments:

If `sorted_result` is not used, the order of the values returned is not predicable.

##### Example 1:

    map the_map_p

    the_map_p = new()
    put(the_map_p, 10, "ten")
    put(the_map_p, 20, "twenty")
    put(the_map_p, 30, "thirty")
    put(the_map_p, 40, "forty")

    sequence keyvals
    keyvals = pairs(the_map_p)
    -- might be {{20,"twenty"},{40,"forty"},{10,"ten"},{30,"thirty"}}

    keyvals = pairs(the_map_p, 1)
    -- will be {{10,"ten"},{20,"twenty"},{30,"thirty"},{40,"forty"}}

##### See Also:

get, keys, values

#### 8.33.3.27 optimize

    include std/map.e
    namespace map
    public procedure optimize(map the_map_p, integer deprecated_max_p = 0,
            atom deprecated_grow_p = 0)

rehashes a map to increase performance. This procedure is deprecated in favor of rehash.

##### Parameters:

1. `the_map_p` : the map being optimized
2. `deprecated_max_p` : unused
3. `deprecated_grow_p` : unused.

##### Comments:

This rehashes the map until either the maximum bucket size is less than the desired maximum or the maximum bucket size is less than the largest size statistically expected (mean + 3 standard deviations).

##### See Also:

statistics, rehash

#### 8.33.3.28 load_map

    include std/map.e
    namespace map
    public function load_map(object input_file_name)

loads a map from a file.

##### Parameters:

1. `file_name_p` : The file to load from. This file may have been created by the save_map function. This can either be a name of a file or an already opened file handle.

##### Returns:

Either a map, with all the entries found in `file_name_p`, or -1 if the file failed to open, or -2 if the file is incorrectly formatted.

##### Comments:

If `file_name_p` is an already opened file handle, this routine will read from that file and not close it. Otherwise, the named file will be opened and closed by this routine.

The input file can be either one created by the save_map function or a manually created or edited text file. See save_map for details about the required layout of the text file.

##### Example 1:

    include std/error.e

    object loaded
    map AppOptions
    sequence SavedMap = "c:\\myapp\\options.txt"

    loaded = load_map(SavedMap)
    if equal(loaded, -1) then
        crash("Map '%s' failed to open", SavedMap)
    end iF

    -- By now we know that it was loaded and a new map created,
    -- so we can assign it to a 'map' variable.
    AppOptions = loaded
    if get(AppOptions, "verbose", 1) = 3 then
        ShowIntructions()
    end if

##### See Also:

new, save_map

#### 8.33.3.29 SM_TEXT

    include std/map.e
    namespace map
    public enum SM_TEXT

#### 8.33.3.30 SM_RAW

    include std/map.e
    namespace map
    public enum SM_RAW

#### 8.33.3.31 save_map

    include std/map.e
    namespace map
    public function save_map(map the_map_, object file_name_p, integer type_ = SM_TEXT)

saves a map to a file.

##### Parameters:

1. `m` : a map.
2. `file_name_p` : Either a sequence, the name of the file to save to, or an open file handle as returned by open().
3. `type` : an integer. SM_TEXT for a human-readable format (default), SM_RAW for a smaller and faster format, but not human-readable.

##### Returns:

An integer, the number of keys saved to the file, or -1 if the save failed.

##### Comments:

If `file_name_p` is an already opened file handle, this routine will write to that file and not close it. Otherwise, the named file will be created and closed by this routine.

The SM_TEXT type saves the map keys and values in a text format which can be read and edited by standard text editor. Each entry in the map is saved as a KEY/VALUE pair in the form

    key = value

Note that if the 'key' value is a normal string value, it can be enclosed in double quotes. If it is not thus quoted, the first character of the key determines its Euphoria value type. A dash or digit implies an atom, an left-brace implies a sequence, an alphabetic character implies a text string that extends to the next equal '=' symbol, and anything else is ignored.

Note that if a line contains a double-dash, then all text from the double-dash to the end of the line will be ignored. This is so you can optionally add comments to the saved map. Also, any blank lines are ignored too.

All text after the '=' symbol is assumed to be the map item's value data.

Because some map data can be rather long, it is possible to split the text into multiple lines, which will be considered by load_map as a single logical line. If an line ends with a comma (,) or a dollar sign ($), then the next actual line is appended to the end of it. After all these physical lines have been joined into one logical line, all combinations of `",$"` and `,$` are removed.

For example:

    one = {"first",
    "second",
    "third",
    $
    }
    second = "A long text ",$
    "line that has been",$
    " split into three lines"
    third = {"first",
    "second",
    "third"}

is equivalent to

    one = {"first","second","third"}
    second = "A long text line that has been split into three lines"
    third = {"first","second","third"}

The SM_RAW type saves the map in an efficient manner. It is generally smaller than the text format and is faster to process, but it is not human readable and standard text editors can not be used to edit it. In this format, the file will contain three serialized sequences:

1. Header sequence: {integer:format version, string: date and time of save (YYMMDDhhmmss), sequence: euphoria version {major, minor, revision, patch}}
2. Keys. A list of all the keys
3. Values. A list of the corresponding values for the keys.

##### Example 1:

    include std/error.e

    map AppOptions
    if save_map(AppOptions, "c:\myapp\options.txt") = -1
        crash("Failed to save application options")
    end if

    if save_map(AppOptions, "c:\myapp\options.dat", SM_RAW) = -1
        crash("Failed to save application options")
    end if

##### See Also:

load_map

#### 8.33.3.32 copy

    include std/map.e
    namespace map
    public function copy(map source_map, object dest_map = 0, integer put_operation = PUT)

duplicates a map.

##### Parameters:

1. `source_map` : map to copy from
2. `dest_map` : optional, map to copy to
3. `put_operation` : optional, operation to use when `dest_map` is used. The default is PUT.

##### Returns:

If `dest_map` was not provided, an exact duplicate of `source_map` otherwise `dest_map`, which does not have to be empty, is returned with the new values copied from `source_map`, according to the `put_operation` value.

##### Example 1:

    map m1 = new()
    put(m1, 1, "one")
    put(m1, 2, "two")

    map m2 = copy(m1)
    printf(1, "%s, %s\n", { get(m2, 1), get(m2, 2) })
    -- one, two

    put(m1, 1, "one hundred")
    printf(1, "%s, %s\n", { get(m1, 1), get(m1, 2) })
    -- one hundred, two

    printf(1, "%s, %s\n", { get(m2, 1), get(m2, 2) })
    -- one, two

##### Example 2:

    map m1 = new()
    map m2 = new()

    put(m1, 1, "one")
    put(m1, 2, "two")
    put(m2, 3, "three")

    copy(m1, m2)

    ? keys(m2)
    -- { 1, 2, 3 }

##### Example 3:

    map m1 = new()
    map m2 = new()

    put(m1, "XY", 1)
    put(m1, "AB", 2)
    put(m2, "XY", 3)

    pairs(m1) --> { {"AB", 2}, {"XY", 1} }
    pairs(m2) --> { {"XY", 3} }

    -- Add same keys' values.
    copy(m1, m2, ADD)

    pairs(m2) --> { {"AB", 2}, {"XY", 4} }

##### See Also:

put

#### 8.33.3.33 new_from_kvpairs

    include std/map.e
    namespace map
    public function new_from_kvpairs(sequence kv_pairs)

converts a set of key:value pairs to a map.

##### Parameters:

1. `kv_pairs` : A seqeuence containing any number of subsequences that have the format {KEY, VALUE}. These are loaded into a new map which is then returned by this function.

##### Returns:

A map, containing the data from `kv_pairs`

##### Example 1:

    map m1 = new_from_kvpairs( {
        { "application", "Euphoria" },
        { "version", "4.0" },
        { "genre", "programming language" },
        { "crc", 0x4F71AE10 }
    })

    v = map:get(m1, "application") --> "Euphoria"

#### 8.33.3.34 new_from_string

    include std/map.e
    namespace map
    public function new_from_string(sequence kv_string)

converts a set of key:value pairs contained in a string to a map.

##### Parameters:

1. `kv_string` : A string containing any number of lines that have the format KEY=VALUE. These are loaded into a new map which is then returned by this function.

##### Returns:

A map, containing the data from `kv_string`

##### Comments:

This function actually calls `keyvalues` to convert the string to key-value pairs, which are then used to create the map.

##### Example 1:

Given that a file called "xyz.config" contains the lines ...

    application = Euphoria,
    version     = 4.0,
    genre       = "programming language",
    crc         = 4F71AE10

    map m1 = new_from_string( read_file("xyz.config", TEXT_MODE))

    printf(1, "%s\n", {map:get(m1, "application")}) --> "Euphoria"
    printf(1, "%s\n", {map:get(m1, "genre")})       --> "programming language"
    printf(1, "%s\n", {map:get(m1, "version")})     --> "4.0"
    printf(1, "%s\n", {map:get(m1, "crc")})         --> "4F71AE10"

#### 8.33.3.35 for_each

    include std/map.e
    namespace map
    public function for_each(map source_map, integer user_rid, object user_data = 0,
            integer in_sorted_order = 0, integer signal_boundary = 0)

calls a user-defined routine for each of the items in a map.

##### Parameters:

1. `source_map` : The map containing the data to process
2. `user_rid`: The routine_id of a user defined processing function
3. `user_data`: An object. Optional. This is passed, unchanged to each call of the user defined routine. By default, zero (0) is used.
4. `in_sorted_order`: An integer. Optional. If non-zero the items in the map are processed in ascending key sequence otherwise the order is undefined. By default they are not sorted.
5. `signal_boundary`: A integer; 0 (the default) means that the user routine is not called if the map is empty and when the last item is passed to the user routine, the Progress Code is not negative.

##### Returns:

An integer: 0 means that all the items were processed, and anything else is whatever was returned by the user routine to abort the `for_each` process.

##### Comments:

- The user defined routine is a function that must accept four parameters.
  1. Object: an Item Key
  2. Object: an Item Value
  3. Object: The `user_data` value. This is never used by `for_each` itself, merely passed to the user routine.
  4. Integer: Progress code.
     - The `abs` value of the progress code is the ordinal call number. That is 1 means the first call, 2 means the second call, etc ...
     - If the progress code is negative, it is also the last call to the routine.
     - If the progress code is zero, it means that the map is empty and thus the item key and value cannot be used.
     - note that if `signal_boundary` is zero, the Progress Code is never less than 1.
- The user routine must return 0 to get the next map item. Anything else will cause `for_each` to stop running, and is returned to whatever called `for_each`.
- Note that any changes that the user routine makes to the map do not affect the order or number of times the routine is called. `for_each` takes a copy of the map keys and data before the first call to the user routine and uses the copied data to call the user routine.

##### Example 1:

    include std/map.e
    include std/math.e
    include std/io.e

    function Process_A(object k, object v, object d, integer pc)
        writefln("[] = []", {k, v})
        return 0
    end function

    function Process_B(object k, object v, object d, integer pc)
        if pc = 0 then
          writefln("The map is empty")
        else
          integer c
          c = abs(pc)
          if c = 1 then
              writefln("---[]---", {d}) -- Write the report title.
          end if
          writefln("[]: [:15] = []", {c, k, v})
          if pc < 0 then
              writefln(repeat('-', length(d) + 6), {}) -- Write the report end.
          end if
        end if
        return 0
    end function

    map m1 = new()
    map:put(m1, "application", "Euphoria")
    map:put(m1, "version", "4.0")
    map:put(m1, "genre", "programming language")
    map:put(m1, "crc", "4F71AE10")

    -- Unsorted
    map:for_each(m1, routine_id("Process_A"))
    -- Sorted
    map:for_each(m1, routine_id("Process_B"), "List of Items", 1)

The output from the first call could be...

    application = Euphoria
    version = 4.0
    genre = programming language
    crc = 4F71AE10

The output from the second call should be...

    ---List of Items---
    1: application     = Euphoria
    2: crc             = 4F71AE10
    3: genre           = programming language
    4: version         = 4.0
    -------------------

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.32 Hashing Algorithms | Up: 8 API Reference | 8.34 Stack > | 9 Release Notes >>