Added new constructors to carray.h. Made cmap and csmap keys immutable. Added get() method to cmap and csmap.

5 files changed, 60 insertions, 54 deletions

diff --git a/docs/carray_api.md b/docs/carray_api.md
index 3fbd8c37..51688fd3 100644
--- a/docs/carray_api.md
+++ b/docs/carray_api.md
@@ -28,14 +28,15 @@ be replaced by `i` in all of the following documentation.
 ## Methods
 
 ```c
-carray2X            carray2X_init(size_t xdim, size_t ydim, Value val);
-carray2X            carray2X_from(Value* array, size_t xdim, size_t ydim);
+carray2X            carray2X_init(size_t xdim, size_t ydim);
+carray2X            carray2X_with_value(size_t xdim, size_t ydim, Value val);
+carray2X            carray2X_with_storage(size_t xdim, size_t ydim, Value* array);
 carray2X            carray2X_clone(carray2X arr);
-Value*              carray2X_release(carray2X* self);       // give away data
+Value*              carray2X_release(carray2X* self);       // release storage (not freed)
 void                carray2X_del(carray2X* self);
 
 size_t              carray2X_size(carray2X arr);
-Value*              carray2X_data(carray2X* self);          // contiguous memory
+Value*              carray2X_data(carray2X* self);          // access storage data
 Value*              carray2X_at(carray2X* self, size_t x, size_t y);
 
 carray2X_iter_t     carray2X_begin(const carray2X* self);
@@ -43,14 +44,15 @@ carray2X_iter_t     carray2X_end(const carray2X* self);
 void                carray2X_next(carray2X_iter_t* it);
 ```
 ```c
-carray3X            carray3X_init(size_t xdim, size_t ydim, size_t zdim, Value val);
-carray3X            carray3X_from(Value* array, size_t xdim, size_t ydim, size_t zdim);
+carray3X            carray3X_init(size_t xdim, size_t ydim, size_t zdim);
+carray3X            carray3X_with_value(size_t xdim, size_t ydim, size_t zdim, Value val);
+carray3X            carray3X_with_storage(size_t xdim, size_t ydim, size_t zdim, Value* array);
 carray3X            carray3X_clone(carray3X arr);
-Value*              carray3X_release(carray3X* self);       // give away data
+Value*              carray3X_release(carray3X* self);       // release storage (not freed)
 void                carray3X_del(carray3X* self);
 
 size_t              carray3X_size(carray3X arr);
-Value*              carray3X_data(carray3X* self);          // contiguous memory
+Value*              carray3X_data(carray3X* self);          // access storage data
 Value*              carray3X_at(carray3X* self, size_t x, size_t y, size_t z);
 
 carray3X_iter_t     carray3X_begin(const carray3X* self);
@@ -59,14 +61,14 @@ void                carray3X_next(carray3X_iter_t* it);
 ```
 ## Types
 
-| Type name            | Type definition                                    | Used to represent...      |
-|:---------------------|:---------------------------------------------------|:--------------------------|
-| `carray2X`           | `struct { Value **data; size_t xdim,ydim; }`       | The carray2 type          |
-| `carray2X_value_t`   | `Value`                                            | The value type            |
-| `carray2X_iter_t`    | `struct { Value *ref; }`                           | Iterator type             |
-| `carray3X`           | `struct { Value ***data; size_t xdim,ydim,zdim; }` | The carray3 type          |
-| `carray3X_value_t`   | `Value`                                            | The value type            |
-| `carray3X_iter_t`    | `struct { Value *ref; }`                           | Iterator type             |
+| Type name            | Type definition                                      | Used to represent...      |
+|:---------------------|:-----------------------------------------------------|:--------------------------|
+| `carray2X`           | `struct { Value **data; size_t xdim, ydim; }`        | The carray2 type          |
+| `carray2X_value_t`   | `Value`                                              | The value type            |
+| `carray2X_iter_t`    | `struct { Value *ref; }`                             | Iterator type             |
+| `carray3X`           | `struct { Value ***data; size_t xdim, ydim, zdim; }` | The carray3 type          |
+| `carray3X_value_t`   | `Value`                                              | The value type            |
+| `carray3X_iter_t`    | `struct { Value *ref; }`                             | Iterator type             |
 
 The **carray** elements can be accessed like `carray3i arr = ...; int val = arr.data[x][y][z];`, or with `carray3i_at(&arr, x, y, z)`.
 
