Merge pull request #119 from harrisb002/docs/separate-readme-examples-boolean

docs: Separate README and EXAMPLES for all packages (#103)

Author: kashifkhan0771

EXAMPLES.md

@@ -0,0 +1,263 @@
+## Boolean Function Examples
+
+### Check if the provided string is a true
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.IsTrue("T"))
+	fmt.Println(boolutils.IsTrue("1"))
+	fmt.Println(boolutils.IsTrue("TRUE"))
+}
+```
+
+#### Output:
+
+```
+true
+true
+true
+```
+
+### Toggle a boolean value
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.Toggle(true))
+	fmt.Println(boolutils.Toggle(false))
+}
+```
+
+#### Output:
+
+```
+false
+true
+```
+
+### Check if all values in a slice are true
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.AllTrue([]bool{true, true, true}))
+	fmt.Println(boolutils.AllTrue([]bool{true, false, true}))
+	fmt.Println(boolutils.AllTrue([]bool{}))
+}
+```
+
+#### Output:
+
+```
+true
+false
+false
+```
+
+### Check if any value in a slice is true
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.AnyTrue([]bool{false, true, false}))
+	fmt.Println(boolutils.AnyTrue([]bool{false, false, false}))
+	fmt.Println(boolutils.AnyTrue([]bool{}))
+}
+```
+
+#### Output:
+
+```
+true
+false
+false
+```
+
+### Check if none of the values in a slice are true
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.NoneTrue([]bool{false, false, false}))
+	fmt.Println(boolutils.NoneTrue([]bool{false, true, false}))
+	fmt.Println(boolutils.NoneTrue([]bool{}))
+}
+```
+
+#### Output:
+
+```
+true
+false
+true
+```
+
+### Count the number of true values in a slice
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.CountTrue([]bool{true, false, true}))
+	fmt.Println(boolutils.CountTrue([]bool{false, false, false}))
+	fmt.Println(boolutils.CountTrue([]bool{}))
+}
+```
+
+#### Output:
+
+```
+2
+0
+0
+```
+
+### Count the number of false values in a slice
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.CountFalse([]bool{true, false, true}))
+	fmt.Println(boolutils.CountFalse([]bool{false, false, false}))
+	fmt.Println(boolutils.CountFalse([]bool{}))
+}
+```
+
+#### Output:
+
+```
+1
+3
+0
+```
+
+### Check if all values in a slice are equal
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.Equal(true, true, true))
+	fmt.Println(boolutils.Equal(false, false, false))
+	fmt.Println(boolutils.Equal(true, false, true))
+	fmt.Println(boolutils.Equal())
+}
+```
+
+#### Output:
+
+```
+true
+true
+false
+false
+```
+
+### Perform a logical AND operation on a slice
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.And([]bool{true, true, true}))
+	fmt.Println(boolutils.And([]bool{true, false, true}))
+	fmt.Println(boolutils.And([]bool{}))
+}
+```
+
+#### Output:
+
+```
+true
+false
+false
+```
+
+### Perform a logical OR operation on a slice
+
+```go
+package main
+
+import (
+	"fmt"
+
+	boolutils "github.com/kashifkhan0771/utils/boolean"
+)
+
+func main() {
+	fmt.Println(boolutils.Or([]bool{false, true, false}))
+	fmt.Println(boolutils.Or([]bool{false, false, false}))
+	fmt.Println(boolutils.Or([]bool{}))
+}
+```
+
+#### Output:
+
+```
+true
+false
+false
+```
+
+---

README.md

@@ -0,0 +1,18 @@
+### Boolean Functions
+
+- **IsTrue**: Checks if the provided string represents a true value (e.g., "T", "1", "TRUE").
+- **Toggle**: Toggles the given boolean value, returning its negation. (e.g., `true` becomes `false` and vice versa).
+- **AllTrue**: Checks if all the values in a slice of booleans are `true`. Returns `false` if the slice is empty.
+- **AnyTrue**: Checks if at least one value in a slice of booleans is `true`. Returns `false` if the slice is empty.
+- **NoneTrue**: Checks if none of the values in a slice of booleans are `true`. Returns `true` if the slice is empty.
+- **CountTrue**: Counts the number of `true` values in a slice of booleans. Returns `0` for an empty slice.
+- **CountFalse**: Counts the number of `false` values in a slice of booleans. Returns `0` for an empty slice.
+- **Equal**: Checks if all the values in a variadic boolean argument are equal. Returns `true` if the slice contains only one or no elements.
+- **And**: Performs a logical AND operation on all the values in a slice of booleans. Returns `true` only if all values are `true`. Returns `false` for an empty slice.
+- **Or**: Performs a logical OR operation on all the values in a slice of booleans. Returns `true` if at least one value is `true`. Returns `false` for an empty slice.
+
+## Examples:
+
+For examples of each function, please checkout [EXAMPLES.md](/boolean/EXAMPLES.md)
+
+---

boolean/EXAMPLES.md

@@ -0,0 +1,71 @@
+## Caching Function Examples
+
+## `CacheWrapper`
+
+### A non-thread-safe caching decorator
+
+```go
+package main
+
+import (
+	"fmt"
+	"math/big"
+	"github.com/kashifkhan0771/utils/math"
+)
+
+// Example function: Compute factorial
+func factorial(n int) *big.Int {
+	result := big.NewInt(1)
+	for i := 2; i <= n; i++ {
+		result.Mul(result, big.NewInt(int64(i)))
+	}
+	return result
+}
+
+func main() {
+	cachedFactorial := utils.CacheWrapper(factorial)
+	fmt.Println(cachedFactorial(10))
+}
+```
+
+#### Output:
+
+```
+3628800
+```
+
+---
+
+## SafeCacheWrapper
+
+### A thread-safe caching decorator
+
+```go
+package main
+
+import (
+	"fmt"
+	"math/big"
+	"github.com/kashifkhan0771/utils/math"
+)
+
+// Example function: Compute factorial
+func factorial(n int) *big.Int {
+	result := big.NewInt(1)
+	for i := 2; i <= n; i++ {
+		result.Mul(result, big.NewInt(int64(i)))
+	}
+	return result
+}
+
+func main() {
+	cachedFactorial := utils.SafeCacheWrapper(factorial)
+	fmt.Println(cachedFactorial(10))
+}
+```
+
+#### Output:
+
+```
+3628800
+```

boolean/README.md

@@ -0,0 +1,22 @@
+### Caching
+
+The caching package provides utilities for creating caching decorators to enhance the performance of functions by storing computed results. It includes both thread-safe and non-thread-safe implementations.
+
+- **SafeCacheWrapper**: A thread-safe caching decorator that safely memoizes function results in concurrent environments.
+
+  - Uses `sync.Map` to ensure thread-safety
+  - Caches all results indefinitely (no eviction)
+  - Best suited for pure functions with limited input domains
+  - Safe for concurrent access but may impact performance under high contention
+
+- **CacheWrapper**: A non-thread-safe caching decorator that memoizes function results.
+  - Caches all results indefinitely (no eviction)
+  - Best suited for pure functions with limited input domains
+  - Not safe for concurrent access
+  - Use SafeCacheWrapper for concurrent scenarios
+
+## Examples:
+
+For examples of each function, please checkout [EXAMPLES.md](/caching/EXAMPLES.md)
+
+---