docs: documented format strings

.wiki/Kernel-documentation.md

@@ -12,13 +12,13 @@ The kernel is booted using the limine boot protocol.
 ---
 
 # General concepts
-## kernel initialization
+## Kernel initialization
 The single parts of the kernel are initialized in the following order:
   - **Global Descriptor Table**
   - **Page Frame Manager**
   - **Interrupt Descriptor Table**
 
-## interrupt handling
+## Interrupt handling
 OSDev Wiki: [Interrupts](https://wiki.osdev.org/Interrupts)
 
 Unfortunatly the x86 architecture doesn't provide a method to get the ID of the current interrupt.
@@ -27,7 +27,7 @@ This function pushes its ID on the stack.
 After that it calls a common Interrupt handler, this handler will generate the current `cpu_state_T` and call the C interrupt handler implementation.
 The C implementation returns a `cpu_state_T` that will then be loaded.
 
-## paging
+## Paging
 OSDev Wiki: [Paging](https://wiki.osdev.org/Paging)
 
 There is a difference between `Virtual Memory Spaces` and the `Physical Memory Space`.
@@ -45,6 +45,122 @@ When the Computer is in paging mode, only mapped pages are accessible.
 Now every Process gets its own page table and tada: we have successfully isolated the processes from each other,
 because every process can only access the data that it needs to access.
 
+## Format strings
+Format strings are strings that are formatted at runtime.
+They are created by defining a pattern, like the following one:
+
+`"Name: %s / ID: %d"`
+
+And giving it arguments at runtime, let's use the following ones for our example:
+
+`"Main Process", 42`
+
+This would format to that:
+
+`Name: Main Process / ID: 42`
+
+As you see, `%s` and `%d` are placeholders.
+Placeholders consist of a `%` sign followed by one or two letters.
+When formatting the string, the placeholders are replaced with the arguments.
+The first placeholder is replaced with the first argument, the second with the second and so on.
+
+### Numeric specifier
+If you put a `.` followed by a number right after the percentage sign of a placeholder,
+you will set the `Numeric specifier`.
+Some placeholders use this numeric specifier to configure their output.
+If you don't set a numeric specifier, the placeholders, that would use it will use a default value instead.
+
+### Arguments
+Make sure, that the arguments you pass, are really of the right type.
+If you e.g. pass a negative value of type `int32_t` like `-1312`,
+the formatter will have problems with that, because the `int32_t` representation of that number is as an `int64_t` a positive number.
+
+### Placeholders
+#### `%s` - string
+| **Argument Type**             | `string_t`       |
+|-------------------------------|------------------|
+| **Numeric Specifier Use**     | None             |
+| **Numeric Specifier Default** | None             |
+| **Description**               | Inserts a string |
+
+#### `%c` - char
+| **Argument Type**             | `char`              |
+|-------------------------------|---------------------|
+| **Numeric Specifier Use**     | None                |
+| **Numeric Specifier Default** | None                |
+| **Description**               | Inserts a character |
+
+#### `%u` - unsigned decimal
+| **Argument Type**             | `uint64_t`                  |
+|-------------------------------|-----------------------------|
+| **Numeric Specifier Use**     | None                        |
+| **Numeric Specifier Default** | None                        |
+| **Description**               | Inserts an unsigned integer |
+
+#### `%d` - signed decimal
+| **Argument Type**             | `int64_t`                |
+|-------------------------------|--------------------------|
+| **Numeric Specifier Use**     | None                     |
+| **Numeric Specifier Default** | None                     |
+| **Description**               | Inserts a signed integer |
+
+#### `%x` - hexadecimal
+| **Argument Type**             | `uint64_t`                   |
+|-------------------------------|------------------------------|
+| **Numeric Specifier Use**     | None                         |
+| **Numeric Specifier Default** | None                         |
+| **Description**               | Inserts a 64 bit hex integer |
+
+##### variants
+###### `%xb` - byte hexadecimal
+| **Argument Type**             | `uint8_t`                   |
+|-------------------------------|-----------------------------|
+| **Numeric Specifier Use**     | None                        |
+| **Numeric Specifier Default** | None                        |
+| **Description**               | Inserts a 8 bit hex integer |
+
+###### `%xw` - word hexadecimal
+| **Argument Type**             | `uint16_t`                   |
+|-------------------------------|------------------------------|
+| **Numeric Specifier Use**     | None                         |
+| **Numeric Specifier Default** | None                         |
+| **Description**               | Inserts a 16 bit hex integer |
+
+###### `%xd` - dword hexadecimal
+| **Argument Type**             | `uint32_t`                   |
+|-------------------------------|------------------------------|
+| **Numeric Specifier Use**     | None                         |
+| **Numeric Specifier Default** | None                         |
+| **Description**               | Inserts a 32 bit hex integer |
+
+###### `%xq` - qword hexadecimal
+This variant is the `%x` standard.
+
+| **Argument Type**             | `uint64_t`                   |
+|-------------------------------|------------------------------|
+| **Numeric Specifier Use**     | None                         |
+| **Numeric Specifier Default** | None                         |
+| **Description**               | Inserts a 64 bit hex integer |
+
+
+#### `%?` - boolean
+| **Argument Type**             | `bool`                    |
+|-------------------------------|---------------------------|
+| **Numeric Specifier Use**     | None                      |
+| **Numeric Specifier Default** | None                      |
+| **Description**               | Inserts `true` or `false` |
+
+#### `%b` - binary
+| **Argument Type**             | `uint64_t`                                    |
+|-------------------------------|-----------------------------------------------|
+| **Numeric Specifier Use**     | The amount of bits that are shown             |
+| **Numeric Specifier Default** | 64                                            |
+| **Description**               | Inserts the binary string of the given number |
+
+#### `%%` - mask
+This is not a really a placeholder, but you can use this to mask the % sign,
+so it will be interpreted as just a `%` instead of a placeholder.
+
 ---
 
 **DISCLAIMER:** Only the headers are documented, because documenting the whole code itself would be very time intensive and the headers as 'public' API are the most important to document.
@@ -459,6 +575,20 @@ Returns the amount of chars a string has before it's null-terminator.
 Returns **true** when the strings **_a_** and **_b_** are equal.
 Returns **false** if they aren't equal.
 
+#### `variadic_format_size(string, args)` - function (uint64_t)
+Returns how long a format string with the given pattern (**_string_**) and **_args_** would be.
+Useful to create a big enough buffer before formatting a string.
+
+#### `format_size(string, ...)` - function (uint64_t)
+This calls `variadic_format_size`, but instead of giving it a `va_list` you can give this function the actual arguments.
+
+#### `variadic_format(output, string, args)` - function (void)
+Formats **_string_** with **_args_** and writes the product to **_output_**.
+The rules for format strings are specified on top of this document in the _General concepts_ block.
+
+#### `format(output, string, ...)` - function (void)
+This calls `variadic_format`, but instead of giving it a `va_list` you can give this function the actual arguments.
+
 #### `string_unsigned_dec_to_alpha(string, value)` - function (void)
 Converts the unsigned integer in **_value_** to an alphanumeric string.
 The representation is decimal.