@@ -82,20 +84,20 @@ int main()
 {
     // Ex1
     int xd = 30, yd = 20, zd = 10;
-    carray3f a3 = carray3f_init(xd, yd, zd, 0.0f);  // define a3[30][20][10], init with 0.0f.
-    a3.data[5][4][3] = 3.14f;
+    carray3f arr3 = carray3f_init(xd, yd, zd, 0.0f);  // define arr3[30][20][10], init with 0.0f.
+    arr3.data[5][4][3] = 3.14f;
 
-    float *a1 = a3.data[5][4];
-    float **a2 = a3.data[5];
+    float *arr1 = arr3.data[5][4];
+    float **arr2 = arr3.data[5];
 
-    printf("%f\n", a1[3]); // 3.14
-    printf("%f\n", a2[4][3]); // 3.14
-    printf("%f\n", a3.data[5][4][3]); // 3.14
-    carray3f_del(&a3); // free array
+    printf("%f\n", arr1[3]); // 3.14
+    printf("%f\n", arr2[4][3]); // 3.14
+    printf("%f\n", arr3.data[5][4][3]); // 3.14
+    carray3f_del(&arr3); // free array
 
     // Ex2
     int w = 256, h = 128;
-    carray2i image = carray2i_from(c_new_n(uint32_t, w*h), w, h); // no value init
+    carray2i image = carray2i_init(w, h);
     int n = 0;
     c_foreach (i, carray2i, image) {
         uint32_t t = n++ % 256;
diff --git a/docs/cmap_api.md b/docs/cmap_api.md
index 78aecfa9..8d12288c 100644
--- a/docs/cmap_api.md
+++ b/docs/cmap_api.md
@@ -62,9 +62,10 @@ size_t              cmap_X_size(cmap_X map);
 size_t              cmap_X_capacity(cmap_X map);                                             // buckets * max_load_factor
 size_t              cmap_X_bucket_count(cmap_X map);                                         // num. of allocated buckets
 
-cmap_X_iter_t       cmap_X_find(const cmap_X* self, RawKey rkey);
 bool                cmap_X_contains(const cmap_X* self, RawKey rkey);
 cmap_X_mapped_t*    cmap_X_at(const cmap_X* self, RawKey rkey);                              // rkey must be in map.
+cmap_X_value_t*     cmap_X_get(const cmap_X* self, RawKey rkey);                             // return NULL if not found
+cmap_X_iter_t       cmap_X_find(const cmap_X* self, RawKey rkey);
 
 cmap_X_result_t     cmap_X_insert(cmap_X* self, Key key, Mapped mapped);                     // no change if key in map
 cmap_X_result_t     cmap_X_insert_or_assign(cmap_X* self, Key key, Mapped mapped);           // always update mapped
@@ -106,7 +107,7 @@ void                c_trivial_del(Type* val);                             // doe
 | `cmap_X_rawvalue_t`  | `struct { RawKey first; RawMapped second; }`    | RawKey + RawMapped type       |
 | `cmap_X_key_t`       | `Key`                                           | The key type                  |
 | `cmap_X_mapped_t`    | `Mapped`                                        | The mapped type               |
-| `cmap_X_value_t`     | `struct { Key first; Mapped second; }`          | The value type                |
+| `cmap_X_value_t`     | `struct { const Key first; Mapped second; }`    | The value: key is immutable   |
 | `cmap_X_result_t`    | `struct { cmap_X_value_t *ref; bool inserted; }`| Result of insert/put/emplace  |
 | `cmap_X_iter_t`      | `struct { cmap_X_value_t *ref; ... }`           | Iterator type                 |
 
diff --git a/docs/cset_api.md b/docs/cset_api.md
index a1265ee8..be083b75 100644
--- a/docs/cset_api.md
+++ b/docs/cset_api.md
@@ -39,8 +39,9 @@ size_t              cset_X_size(cset_X set);
 size_t              cset_X_capacity(cset_X set);                                             // buckets * max_load_factor

 size_t              cset_X_bucket_count(cset_X set);

 

-cset_X_iter_t       cset_X_find(const cset_X* self, RawKey rkey);

 bool                cset_X_contains(const cset_X* self, RawKey rkey);

+cset_X_value_t*     cset_X_get(const cset_X* self, RawKey rkey);                             // return NULL if not found

+cset_X_iter_t       cset_X_find(const cset_X* self, RawKey rkey);

 

 cset_X_result_t     cset_X_insert(cset_X* self, Key key);

 cset_X_result_t     cset_X_emplace(cset_X* self, RawKey rkey);

@@ -59,15 +60,15 @@ cset_X_value_t      cset_X_value_clone(cset_X_value_t val);
 

 ## Types

 

-| Type name            | Type definition                                  | Used to represent...     |

-|:---------------------|:-------------------------------------------------|:-------------------------|

-| `cset_X`             | `struct { ... }`                                 | The cset type            |

-| `cset_X_rawkey_t`    | `RawKey`                                         | The raw key type         |

-| `cset_X_rawvalue_t`  | `cset_X_rawkey_t`                                | The raw key type         |

-| `cset_X_key_t`       | `Key`                                            | The key type             |

-| `cset_X_value_t`     | `cset_X_key_t`                                   | The value type           |

-| `cset_X_result_t`    | `struct { cset_X_value_t* ref; bool inserted; }` | Result of insert/emplace |

-| `cset_X_iter_t`      | `struct { cset_X_value_t *ref; ... }`            | Iterator type            |

+| Type name            | Type definition                                  | Used to represent...        |

+|:---------------------|:-------------------------------------------------|:----------------------------|

+| `cset_X`             | `struct { ... }`                                 | The cset type               |

+| `cset_X_rawkey_t`    | `RawKey`                                         | The raw key type            |

+| `cset_X_rawvalue_t`  | `RawKey`                                         | The raw value type          |

+| `cset_X_key_t`       | `Key`                                            | The key type                |

+| `cset_X_value_t`     | `const Key`                                      | The value: key is immutable |

+| `cset_X_result_t`    | `struct { cset_X_value_t* ref; bool inserted; }` | Result of insert/emplace    |

+| `cset_X_iter_t`      | `struct { cset_X_value_t *ref; ... }`            | Iterator type               |

 

 ## Example

 ```c

diff --git a/docs/csmap_api.md b/docs/csmap_api.md
index 5717c287..ba9a2978 100644
--- a/docs/csmap_api.md
+++ b/docs/csmap_api.md
@@ -54,11 +54,12 @@ void                csmap_X_del(csmap_X* self);
 bool                csmap_X_empty(csmap_X map);
 size_t              csmap_X_size(csmap_X map);
 
-csmap_X_iter_t      csmap_X_find(const csmap_X* self, RawKey rkey);
-csmap_X_iter_t      csmap_X_lower_bound(const csmap_X* self, RawKey rkey);                      // find closest entry >= rkey
 bool                csmap_X_contains(const csmap_X* self, RawKey rkey);
-csmap_X_value_t*    csmap_X_find_it(const csmap_X* self, RawKey rkey, csmap_X_iter_t* out);     // return NULL if not found
 csmap_X_mapped_t*   csmap_X_at(const csmap_X* self, RawKey rkey);                               // rkey must be in map.
+csmap_X_value_t*    csmap_X_get(const csmap_X* self, RawKey rkey);                              // return NULL if not found
+csmap_X_iter_t      csmap_X_lower_bound(const csmap_X* self, RawKey rkey);                      // find closest entry >= rkey
+csmap_X_iter_t      csmap_X_find(const csmap_X* self, RawKey rkey);
+csmap_X_value_t*    csmap_X_find_it(const csmap_X* self, RawKey rkey, csmap_X_iter_t* out);     // return NULL if not found
 
 csmap_X_result_t    csmap_X_insert(csmap_X* self, Key key, Mapped mapped);                      // no change if key in map
 csmap_X_result_t    csmap_X_insert_or_assign(csmap_X* self, Key key, Mapped mapped);            // always update mapped
@@ -85,10 +86,10 @@ csmap_X_value_t     csmap_X_value_clone(csmap_X_value_t val);
 | `csmap_X`             | `struct { ... }`                                  | The csmap type               |
 | `csmap_X_rawkey_t`    | `RawKey`                                          | The raw key type             |
 | `csmap_X_rawmapped_t` | `RawMapped`                                       | The raw mapped type          |
-| `csmap_X_rawvalue_t`  | `struct { RawKey first; RawMapped second; }`      | RawKey + RawVal type         |
+| `csmap_X_rawvalue_t`  | `struct { RawKey first; RawMapped second; }`      | RawKey+RawMapped type        |
 | `csmap_X_key_t`       | `Key`                                             | The key type                 |
 | `csmap_X_mapped_t`    | `Mapped`                                          | The mapped type              |
-| `csmap_X_value_t`     | `struct { Key first; Mapped second; }`            | The value type               |
+| `csmap_X_value_t`     | `struct { const Key first; Mapped second; }`      | The value: key is immutable  |
 | `csmap_X_result_t`    | `struct { csmap_X_value_t *ref; bool inserted; }` | Result of insert/put/emplace |
 | `csmap_X_iter_t`      | `struct { csmap_X_value_t *ref; ... }`            | Iterator type                |
 
diff --git a/docs/csset_api.md b/docs/csset_api.md
index 500e38e4..3e8f1aff 100644
--- a/docs/csset_api.md
+++ b/docs/csset_api.md
@@ -34,10 +34,11 @@ void                csset_X_del(csset_X* self);
 bool                csset_X_empty(csset_X set);

 size_t              csset_X_size(csset_X set);

 

-csset_X_iter_t      csset_X_find(const csset_X* self, RawKey rkey);

-csset_X_iter_t      csset_X_lower_bound(const csset_X* self, RawKey rkey);                      // find closest entry >= rkey

-csset_X_value_t*    csset_X_find_it(const csset_X* self, RawKey rkey, csset_X_iter_t* out);

 bool                csset_X_contains(const csset_X* self, RawKey rkey);

+csset_X_value_t*    csset_X_get(const csset_X* self, RawKey rkey);                              // return NULL if not found

+csset_X_iter_t      csset_X_lower_bound(const csset_X* self, RawKey rkey);                      // find closest entry >= rkey

+csset_X_iter_t      csset_X_find(const csset_X* self, RawKey rkey);

+csset_X_value_t*    csset_X_find_it(const csset_X* self, RawKey rkey, csset_X_iter_t* out);     // return NULL if not found

 

 csset_X_result_t    csset_X_insert(csset_X* self, Key key);

 csset_X_result_t    csset_X_emplace(csset_X* self, RawKey rkey);

@@ -56,15 +57,15 @@ csset_X_value_t     csset_X_value_clone(csset_X_value_t val);
 

 ## Types

 

-| Type name            | Type definition                                   | Used to represent...     |

-|:---------------------|:--------------------------------------------------|:-------------------------|

-| `csset_X`            | `struct { ... }`                                  | The csset type           |

-| `csset_X_rawkey_t`   | `RawKey`                                          | The raw key type         |

-| `csset_X_rawvalue_t` | `csset_X_rawkey_t`                                | The raw key type         |

-| `csset_X_key_t`      | `Key`                                             | The key type             |

-| `csset_X_value_t`    | `csset_X_key_t`                                   | The value type           |

-| `csset_X_result_t`   | `struct { csset_X_value_t* ref; bool inserted; }` | Result of insert/emplace |

-| `csset_X_iter_t`     | `struct { csset_X_value_t *ref; ... }`            | Iterator type            |

+| Type name            | Type definition                                   | Used to represent...        |

+|:---------------------|:--------------------------------------------------|:----------------------------|

+| `csset_X`            | `struct { ... }`                                  | The csset type              |

+| `csset_X_rawkey_t`   | `RawKey`                                          | The raw key type            |

+| `csset_X_rawvalue_t` | `csset_X_rawkey_t`                                | The raw key type            |

+| `csset_X_key_t`      | `Key`                                             | The key type                |

+| `csset_X_value_t`    | `const Key`                                       | The value: key is immutable |

+| `csset_X_result_t`   | `struct { csset_X_value_t* ref; bool inserted; }` | Result of insert/emplace    |

+| `csset_X_iter_t`     | `struct { csset_X_value_t *ref; ... }`            | Iterator type               |

 

 ## Example

 ```c