# ConvertObject

Type conversion utility for Dart with nested extraction and custom converters.

## API

### Core Pattern

to[Type](object, {mapKey?, listIndex?, defaultValue?, converter?}) → Type | throws ParsingException
tryTo[Type](object, {mapKey?, listIndex?, defaultValue?, converter?}) → Type?

Types: String, num, int, BigInt, double, bool, DateTime, Uri, Map<K,V>, Set<T>, List<T>

### Type-Specific Parameters

Numbers (num/int/double):
- format: String? - number format pattern
- locale: String? - locale for parsing

DateTime:
- format: String? - date format pattern
- locale: String? - locale for parsing
- autoDetectFormat: bool = false
- useCurrentLocale: bool = false
- utc: bool = false

Collections (Map/Set/List):
- keyConverter: ElementConverter<K>? - for Map keys
- valueConverter: ElementConverter<V>? - for Map values
- elementConverter: ElementConverter<T>? - for Set/List elements

### Nested Extraction

```dart
// Extract from Map
final data = {'user': {'age': '25'}};
final age = ConvertObject.toInt(data, mapKey: 'user', listIndex: null); // ERROR - can't extract nested
final age = ConvertObject.toInt(data['user'], mapKey: 'age'); // 25

// Extract from List
final data = [100, '200', 300];
final num = ConvertObject.toInt(data, listIndex: 1); // 200

// String auto-decode
final json = '{"value": 42}';
final map = ConvertObject.toMap<String, int>(json, decodeInput: true); // {value: 42}
```

### Extension Methods

```dart
// Iterable
list.getInt(0) → int
list.tryGetString(1, altIndexes: [2, 3]) → String?

// Map
map.getString('key', altKeys: ['alt1', 'alt2']) → String
map.tryGetBool('enabled', defaultValue: false) → bool
map.parse('data', UserModel.fromJson) → UserModel

// Collections
[1, '2', 3].convertTo<int>() → [1, 2, 3]
{'a', 'b'}.convertTo<String>() → {'a', 'b'}

// Let chains
'123'.let((s) => int.parse(s) * 2) → 246
nullableValue?.let((v) => process(v)) → Result?
```

### Global Functions

toType<T>(object) → T | throws
tryToType<T>(object) → T?

Supported T: bool, int, BigInt, double, num, String, DateTime

### Conversion Rules

bool: true/false, 'yes'/'true', num > 0
String: toString() on any object
num/int/double: parse numeric strings, convert between number types
BigInt: WARNING - computationally expensive for large values
DateTime: ISO strings, formatted strings, existing DateTime
Uri: valid URI strings, phone numbers → tel: URIs
Map/Set/List: Iterables, single values → collection, empty → empty collection

### Exceptions

ParsingException.nullObject - input was null (for to* methods)
ParsingException - conversion failed
ElementAt errors - invalid list index
Key errors - invalid map key

## Gotchas

- to* methods throw on null, tryTo* methods return null
- BigInt operations expensive - use only when necessary
- mapKey/listIndex extract one level deep only
- format/locale parameters require string input to work
- Collections attempt element-wise conversion if type mismatch
- Phone numbers auto-convert to tel: URIs
- Let extension only processes non-null values
