# SharpLib - Core Library Reference

SharpLib is a comprehensive C# utility library providing essential functionality for .NET applications. It offers a wide range of utilities, mathematical operations, and helper classes to streamline development.

## Core Components

### Math & Geometry
- **Vector2/3/4**: Vector mathematics with extensive operations
- **Matrix**: 4x4 matrix operations for transformations
- **Quaternion**: Quaternion math for 3D rotations
- **BoundingBox/BoundingSphere**: Collision detection primitives
- **Ray/Plane**: Geometric raycasting and plane operations
- **Color**: Color manipulation with multiple formats (RGBA, HSV, etc.)
- **MathUtil**: Mathematical helper functions and constants
- **Angle**: Angle handling utilities

### Data Structures & Collections
- **Immutable collections**: Immutable List, FSM (Finite State Machine), Versioned, Recorded, Timed objects
- **Pod**: Plain Old Data structures
- **LinqExtensions**: Extended LINQ functionality
- **RandomEx**: Enhanced random number generation
- **Guid**: GUID utilities

### Utilities & Helpers
- **StringEx**: String manipulation extensions
- **Debug**: Debugging utilities
- **Exec**: Process execution helpers
- **Utilities**: General utility functions
- **Token**: Token handling utilities
- **Id**: ID generation utilities

### Reflection & Metadata
- **Reflection utilities**: Runtime type inspection and manipulation
- **Attributes**: Custom attributes for data handling

### System Integration
- **Logging**: Logging infrastructure with structured logging, source location tracking, and multiple log levels
- **Time/Timer/Clock**: Time management utilities
- **Resources**: Resource management helpers with lazy loading and caching
- **Interop**: Platform interop capabilities
- **Config**: Configuration management with XML serialization and template creation
- **Immutable**: Immutable collections with versioning (Versioned), recording (Recorded), and timing (Timed) capabilities

## Key Features

- **Cross-platform compatibility**: Targets .NET 9.0 and 10.0
- **Unsafe code support**: For performance-critical operations
- **Extensive documentation**: Well-documented APIs with examples
- **Type safety**: Strong typing throughout the library
- **Performance focused**: Optimized for speed and memory usage

## Usage Examples

```csharp
// Vector math
var vector = new Vector3(1, 2, 3);
var normalized = vector.Normalized();

// Color manipulation
var color = Color.FromRgb(255, 128, 0);
var hsv = color.ToHsv();

// Bitwise operations
if (bit.On(flags, MyEnum.Flag1))
{
    // Handle flag
}

// Random generation
var random = new RandomEx();
var value = random.NextDouble();

// Logging with source location tracking
log.Info("Application started", cat: "app");
log.Var("User ID", userId);
log.Operations(() => {
    // Some operation
});

// Configuration loading
var config = cfg.load<MyConfig>("config.xml");

// Resource management
var texture = res.Mgr.Lookup<Texture2D>("assets/texture.png");

// Immutable collections
var list = new List<int>(new[] { 1, 2, 3 });
var newList = list.Add(4);
```

## Target Frameworks

- .NET 9.0
- .NET 10.0

## Dependencies

- Microsoft.CodeAnalysis.CSharp
- Optional (for functional programming patterns)
- System.Collections.Immutable
- System.ValueTuple
- Microsoft.Diagnostics.NETCore.Client
- Microsoft.Diagnostics.Tracing.TraceEvent