better description

README.md

@@ -1,12 +1,12 @@
 # String to Number (s2n)
-A single header library for string manipulation/hashing/encryption.  
+A single header `constexpr` `template` interface which could be used with other libraries for C-string manipulation/hashing/encryption at compile-time.  
 
 ## Features:
 * Single header file (`.hpp`) which could be included in any project
 * Zero dependency, no other headers are included, even from the standard ones
-* Compile-time library, all functions are marked `constexpr`
-* Provides a generic (`template`) interface to allow integration with different string manipulation/encryption implementations
-* Supports language versions `C++14` and above
+* Compile-time, all functions are marked `constexpr`
+* Provides a generic (`template`) interface to allow integration with different string manipulation libraries
+* Supports language version `C++14` and above
 * Compare the encrypted data with the natural `==` operator
 
 ## Use cases:
@@ -16,21 +16,22 @@ A single header library for string manipulation/hashing/encryption.
   ![hover image](./assets/hover.png)  
   ![hover image 2](./assets/hover2.png)  
 
+## Built-in converters/manipulators
+* `s2n_cvt::xor_cvt`: simple XOR converter
+* `s2n_cvt::crc32`: CRC-32 hash calculator
+* `s2n_cvt::hash_fnv_1a_64`: Fowler–Noll–Vo hash calculator (FNV-1a hash variant with parameters adjusted for 64-bits)
+
 ## Quick usage example:
 ```c++
-// this is the only file you need to include
-
 // the library depends on the standard macro __cplusplus
 // but you can override it with the macro "S2N_CPP_VERSION" which is optional
 // when used, it must be set to the actual C++ language version used by the compiler
 
 //#define S2N_CPP_VERSION 201402L
-#include "str-to-num.hpp"
+#include "str-to-num.hpp" // this is the only file you need to include
 
-// std::cout
-#include <iostream>
-// size_t
-#include <cstddef>
+#include <iostream> // std::cout
+#include <cstddef> // size_t
 
 // compare the decrypted strings (using plain C-style arrays)
 template<typename Ta, typename Tb, size_t N>
@@ -43,7 +44,7 @@ constexpr bool same_str_data(const Ta (&str_a) [N], const Tb (&str_b) [N]) {
   return true;
 }
 
-// compare the decrypted strings (using the returned string container instance)
+// compare the decrypted strings (using the returned string container instance from the library)
 template<typename Ta, typename Tb>
 constexpr bool same_str_data(const Ta &str_a, const Tb &str_b) {
   if (str_a.count != str_b.count) {
@@ -100,6 +101,17 @@ When the encrypted/manipulated data is changed back to a string, the returned ob
 3. `void clear()`: a function to clear the data buffer manually after usage, ensuring it is not still available on the stack.  
    For `C++20` and above, a `constexpr` destructor is automatically invoked when the decrypted string goes out of scope
 
+## Notes
+* Static arrays in C/C++ cannot have a size of 0
+  ```c++
+  char my_array[0]; // compiler error
+  ```
+  But many hashing algorithms support empty strings (`""`), to workaround this problem the library creates a 1-element array whose value is null `'\0'`  
+
+* Microsoft's compiler doesn't set the proper value for the standard macro `__cplusplus`, you have to add this `/Zc:__cplusplus` to the compiler flags, more info: https://learn.microsoft.com/en-us/cpp/build/reference/zc-cplusplus
+* Starting from `C++17` the exception specification for a function (`noexcept`) is a mandatory part for `typedef` statements, and the library takes care of that automatically.  
+But if for example you set the macro `S2N_CPP_VERSION` to `201402L` (`C++14`) while the compiler was targeting language version `C++17` or above, this will result in an error since the library would be looking for the function `to_num()` **WITHOUT** `noexcept` specification, which would fail on `C++17` or above.  
+Always rely on the standard macro `__cplusplus`, otherwise set the macro `S2N_CPP_VERSION` carefully.
 
 ## Adding your custom converter
 ### Mandatory **string-to-number** conversion function
@@ -132,9 +144,20 @@ When the encrypted/manipulated data is changed back to a string, the returned ob
       const TStr& src
       ```
 
