readme

README.md

@@ -82,16 +82,19 @@ printf("port %d\n", port.u.i);
 4. Then, free up that memory if needed.
 
 ```c
-/* Use `toml_free` on the table returned from `toml_parse[_file]`. */
+/* Use `toml_free` on the table returned from `toml_parse[_file]`.
+ * NOTE: you only need to `toml_free` the root table returned by `toml_parse[_file]`;
+ * internal tables do not need to be freed.
+ */
 toml_free(conf);
 
 /* Free any string values returned from access functions. */
 free(host.u.s);
 ```
 
-### Accessing Table Content
+#### Accessing Table Content
 
-Tables are dictionaries where lookups are done using string keys. In
+TOML tables are dictionaries where lookups are done using string keys. In
 general, all access methods on tables are named `toml_*_in(...)`.
 
 Keys in tables can be iterrogated using a key index:
@@ -112,8 +115,45 @@ toml_bool_in(tab, key);
 toml_int_in(tab, key);
 toml_double_in(tab, key);
 toml_timestamp_in(tab, key);
+toml_table_in(tab, key);
+toml_array_in(tab, key);
 ```
 
+#### Accessing Array Content
+
+TOML arrays can be deref-ed using integer values. In general, all access methods on arrays are named `toml_*_at()`.
+
+To obtain the size of an array:
+```c
+int size = toml_array_nelem(arr);
+```
+
+To obtain the content of an array, use an valid index and call one of these functions:
+```c
+toml_string_at(arr, idx);
+toml_bool_at(arr, idx);
+toml_int_at(arr, idx);
+toml_double_at(arr, idx);
+toml_timestamp_at(arr, idx);
+toml_table_at(arr, idx);
+toml_array_at(arr, idx);
+```
+
+#### toml_access_t
+
+Some `toml_*_at` and `toml_*_in` functions return a toml_access_t
+structure. The `ok` flag in the structure indicates if the function
+call was successful. If so, you may proceed to read the value
+corresponding to the type of the call.
+
+For example:
+```
+toml_access_t host = toml_string_in(tab, "host");
+if (host.ok) {
+	printf("host: %s\n", host.u.s);
+	free(host.u.s);   /* FREE applies to string type only */
+}
+```
 
 ## Building