set/README.md

# set

A small, generic Go set implementation for ordered types (numbers, strings, etc.).

This package provides a lightweight `Set[T]` built on Go maps, with common
set operations such as union, intersection, difference, and helpers to convert
to slices. It uses Go generics and requires ordered element types.

## Features

- Generic `Set[T]` where `T` is any `constraints.Ordered` type (e.g. `int`,
  `string`, `float64`).
- Common set operations: `Union`, `Intersection`, `Difference`.
- Convenience methods: `Add`, `Remove`, `Contains`, `Size`, `ToSlice`,
  `ToSortedSlice`, and `Equal`.

## Requirements

- Go 1.20+ (uses `maps` package and generics introduced in earlier versions; `maps.Equal` requires Go 1.20+).

## Module & Dependencies

- **Module path:** `code.wmdillon.com/wmdillon/settings`
- **Go toolchain:** `go 1.25.3`
- **Direct dependencies:**
  - `golang.org/x/exp v0.0.0-20251125195548-87e1e737ad39`

To fetch dependencies for this module run:

```bash
go mod download
```

## Installation

Add the package to your module by importing it. Replace the import path with
your module path if the package is local to your repository.

```go
import "your/module/path/set"
```

## Quick Example

```go
package main

import (
    "fmt"
    "your/module/path/set"
)

func main() {
    // Create new sets of ints
    s1 := set.New[int](1, 2, 3, 4)
    s2 := set.New[int](3, 4, 5)

    // Union
    u := s1.Union(s2)
    fmt.Println("Union:", u.ToSortedSlice()) // [1 2 3 4 5]

    // Intersection
    i := s1.Intersection(s2)
    fmt.Println("Intersection:", i.ToSortedSlice()) // [3 4]

    // Difference
    d := s1.Difference(s2)
    fmt.Println("Difference:", d.ToSortedSlice()) // [1 2]

    // Add / Remove / Contains
    s := set.New[int]()
    s.Add(10)
    s.Add(20)
    fmt.Println("Contains 20?", s.Contains(20))
    s.Remove(20)
    fmt.Println("Size:", s.Size())
}
```

## API Overview

- `type Set[T constraints.Ordered] map[T]struct{}`
- `func New[T constraints.Ordered](elements ...T) Set[T]`
- `func (s Set[T]) Add(element T)`
- `func (s Set[T]) Remove(element T)`
- `func (s Set[T]) Contains(element T) bool`
- `func (s Set[T]) Size() int`
- `func (s Set[T]) ToSlice() []T`
- `func (s Set[T]) ToSortedSlice() []T` — returns a sorted slice (ascending order)
- `func (s Set[T]) Union(other Set[T]) Set[T]`
- `func (s Set[T]) Intersection(other Set[T]) Set[T]`
- `func (s Set[T]) Difference(other Set[T]) Set[T]`
- `func (s Set[T]) Equal(other Set[T]) bool`

## Running Tests

From the package directory run:

```bash
go test ./... -v
```

The repository includes unit tests (`set_test.go`) demonstrating expected
behavior for union, intersection, difference, membership, and conversions.

## Notes

- Because the implementation uses `constraints.Ordered`, only ordered types are
  supported (numbers, strings). If you need sets for non-ordered types (e.g.
  structs) you can adapt the code to use `comparable` and provide a custom
  ordering for `ToSortedSlice`.
- The `Equal` method uses `maps.Equal` from the standard library to compare
  underlying maps.

If you'd like, I can update the README with an import path (module name),
add more examples for strings or custom types, or include benchmarks.