ucx: comparison docs/Writerside/topics/map.h.md

-:fc5e63b04281
+:aad755d296a7
 > If you want to lazy-initialize maps, you can use the global `cxEmptyMap` symbol as a placeholder instead of using a `NULL`-pointer.
 > While you *must not* insert elements into that map, you can safely access this map or create iterators.
 > This allows you to write clean code without checking for `NULL`-pointer everywhere.
 > You still need to make sure that the placeholder is replaced with an actual map before inserting elements.
-## Overview
+## Examples
-<warning>
+```C
-TODO: example
+#include <stdio.h>
-</warning>
+#include <cx/hash_map.h>
+int main() {
+CxMap *contacts = cxHashMapCreateSimple(CX_STORE_POINTERS);
+// Build a small phone book
+cxMapPut(contacts, "John", "123-0815");
+cxMapPut(contacts, "Jane", "987-4711");
+cxMapPut(contacts, "Michelle", "555-3141");
+cxMapPut(contacts, "Oliver", "000-9999");
+// Retrieve a phone number
+const char *janes_phone = cxMapGet(contacts, "Jane");
+printf("The number of Jane is: %s\n", janes_phone);
+// Update number
+cxMapPut(contacts, "Jane", "987-1337");
+// Remove and retrieve number
+cxMapRemoveAndGet(contacts, "Jane", &janes_phone);
+printf("The number of Jane was: %s\n", janes_phone);
+janes_phone = cxMapGet(contacts, "Jane");
+if (janes_phone == NULL) printf("Jane's number was deleted.\n");
+// Iterate through the contact list
+CxMapIterator iter = cxMapIterator(contacts);
+cx_foreach(CxMapEntry *, entry, iter) {
+cxstring name = cx_strn(entry->key->data, entry->key->len);
+const char *phone = entry->value;
+printf("%.*s: %s\n", (int) name.length, name.ptr, phone);
+}
+cxMapFree(contacts);
+return 0;
+}
+```
+The above example illustrates basic operations with a map.
+In the first part we add several entries to the map.
+Then the example shows retrieval, updating, and removal of information.
+The last part shows how to iterate over the pairs of the map and how to recover the string from the key.
+In real world situations, however, it is quite unlikely that you will use a map to store string literals.
+The next example shows a more realistic program, where it is necessary to store strings based on user input.
+```C
+#include <stdio.h>
+#include <string.h>
+#include <cx/hash_map.h>
+int main() {
+// store strings in the map...
+CxMap *contacts = cxHashMapCreateSimple(sizeof(cxmutstr));
+// ...which are automatically freed when removed
+cxDefineDestructor(contacts, cx_strfree);
+// build a small interactive program
+const unsigned buffer_size = 256;
+char input[buffer_size];
+bool running = true;
+while (running) {
+puts("\n*** Contacts - Menu ***");
+puts("1) Add entry");
+puts("2) Look up entry");
+puts("3) Remove entry");
+puts("4) Show all entries");
+puts("0) Exit");
+fputs("> ", stdout);
+if (fgets(input, buffer_size, stdin)) {
+if (input[1] != '\n') {
+puts("Please select a menu item.\n");
+} else if (input[0] == '1') {
+fputs("Name > ", stdout);
+if (fgets(input, buffer_size, stdin)) {
+// Copy the name (alternative: use 2nd input buf)
+cxmutstr name = cx_strdup(
+cx_strn(input, strcspn(input, "\n")));
+fputs("Phone > ", stdout);
+if (fgets(input, buffer_size, stdin)) {
+// add the entry, note that only the contents
+// of the cxmutstr are copied, not the string
+// data - therefore we have to call cx_strdup
+cxmutstr phone = cx_strdup(
+cx_strn(input, strcspn(input, "\n")));
+// note, that we can simply use the cxmutstr
+// for the name as key, because cxMapPut uses
+// generic selection
+cxMapPut(contacts, name, &phone);
+}
+cx_strfree(&name);
+}
+} else if (input[0] == '2') {
+fputs("Name > ", stdout);
+if (fgets(input, buffer_size, stdin)) {
+// Look up the name
+input[strcspn(input, "\n")] = '\0';
+cxmutstr *phone = cxMapGet(contacts, input);
+if (phone == NULL) {
+puts("No record.");
+} else {
+printf("Result: %.*s\n",
+(int) phone->length, phone->ptr);
+}
+}
+} else if (input[0] == '3') {
+fputs("Name > ", stdout);
+if (fgets(input, buffer_size, stdin)) {
+// Remove the entry
+// Since we registered cx_strfree as destructor,
+// the memory is automatically freed
+input[strcspn(input, "\n")] = '\0';
+if (cxMapRemove(contacts, input)) {
+puts("No such record.");
+} else {
+puts("Removed.");
+}
+}
+} else if (input[0] == '4') {
+// Almost the same iteration loop as above ...
+CxMapIterator iter = cxMapIterator(contacts);
+cx_foreach(CxMapEntry *, entry, iter) {
+cxstring name = cx_strn(entry->key->data,
+entry->key->len);
+// ... except that here we get cxmutstr*
+cxmutstr *phone = entry->value;
+printf("%.*s: %.*s\n",
+(int) name.length, name.ptr,
+(int) phone->length, phone->ptr);
+}
+} else if (input[0] == '0') {
+running = false;
+} else {
+puts("Please select a menu item.\n");
+}
+} else {
+running = false;
+}
+}
+// this will free all remaining strings that are in the map
+cxMapFree(contacts);
+return 0;
+}
+```
 > In the following Sections, the type for the key is denoted `KeyType`.
 > All functions are implemented as generics, so that the following types are supported:
 > `CxHashKey`, `cxstring`, `cxmutstr`, `const char*`, and `char*`.
 > {style="note"}

Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/map.h.md

docs/Writerside/topics/map.h.md