Added String type documentation

docs/README.md

@@ -7,4 +7,5 @@ At the time being, this documentation includes the following pages:
 
 - [vector.md](vector.md): vector documentation;  
 - [map.md](map.md): map documentation;   
-- [bigint.md](bigint.md): bigint documentation.
+- [bigint.md](bigint.md): bigint documentation;  
+- [string.md](string.md): string documentation.

docs/bigint.md

@@ -80,8 +80,6 @@ Each method that returns such type indicates whether the operation was successfu
 by setting the `status` field and by providing a descriptive message on the `message`
 field. If the operation was successful (that is, `status == BIGINT_OK`), you can either
 move on with the rest of the program or read the returned value from the sum data type.
-Of course, you can choose to ignore the return value (if you're brave enough :D) as 
-illustrated on the first part of the README.
 
 The sum data type (i.e., the `value` union) defines four different variables. Each
 of them has an unique scope as described below:

docs/map.md

@@ -72,5 +72,4 @@ typedef struct {
 Each method that returns such type indicates whether the operation was successful or not by setting
 the `status` field and by providing a descriptive message on the `message` field. If the operation was
 successful (that is, `status == MAP_OK`), you can either move on with the rest of the program or read
-the returned value from the sum data type. Of course, you can choose to ignore the return value (if you're brave enough :D) as illustrated
-on the first part of the README.
+the returned value from the sum data type.

docs/string.md

@@ -0,0 +1,85 @@
+# String Technical Details
+In this document you can find a quick overview of the technical aspects (internal design, memory layout, etc.) of the `String` data structure.
+
+`String` is an immutable, null-terminated string data type with partial UTF-8 support.
+This means that methods return a new string instance rather than modifying the string in-place.
+Internally, this data structure is represented by the following layout:
+
+```c
+typedef struct {
+    char *data;
+    size_t byte_size;
+    size_t byte_capacity;
+    size_t char_count;
+} string_t;
+```
+
+where the `data` field represent the actual string, `byte_size`
+indicates the actual size (in bytes), `byte_capacity` represents the total number
+of allocated memory (in bytes) and `char_count` represents the number of symbols.
+
+As mentioned earlier, this data type provides partial UTF-8 support. It is able
+to recognize UTF-8 byte sequences as individual Unicode code points and has
+full support for Unicode symbols such as emojis. However, it does not support
+localization. In particular, it does not perform local-aware conversions. For instance, uppercase/lowercase transformations are limited to ASCII characters only. As a result, the German scharfes S (`ß`) is not convert to `SS`, the Spanish `Ñ` is not converted to `ñ` and the Italian `é` (and its variants) is not treated as a single symbol but rather as a base letter combined with an accent. 
+
+At the time being, `String` supports the following methods:
+
+- `string_result_t string_new(c_str)`: create a new string;
+- `string_result_t string_clone(str)`: clone an existing string;
+- `string_result_t string_concat(x, y)`: concatenate two strings together;
+- `string_result_t string_contains(haystack, needle)`: search whether the `haystack` string contains `needle`;
+- `string_result_t string_slice(str, start, end)`: return a slice (a new string) from `str` between `start` and `end` indices (inclusive);
+- `string_result_t string_eq(x, y, case_sensitive)`: check whether `x` and `y` are equal;
+- `string_result_t string_get_at(str, position)`: get the UTF-8 symbol indexed by `position` from `str`;
+- `string_result_t string_set_at(str, position, utf8_char)`: write a UTF-8 symbol into `str` at index `position`;
+- `string_result_t string_to_lower(str)`: convert a string to lowercase;
+- `string_result_t string_to_upper(str)`: convert a string to uppercase;
+- `string_result_t string_reverse(str)`: reverse a string;
+- `string_result_t string_trim(str)`: remove leading and trailing white space from a string;
+- `string_result_t string_split(str, delim)`: split a string into an array of `string_t` by specifying a separator;
+- `string_result_t string_destroy(str)`: remove a string from memory;
+- `string_result_t string_split_destroy(split, count)`: remove an array of strings from memory;
+- `size_t string_size(str)`: return string character count.
+
+As you can see from the previous function signatures, most methods that operate on the `String`
+data type return a custom type called `string_result_t` which is defined as follows:
+
+```c
+typedef enum {
+    STRING_OK = 0x0,
+    STRING_ERR_ALLOCATE,
+    STRING_ERR_INVALID,
+    STRING_ERR_INVALID_UTF8,
+    STRING_ERR_OVERFLOW
+} string_status_t;
+
+typedef struct {
+    string_status_t status;
+    uint8_t message[RESULT_MSG_SIZE];
+    union {
+        string_t *string;
+        char *symbol;
+        int64_t idx;
+        bool is_equ;
+        struct {
+            string_t **strings;
+            size_t count;
+        } split;
+    } value;
+} string_result_t;
+```
+
+Each method that returns such type indicates whether the operation was successful or not
+by setting the `status` field and by providing a descriptive message on the `message`
+field. If the operation was successful (that is, `status == STRING_OK`) you can either
+move on with the rest of your program or read the returned value from the sum data type.
+
+The sum data type (i.e., the `value` union) defines five different variables.
+Each of them has an unique scope as described below:
+
+- `string`: result of `new`, `clone`, `slice`, `reverse` and `trim` functions;
+- `symbol`: result of `get_at` function;
+- `idx`: result of `contains` function;
+- `is_eq`: result of `equ` function. It's true when two strings are equal, false otherwise;
+- `split`: result of `split` function. It contains an array of `string_t` and its number of elements.

docs/vector.md

@@ -65,8 +65,7 @@ typedef struct {
 Each method that returns such type indicates whether the operation was successful or not
 by setting the `status` field and by providing a descriptive message on the `message`
 field. If the operation was successful (that is, `status == VECTOR_OK`), you can either
-move on with the rest of the program or read the returned value from the sum data type. Of course, you can choose to 
-ignore the return value (if you're brave enough :D) as illustrated on the first part of the README.
+move on with the rest of the program or read the returned value from the sum data type.
 
 ## Functional methods
 `Vector` provides three functional methods called `map`, `filter` and `reduce` which allow the caller to apply a computation to the vector,