-   Check the built-in converters `s2n_cvt::xor_cvt` and `s2n_cvt::hash_fnv_1a_64` for an actual example
+Examples:  
+Return a C-style array `TChar (&dst) [StrCount]` containing the encrypted data
+```c++
+template<typename TStr, s2n_sz_t StrCount, typename TChar>
+constexpr static void to_num(TChar (&dst) [StrCount], const TStr& src) noexcept;
+```
+Return the hash of the input string as `unsigned int`
+```c++
+template<typename TStr, s2n_sz_t StrCount, typename TChar>
+constexpr static void to_num(unsigned int &crc, const TStr& src) noexcept;
+```
+Check the built-in converters `s2n_cvt::xor_cvt` and `s2n_cvt::hash_fnv_1a_64` for an actual example
 
-### Optional **number-to-string** conversion function (if your converter supports recovering back the original string)
+### Optional **number-to-string** conversion function (if your converter supports restoring back the original string)
 * Provide a function called `to_str`, which must satisfy the following:
    - Defined as `constexpr`
    - Have a `static` storage specifier
@@ -152,28 +175,17 @@ When the encrypted/manipulated data is changed back to a string, the returned ob
      ```c++
      TChar (&dst) [StrCount + 1]
      ```
-     This is the destination buffer, allocated by the library, you have to fill with the unencrypted characters/items. It's size is more than the original string by 1 for the null terminator, you don't have to write the null terminator, it is done automatically by the library
+     This is the destination buffer allocated by the library, you have to fill it with the unencrypted characters/items. It's size is more than the original string by 1 for the null terminator, you don't have to write the null terminator, it is done automatically for you
     - The second function parameter must be
       ```c++
       const TChar (&src) [StrCount]
       ```
       Which is a reference to the encrypted string
 
-   Check the built-in converter `s2n_cvt::xor_cvt` for an actual example
-
-## Notes
-* Static arrays in C/C++ cannot have a 0 size
-  ```c++
-  char my_array[0]; // compiler error
-  ```
-  But many hashing algorithms support empty strings (`""`), to workaround this problem the library creates a 1-element array whose value is null `'\0'`  
-
-* Microsoft's compiler doesn't set the proper value for the standard macro `__cplusplus`, you have to add this `/Zc:__cplusplus` to the compiler flags, more info: https://learn.microsoft.com/en-us/cpp/build/reference/zc-cplusplus
-* Starting from `C++17` the exception specification for a function (`noexcept`) is a mandatory part for `typedef` statements, and the library takes care of that automatically.  
-But if for example you set the macro `S2N_CPP_VERSION` to `201402L` (`C++14`) while the compiler was targeting language version `C++17` or above, this will result in an error since the library would be looking for the function `to_num()` **WITHOUT** `noexcept` specification, which would fail on `C++17` or above.  
-Always rely on the standard macro `__cplusplus`, otherwise set the macro `S2N_CPP_VERSION` carefully.
-
-## Built-in converters
-* `s2n_cvt::xor_cvt`: simple XOR converter
-* `s2n_cvt::crc32`: CRC-32 hash calculator
-* `s2n_cvt::hash_fnv_1a_64`: Fowler–Noll–Vo hash calculator (FNV-1a hash variant with parameters adjusted for 64-bits)
+Examples:  
+Resore the original string and save it in a C-style array `TChar (&dst) [StrCount + 1]`
+```c++
+template<typename TStr, s2n_sz_t StrCount, typename TChar>
+constexpr static void to_str(TChar (&dst) [StrCount + 1], const TChar (&src) [StrCount]) noexcept;
+```
+Check the built-in converter `s2n_cvt::xor_cvt` for an actual example