Introduce initial documentation (#13)

Singed-off-by: Daniil Dudkin <umarmungenfuerimmer@gmail.com>
Co-authored-by: Alexander Yurev <sapfir999999@yandex.ru>
Singed-off-by: Alexander Yurev <sapfir999999@yandex.ru>

.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/about.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# About
+
+This library provides `basic_fixed_string` class template to enable fixed-size `std::array` semantic with standard-like string semantic.
+
+## Features
+
+* C++17 or higher
+* Header-only
+* Dependency-free
+
+:::caution Warning
+Dependencies can be added later to enable lower C++ standards support.
+:::
+
+* No dynamic allocations
+* `constexpr` as much as possible
+* Can be used as class non-type template parameter *(since C++20)*
+
+## Possible usages
+
+* ## Make your own eDSL with C++20's class non-type template parameter feature
+
+[CTRE library](https://github.com/hanickadot/compile-time-regular-expressions) uses similar class to make regular expressions in C++ more easy to use:
+```cpp
+std::optional<std::string_view> extract_number(std::string_view s) noexcept {
+    if (auto m = ctre::match<"[a-z]+([0-9]+)">(s)) {
+        return m.get<1>().to_view();
+    } else {
+        return std::nullopt;
+    }
+}
+```
+
+* ## Make more concise APIs
+
+For example, before `fixed_string` if you needed to implement MD5 hash function, you'd write something like this:
+```cpp
+std::string hash_md5(std::string_view string);
+```
+This solution has 2 downsides: 
+* it can allocate
+* it can return a string that is not 16 bytes
+
+With `fixed_string` these 2 problems are solved:
+```cpp
+fixstr::fixed_string<16> hash_md5(std::string_view string);
+```
+
+* ## Use in a free-standing environment
+
+Returning to the example with the hash function: the implementation with `std::string` as the return type has one more downside which is a consequence of possible allocations - it cannot be used in free-standing environments where is no dynamic memory.
+
+## Examples
+
+* Construction
+```cpp
+constexpr fixstr::fixed_string foo = "foo";
+```
+
+* Concatenation
+```cpp
+using namespace fixstr;
+constexpr fixed_string first = "Hello, ";
+constexpr fixed_string second = "World!";
+constexpr auto result = first + second; // "Hello, World!"
+```
+
+* Comparison
+```cpp
+using namespace fixstr;
+constexpr fixed_string first = "Hello, ";
+constexpr fixed_string second = "World!";
+static_assert(first == second); // false
+static_assert(first != second); // true
+static_assert(first < second);  // true
+static_assert(first <= second); // true
+static_assert(first > second);  // false 
+static_assert(first >= second); // false
+static_assert(first <=> second != 0); // true
+```
+
+* Non-type template parameter
+```cpp
+template <fixstr::fixed_string Foo>
+void bar()
+{
+    static_assert(Foo == "foo"sv);
+}
+
+void foo()
+{
+    bar<"foo">();
+}
+```
+
+## Integration
+Since it's a header only library, you need just copy `fixed_string.hpp` to your project.
+
+If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can use the [**fixed-string** package](https://github.com/microsoft/vcpkg/tree/master/ports/fixed-string).
+
+If you are using Conan on your project for external dependencies, then you can use the Conan recipe located in the root of the repository.
+
+## Compiler compatibility
+* GCC >= 7.3
+* Clang >= 5
+* ICC >= 19.0.1
+* MSVC >= 14.28 / Visual Studio 2019 (I don't have access to older VS versions right now, so it can work on older versions too)
+
+**Using `basic_fixed_string` as class non-type template parameter full available in GCC >= 10 and VS 2019 16.9 or newer**

docs/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API Reference",
+  "position": 2
+}

docs/api/basic_fixed_string.md

@@ -0,0 +1,100 @@
+---
+sidebar_position: 1
+sidebar_label: basic_fixed_string
+---
+
+# Class template `basic_fixed_string`
+
+##### Defined in header [`<fixed_string.hpp>`](https://github.com/unterumarmung/fixed_string/blob/master/include/fixed_string.hpp)
+
+```cpp
+template<
+    typename TChar, 
+    std::size_t N, 
+    typename TTraits = std::char_traits<TChar>
+> struct basic_fixed_string;
+```
+
+The class template `basic_fixed_string` describes objects that can store a sequence consisting of a fixed number of arbitrary `char`-like objects with the first element of the sequence at position zero. 
+
+Several typedefs for common character types are provided:
+
+| Type                         | Definition                                |               |
+| ---------------------------- | ----------------------------------------- | ------------- |
+| `fixstr::fixed_string<N>`    | `fixstr::basic_fixed_string<char, N>`     |               |
+| `fixstr::fixed_u8string<N>`  | `fixstr::basic_fixed_string<char8_t, N>`  | *since C++20* |
+| `fixstr::fixed_u16string<N>` | `fixstr::basic_fixed_string<char16_t, N>` |               |
+| `fixstr::fixed_u32string<N>` | `fixstr::basic_fixed_string<char32_t, N>` |               |
+| `fixstr::fixed_wstring<N>`   | `fixstr::basic_fixed_string<wchar_t, N>`  |               |
+
+:::info NOTE
+In actual implementation, these are not the type aliases. Unfortunately, early GCC versions that are supported cNTTP couldn't automatically deduct `size_t` template parameter when an alias was used in cNTTP. So, the actual implementation is that every "typedef" is actually a separate class inherited from `basic_fixed_string`. 
+:::
+
+### Template parameters
+
+| Name      | Description                                                                                                                                                                                                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TChar`   | character type                                                                                                                                                                                                                                                                |
+| `N`       | string size                                                                                                                                                                                                                                                                   |
+| `TTraits` | [`CharTraits`](https://en.cppreference.com/w/cpp/named_req/CharTraits) class specifying the operations on the character type. Like for `std::basic_string` or `std::basic_string_view`, `TTraits::char_type` must name the same type as `TChar` or the program is ill-formed. |
+
+### Member types
+
+| Member type              | Definiton                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `traits_type`            | `TTraits`                                                                                                                 |
+| `value_type`             | `TChar`                                                                                                                   |
+| `pointer`                | `value_type*`                                                                                                             |
+| `const_pointer`          | `const value_type*`                                                                                                       |
+| `reference`              | `value_type&`                                                                                                             |
+| `iterator`               | [`LegacyRandomAccessIterator`](https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator) to `value_type`          |
+| `const_iterator`         | Constant [`LegacyRandomAccessIterator`](https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator) to `value_type` |
+| `reverse_iterator`       | [`std::reverse_iterator<iterator>`](https://en.cppreference.com/w/cpp/iterator/reverse_iterator)                          |
+| `const_reverse_iterator` | [`std::reverse_iterator<const_iterator>`](https://en.cppreference.com/w/cpp/iterator/reverse_iterator)                    |
+| `size_type`              | `size_t`                                                                                                                  |
+| `difference_type`        | `ptrdiff_t`                                                                                                               |
+| `string_view_type`       | `std::basic_string_view<value_type, traits_type>`                                                                         |
+
+### Member functions
+
+#### Constructors and assignment
+
+| Name                                               | Description                       |
+| -------------------------------------------------- | --------------------------------- |
+| [*(constructor)*](./member-functions/constructors) | Constructs a `basic_fixed_string` |
+| [`operator=`](./member-functions/operator-assign)  | assigns values to the string      |
+
+#### Element access
+
+| Name                                           | Description                                   |
+| ---------------------------------------------- | --------------------------------------------- |
+| [`operator[]`](./member-functions/operator-at) | access specified element                      |
+| [`at`](./member-functions/at)                  | access specified element with bounds checking |
+| [`front`](./member-functions/front)            | accesses the first character                  |
+| [`back`](./member-functions/back)              | accesses the last character                   |
+
+#### Iterators
+
+| Name                                                  | Description                                 |
+| ----------------------------------------------------- | ------------------------------------------- |
+| [`begin` <br/> `cbegin`](./member-functions/begin)    | returns an iterator to the beginning        |
+| [`end` <br/> `cend`](./member-functions/end)          | returns an iterator to the end              |
+| [`rbegin` <br/> `crbegin`](./member-functions/rbegin) | returns a reverse iterator to the beginning |
+| [`rend` <br/> `crend`](./member-functions/rend)       | returns a reverse iterator to the end       |
+
+#### Capacity
+
+| Name                                             | Description                              |
+| ------------------------------------------------ | ---------------------------------------- |
+| [`empty`](./member-functions/empty)              | checks whether the fixed string is empty |
+| [`size` <br/> `length`](./member-functions/size) | returns the number of characters         |
+| [`max_size`](./member-functions/max_size)        | returns the maximum number of characters |
+
+
+#### Operations
+
+| Name                                  | Description                         |
+| ------------------------------------- | ----------------------------------- |
+| [`substr`](./member-functions/substr) | returns a substring                 |
+| [`find`](./member-functions/find.mdx) | find characters in the fixed string |

docs/api/member-functions/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Member functions",
+  "position": 2
+}

docs/api/member-functions/at.mdx

@@ -0,0 +1,53 @@
+---
+sidebar_position: 4
+sidebar_label: at
+---
+# `fixstr::basic_fixed_string::at`
+
+import CppOverload from '../../components/CppOverload';
+import CppOverloadList from '../../components/CppOverloadList';
+import LinkButton from '../../components/LinkButton';
+import CodeBlock from '@theme/CodeBlock';
+import Overload1 from '!!raw-loader!.//at/1.cpp';
+import Overload2 from '!!raw-loader!.//at/2.cpp';
+import Example from '!!raw-loader!.//at/example.cpp';
+
+<CppOverloadList>
+    <CppOverload num={1} code={Overload1} />
+    <CppOverload num={2} code={Overload2} />
+</CppOverloadList>
+
+Returns a reference to the element at specified location `pos`, with bounds checking.
+
+If pos is not within the range of the container, an exception of type [`std::out_of_range`](https://en.cppreference.com/w/cpp/error/out_of_range) is thrown.
+
+## Parameters
+
+* `pos`	-	position of the element to return
+
+## Return value
+
+Reference to the requested element.
+
+## Exceptions
+
+[`std::out_of_range`](https://en.cppreference.com/w/cpp/error/out_of_range) if `pos > size()`.
+
+## Complexity
+
+Constant.
+
+## Example
+
+<LinkButton link="https://godbolt.org/z/xWcGTdE9h">Run this code!</LinkButton>
+<CodeBlock className="language-cpp">{Example}</CodeBlock>
+
+Possible output:
+```
+H
+array::at
+```
+
+:::info note
+In the implementation the call to `at` member function is delegated to `std::array` that serves as an underlying storage. That's why `error.what()` returns `array::at`.
+:::

docs/api/member-functions/at/1.cpp

@@ -0,0 +1 @@
+[[nodiscard]] constexpr reference at(size_type pos);

docs/api/member-functions/at/2.cpp

@@ -0,0 +1 @@
+[[nodiscard]] constexpr const_reference at(size_type pos) const;

docs/api/member-functions/at/example.cpp

@@ -0,0 +1,16 @@
+#include <fixed_string.hpp>
+#include <iostream>
+
+int main()
+{
+    fixstr::fixed_string str = "Hello, World!";
+    try
+    {
+        std::cout << str.at(0) << std::endl;
+        std::cout << str.at(25) << std::endl;
+    }
+    catch (std::exception& error)
+    {
+        std::cout << error.what() << std::endl;
+    }
+}