Merge branch 'docsReDesign' into develop

Author: EvilLord666

README.md

@@ -1,154 +1,190 @@
-# StringFormatter
-
-* A set of a ***high performance string tools*** that helps to build strings from templates and process text faster than with `fmt`!!!.
-* Allows to **format code in appropriate style** (`Snake`, `Kebab`, `Camel`) and case.
-* Slice printing is **50% faster with 8 items** slice and **250% with 20 items** slice 
-
+# Wissance/StringFormatter
 ![GitHub go.mod Go version (subdirectory of monorepo)](https://img.shields.io/github/go-mod/go-version/wissance/stringFormatter?style=plastic) 
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/wissance/stringFormatter?style=plastic) 
 ![GitHub issues](https://img.shields.io/github/issues/wissance/stringFormatter?style=plastic)
 ![GitHub Release Date](https://img.shields.io/github/release-date/wissance/stringFormatter) 
-![GitHub release (latest by date)](https://img.shields.io/github/downloads/wissance/stringFormatter/v1.6.1/total?style=plastic)
+[![Wissance.WebApiToolkit CI](https://github.com/Wissance/stringFormatter/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Wissance/stringFormatter/actions/workflows/ci.yml)
 
-![String Formatter: a convenient string formatting tool](img/sf_cover.png)
+![String Formatter: a convenient string formatting tool](img/sf_logo_sm.png)
 
-## 1. Features
+`StringFormatter` is a ***high-performance*** Go library for string (text) formatting. It offers a syntax *familiar* to `C#`, `Java` and `Python` developers (via template arguments - `{0}` (positional), `{name}` (named)), extensive argument formatting options (numbers, lists, code style), and a set of text utilities — all while being significantly fast as the standard `fmt` package and even more! Typical usage of `sf` are:
+1. Create `e-mails`, `Messages` (`SMS`, `Telegram`, other `Notifications`) or other complicated text **based on templates**
+2. Create a complicated log text with specific argument formatting
+3. Use for **template-based src code generator**
+4. Other text proccessing
 
-1. Text formatting with template using traditional for `C#, Python programmers style` - `{0}`, `{name}` that faster then `fmt` does:
-![String Formatter: a convenient string formatting tool](img/benchmarks_adv.png)
-2. Additional text utilities:
-   - convert ***map to string*** using one of predefined formats (see `text_utils.go`)
-3. Code Style formatting utilities
-   - convert `snake`/`kebab`/`camel` programming code to each other and vice versa (see `stringstyle_formatter.go`).
-4. `StringFormatter` aka `sf` **is safe** (`SAST` and tests were running automatically on push) 
+## ✨ 1 Features
 
-### 1. Text formatting from templates
+🔤 Flexible Syntax: Supports both indexed / positional (`{0}`) and named (`{user}`) *placeholders* in templates.
 
-#### 1.1 Description
+🎨 Advanced Formatting: Built-in directives for numbers (`HEX`, `BIN`), `floats`, `lists`, and code styles (camelCase, SNAKE_CASE).
 
-This is a GO module for ***template text formatting in syntax like in C# or/and Python*** using:
-- `{n}` , n here is a number to notes order of argument list to use i.e. `{0}`, `{1}`
-- `{name}` to notes arguments by name i.e. `{name}`, `{last_name}`, `{address}` and so on ...
+🚀 Performance: Template formatting and slice conversion are even faster then `fmt`.
 
-#### 1.2 Examples
+🛠 Utilities: Functions to convert `maps` and `slices` into strings with custom separators and formats.
 
-##### 1.2.1 Format by arg order
+:man_technologist: Safe : `StringFormatter` aka `sf` **is safe** (`SAST` and tests are running automatically on push) 
 
-i.e. you have following template:  `"Hello {0}, we are greeting you here: {1}!"`
+## 📦 2 Installation
+
+```bash
+go get github.com/Wissance/stringFormatter
+```
 
-if you call Format with args "manager" and "salesApp" :
+## 🚀 3  Usage
+
+### 3.1 Template Formatting
+
+#### 3.1.1 By Argument Order (Format)
+The Format function replaces `{n}` placeholders with the corresponding argument in the provided order.
 
 ```go
-formattedStr := stringFormatter.Format("Hello {0}, we are greeting you here: {1}!", "manager", "salesApp")
-```
+package main
 
-you get string `"Hello manager, we are greeting you here: salesApp!"`
+import (
+    "fmt"
+    sf "github.com/Wissance/stringFormatter"
+)
 
-##### 1.2.2 Format by arg key
+func main() {
+    template := "Hello, {0}! Your balance is {1} USD."
+    result := sf.Format(template, "Alex", 2500)
+    fmt.Println(result)
+    // Output: Hello, Alex! Your balance is 2500 USD.
+}
+```
 
-i.e. you have following template: `"Hello {user} what are you doing here {app} ?"`
+#### 3.1.2 By Argument Name (FormatComplex)
+The FormatComplex function uses a `map[string]any` to replace named placeholders like `{key}`.
 
-if you call `FormatComplex` with args `"vpupkin"` and `"mn_console"` `FormatComplex("Hello {user} what are you doing here {app} ?", map[string]any{"user":"vpupkin", "app":"mn_console"})`
+```go
+package main
 
-you get string `"Hello vpupkin what are you doing here mn_console ?"`
+import (
+    "fmt"
+    sf "github.com/Wissance/stringFormatter"
+)
 
-another example is:
+func main() {
+    template := "User {user} (ID: {id}) logged into {app}."
+    args := map[string]any{
+        "user": "john_doe",
+        "id":   12345,
+        "app":  "dashboard",
+    }
+    result := sf.FormatComplex(template, args)
+    fmt.Println(result)
+    // Output: User john_doe (ID: 12345) logged into dashboard.
+}
+```
+
+### 3.2 Advanced Argument Formatting
+You can control how arguments are displayed by adding a colon (:) and a format specifier to the placeholder.
+
+| Type | Specifier | Description | Example Template | Example Value | Output |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Numbers** | `:B` | Binary (without padding) | `"{0:B}"` | `15` | `1111` |
+| | `:B8` | Binary with 8-digit padding | `"{0:B8}"` | `15` | `00001111` |
+| | `:X` | Hexadecimal (lowercase) | `"{0:X}"` | `250` | `fa` |
+| | `:X4` | Hexadecimal with 4-digit padding | `"{0:X4}"` | `250` | `00fa` |
+| | `:o` | Octal | `"{0:o}"` | `11` | `14` |
+| **Floating Point** | `:F` | Default float format | `"{0:F}"` | `10.4567890` | `10.456789` |
+| | `:F2` | Float with 2 decimal places | `"{0:F2}"` | `10.4567890` | `10.46` |
+| | `:F4` | Float with 4 decimal places | `"{0:F4}"` | `10.4567890` | `10.4568` |
+| | `:F8` | Float with 8 decimal places | `"{0:F8}"` | `10.4567890` | `10.45678900` |
+| | `:E2` | Scientific notation | `"{0:E2}"` | `191.0478` | `1.91e+02` |
+| **Percentage** | `:P100` | Percentage (multiply by 100) | `"{0:P100}"` | `12` | `12%` |
+| **Lists (Slices)** | `:L-` | Join with hyphen | `"{0:L-}"` | `[1 2 3]` | `1-2-3` |
+| | `:L, ` | Join with comma and space | `"{0:L, }"` | `[1 2 3]` | `1, 2, 3` |
+| **Code Styles** | `:c:snake` | Convert to snake_case | `"{0:c:snake}"` | `myFunc` | `my_func` |
+| | `:c:Snake` | Convert to Snake_Case (PascalSnake) | `"{0:c:Snake}"` | `myFunc` | `My_Func` |
+| | `:c:SNAKE` | Convert to SNAKE_CASE (upper) | `"{0:c:SNAKE}"` | `read-timeout` | `READ_TIMEOUT` |
+| | `:c:camel` | Convert to camelCase | `"{0:c:camel}"` | `my_variable` | `myVariable` |
+| | `:c:Camel` | Convert to CamelCase (PascalCase) | `"{0:c:Camel}"` | `my_variable` | `MyVariable` |
+| | `:c:kebab` | Convert to kebab-case | `"{0:c:kebab}"` | `myVariable` | `my-variable` |
+| | `:c:Kebab` | Convert to Kebab-Case (PascalKebab) | `"{0:c:Kebab}"` | `myVariable` | `My-Variable` |
+| | `:c:KEBAB` | Convert to KEBAB-CASE (upper) | `"{0:c:KEBAB}"` | `myVariable` | `MY-VARIABLE` |
 
 ```go
-strFormatResult = stringFormatter.FormatComplex(
-	"Current app settings are: ipAddr: {ipaddr}, port: {port}, use ssl: {ssl}.", 
-	map[string]any{"ipaddr":"127.0.0.1", "port":5432, "ssl":false},
+package main
+
+import (
+    "fmt"
+    sf "github.com/Wissance/stringFormatter"
 )
+
+func main() {
+    template := "Status 0x{0:X4} (binary: {0:B8}), temp: {1:F1}°C, items: {2:L, }."
+    result := sf.Format(template, 475, 23.876, []int{1, 2, 3})
+    fmt.Println(result)
+    // Output: Status 0x01DB (binary: 00011101), temp: 23.9°C, items: 1, 2, 3.
+}
 ```
-a result will be: `"Current app settings are: ipAddr: 127.0.0.1, port: 5432, use ssl: false."``
-
-##### 1.2.3 Advanced arguments formatting
-
-For more convenient lines formatting we should choose how arguments are representing in output text, 
-`stringFormatter` supports following format options:
-1. Bin number formatting 
-   - `{0:B}, 15 outputs -> 1111`
-   - `{0:B8}, 15 outputs -> 00001111`
-2. Hex number formatting
-   - `{0:X}, 250 outputs -> fa`
-   - `{0:X4}, 250 outputs -> 00fa`
-3. Oct number formatting
-   - `{0:o}, 11 outputs -> 14`
-4. Float point number formatting
-   - `{0:E2}, 191.0478 outputs -> 1.91e+02`
-   - `{0:F}, 10.4567890 outputs -> 10.456789`
-   - `{0:F4}, 10.4567890 outputs -> 10.4568`
-   - `{0:F8}, 10.4567890 outputs -> 10.45678900`
-5. Percentage output
-   - `{0:P100}, 12 outputs -> 12%`
-6. Lists
-   - `{0:L-}, [1,2,3] outputs -> 1-2-3`
-   - `{0:L, }, [1,2,3] outputs -> 1, 2, 3`
-7. Code
-   - `{0:c:snake}, myFunc outputs -> my_func`
-   - `{0:c:Snake}, myFunc outputs -> My_func`
-   - `{0:c:SNAKE}, read-timeout outputs -> READ_TIMEOUT`
-   - `{0:c:camel}, my_variable outputs -> myVariable`
-   - `{0:c:Camel}, my_variable outputs -> MyVariable`
-
-##### 1.2.4 Benchmarks of the Format and FormatComplex functions
-
-benchmark could be running using following commands from command line:
-* to see `Format` result - `go test -bench=Format -benchmem -cpu 1`
-* to see `fmt` result - `go test -bench=Fmt -benchmem -cpu 1`
-
-### 2. Text utilities
-
-#### 2.1 Map to string utility
-
-`MapToString` function allows to convert map with primitive key to string using format, including key and value, e.g.:
-* `{key} => {value}`
-* `{key} : {value}`
-* `{value}`
-
-For example:
+
+## 🛠 4 Text Utilities
+
+### 4.1 Map to String (MapToString)
+Converts a map with primitive keys to a formatted string.
 ```go
 options := map[string]any{
-	"connectTimeout": 1000,
-	"useSsl":         true,
-	"login":          "sa",
-	"password":       "sa",
+    "host": "localhost",
+    "port": 8080,
+    "ssl":  true,
 }
 
-str := stringFormatter.MapToString(&options, "{key} : {value}", ", ")
-// NOTE: order of key-value pairs is not guranteed though
-// str will be something like:
-"connectTimeout : 1000, useSsl : true, login : sa, password : sa"
+str := sf.MapToString(&options, "{key} = {value}", "\n")
+// Possible output (key order is not guaranteed):
+// host = localhost
+// port = 8080
+// ssl = true
 ```
 
-#### 2.2 Benchmarks of the MapToString function
+### 4.2 Slice to String (SliceToString, SliceSameTypeToString)
+Converts slices to a string using a specified separator.
 
-* to see `MapToStr` result - `go test -bench=MapToStr -benchmem -cpu 1`
+```go
+// For a slice of any type
+mixedSlice := []any{100, "text", 3.14}
+separator := " | "
+result1 := sf.SliceToString(&mixedSlice, &separator)
+// result1: "100 | text | 3.14"
+
+// For a typed slice
+numSlice := []int{10, 20, 30}
+result2 := sf.SliceSameTypeToString(&numSlice, &separator)
+// result2: "10 | 20 | 30"
+```
 
-![MapToStr benchmarks](/img/map2str_benchmarks.png)
+## 📊 5 Benchmarks
+The library is optimized for high-load scenarios. Key benchmarks show significant performance gains (performance could be differ due to 1. different CPU architectures 2. statistics):
 
-#### 2.3 Slice to string utility
+Formatting (Format) vs fmt.Sprintf: 3-5x faster for complex templates.
+Slices (SliceToString) vs manual fmt-based joining: from `2.5` faster up to 20 items.
 
-`SliceToString` - function that converts slice with passed separation between items to string.
-```go
-slice := []any{100, "200", 300, "400", 500, 600, "700", 800, 1.09, "hello"}
-separator := ","
-result := stringFormatter.SliceToString(&slice, &separator)
+Run the benchmarks yourself:
+```bash
+go test -bench=Format -benchmem -cpu 1
+go test -bench=Fmt -benchmem -cpu 1
+go test -bench=MapToStr -benchmem -cpu 1
 ```
+Some benchmark screenshots:
 
-`SliceSameTypeToString` - function that converts typed slice to line with separator
-```go
-separator := ":"
-numericSlice := []int{100, 200, 400, 800}
-result := stringFormatter.SliceSameTypeToString(&numericSlice, &separator)
-```
+1. `Format` and `FormatComplex`:
+![Format](img/benchmarks2.png)
+
+2. `MapToStr`:
+![MapToStr benchmarks](img/map2str_benchmarks.png)
+
+3. `SliceToStr`:
+![SliceToStr benchmarks](img/slice2str_benchmarks.png)
 
-#### 2.4 Benchmarks of the SliceToString function
+## 📄 6 License
+This project is licensed under the MIT License - see the LICENSE file for details.
 
-`sf` is rather fast then `fmt` 2.5 times (250%) faster on slice with 20 items, see benchmark:
-![SliceToStr benchmarks](/img/slice2str_benchmarks.png)
+## 🤝 7 Contributing
+Contributions are welcome! If you find a bug or have a feature suggestion, please open an issue or submit a pull request.
 
-### 3. Contributors
+**Contributors:**
 
 <a href="https://github.com/Wissance/stringFormatter/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=Wissance/stringFormatter" />