# Helpers
## บทนำ
Nylo มาพร้อมกับชุดคลาสอรรถประโยชน์แบบ static — `Arr`, `Str`, `Number` และ `Obj` — รวมถึงฟังก์ชัน helper แบบ global สำหรับงานทั่วไป ทั้งหมดถูก export จาก `nylo_framework`:
``` dart
import 'package:nylo_framework/nylo_framework.dart';
Arr.first([1, 2, 3]); // 1
Str.slug('Hello World'); // 'hello-world'
Number.currency(1234.56); // '$1,234.56'
Obj.get(user, 'profile.name'); // 'Anna'
```
> **หมายเหตุ:** `Backpack`, `NyStorage`, `NyCache` และ `NyLogger` มีหน้าเอกสารเฉพาะของตัวเอง: [Backpack](/docs/7.x/backpack), [Storage](/docs/7.x/storage), [Cache](/docs/7.x/cache), [Logging](/docs/7.x/logging).
## เมธอดที่ใช้ได้
### Arrays
### Strings
### Numbers
### Objects
### เบ็ดเตล็ด
## Arrays
#### `Arr.accessible()`
ตรวจสอบว่าค่าที่กำหนดสามารถเข้าถึงได้เหมือน array หรือไม่ (`List` หรือ `Map`):
``` dart
Arr.accessible([1, 2, 3]); // true
Arr.accessible({'a': 1}); // true
Arr.accessible('hello'); // false
Arr.accessible(null); // false
```
#### `Arr.average()`
คืนค่าเฉลี่ยเลขคณิตของ list หรือ `0` เมื่อว่างเปล่า ใช้ `by` เพื่อดึงตัวเลขจากแต่ละสมาชิก:
``` dart
Arr.average([2, 4, 6]); // 4.0
Arr.average(orders, by: (o) => o.total); // ค่าเฉลี่ยยอดรวม
```
#### `Arr.chunk()`
แบ่ง list ออกเป็นส่วนๆ ตามขนาดที่กำหนด:
``` dart
Arr.chunk([1, 2, 3, 4, 5], 2);
// [[1, 2], [3, 4], [5]]
```
#### `Arr.collapse()`
รวม list ของ list เป็น list เดียว:
``` dart
Arr.collapse([[1, 2], [3, 4], [5]]);
// [1, 2, 3, 4, 5]
```
#### `Arr.countBy()`
นับจำนวนการเกิดขึ้นใน list โดยจัดกลุ่มตาม value extractor ที่ระบุ:
``` dart
Arr.countBy(['a', 'b', 'a', 'c']);
// {'a': 2, 'b': 1, 'c': 1}
Arr.countBy(orders, by: (o) => o.status);
// {'paid': 12, 'pending': 3}
```
#### `Arr.crossJoin()`
Cross-join list ที่กำหนด คืนค่าทุกชุดค่าผสมที่เป็นไปได้:
``` dart
Arr.crossJoin([[1, 2], ['a', 'b']]);
// [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
```
#### `Arr.every()`
คืนค่า `true` เมื่อทุกสมาชิกของ list ผ่าน predicate โดยจะเป็น true เสมอสำหรับ list ว่างเปล่า:
``` dart
Arr.every([2, 4, 6], (n) => n.isEven); // true
Arr.every([1, 2, 3], (n) => n.isEven); // false
```
#### `Arr.exceptValues()`
คืนค่า list โดยนำค่าที่กำหนดออก:
``` dart
Arr.exceptValues([1, 2, 3, 4], [2, 4]); // [1, 3]
```
#### `Arr.first()`
คืนค่าสมาชิกแรกที่ตรงกับ predicate หรือค่า default:
``` dart
Arr.first([1, 2, 3]); // 1
Arr.first([1, 2, 3, 4], predicate: (n) => n.isEven); // 2
Arr.first([], defaultValue: 99); // 99
```
#### `Arr.flatMap()`
map แต่ละสมาชิกผ่าน `fn` และ flatten iterable ที่ได้:
``` dart
Arr.flatMap(pages, (p) => p.items); // รายการทั้งหมดจากทุกหน้า
Arr.flatMap([1, 2, 3], (n) => [n, n * 10]); // [1, 10, 2, 20, 3, 30]
```
#### `Arr.flatten()`
ทำให้ iterable ที่ซ้อนกันแบน เป็น list ระดับเดียว `depth` จำกัดความลึกในการทำให้แบน; `-1` หมายถึงไม่จำกัด:
``` dart
Arr.flatten([1, [2, [3]]]); // [1, 2, 3]
Arr.flatten([1, [2, [3]]], depth: 1); // [1, 2, [3]]
```
#### `Arr.groupBy()`
จัดกลุ่ม list เป็น map โดยใช้ค่าที่คืนโดย `by` เป็น key:
``` dart
Arr.groupBy(messages, (m) => m.date);
// {2024-01-01: [...], 2024-01-02: [...]}
```
#### `Arr.indexed()`
จับคู่แต่ละสมาชิกกับ index คืนค่า list ของ record `(index, value)`:
``` dart
for (final (i, v) in Arr.indexed(['a', 'b', 'c'])) {
print('$i: $v'); // '0: a', '1: b', '2: c'
}
```
#### `Arr.interleave()`
แทรก separator ระหว่างทุกคู่ของสมาชิก มีประโยชน์สำหรับสร้าง widget children ที่มี separator:
``` dart
Arr.interleave([1, 2, 3], 0); // [1, 0, 2, 0, 3]
Column(children: Arr.interleave(tiles, const Divider()));
```
#### `Arr.isAssoc()`
คืนค่า `true` เมื่อค่าเป็น `Map` (associative):
``` dart
Arr.isAssoc({'a': 1}); // true
Arr.isAssoc([1, 2, 3]); // false
```
#### `Arr.isList()`
คืนค่า `true` เมื่อค่าเป็น `List`:
``` dart
Arr.isList([1, 2, 3]); // true
Arr.isList({'a': 1}); // false
```
#### `Arr.join()`
รวม list เป็น string สมาชิกสุดท้ายสามารถรวมด้วย separator ที่แตกต่างกัน:
``` dart
Arr.join(['Anna', 'Brad', 'Carol'], ', ', ' and ');
// 'Anna, Brad and Carol'
Arr.join(['a', 'b', 'c']);
// 'a, b, c'
```
#### `Arr.keyBy()`
จัดทำดัชนี list ตามค่าที่ key ที่ระบุ รายการที่มีค่า `null` ที่ key นั้นจะถูกข้ามไป:
``` dart
Arr.keyBy([
{'id': 1, 'name': 'Anna'},
{'id': 2, 'name': 'Brad'},
], 'id');
// {1: {'id': 1, 'name': 'Anna'}, 2: {'id': 2, 'name': 'Brad'}}
```
#### `Arr.last()`
คืนค่าสมาชิกสุดท้ายที่ตรงกับ predicate หรือค่า default:
``` dart
Arr.last([1, 2, 3, 4], predicate: (n) => n.isEven); // 4
Arr.last([1, 2, 3]); // 3
```
#### `Arr.map()`
map แต่ละสมาชิกผ่าน callback ที่รับ index ด้วย:
``` dart
Arr.map(['a', 'b'], (v, i) => '$i:$v'); // ['0:a', '1:b']
```
#### `Arr.mapWithKeys()`
map แต่ละสมาชิกไปยัง `MapEntry` คืนค่า map ที่ได้:
``` dart
Arr.mapWithKeys(
[{'id': 1, 'name': 'Anna'}, {'id': 2, 'name': 'Brad'}],
(m) => MapEntry(m['id'], m['name']),
);
// {1: 'Anna', 2: 'Brad'}
```
#### `Arr.max()`
คืนค่าสมาชิกที่มีค่า `by` มากที่สุด หรือสมาชิกที่ใหญ่ที่สุดเมื่อไม่ระบุ `by`:
``` dart
Arr.max([3, 1, 4, 1, 5]); // 5
Arr.max(users, by: (u) => u.age); // ผู้ใช้ที่มีอายุมากที่สุด
```
#### `Arr.median()`
คืนค่ามัธยฐานของ list หรือ `0` เมื่อว่างเปล่า:
``` dart
Arr.median([1, 3, 5]); // 3.0
Arr.median([1, 2, 3, 4]); // 2.5
```
#### `Arr.min()`
คืนค่าสมาชิกที่มีค่า `by` น้อยที่สุด หรือสมาชิกที่เล็กที่สุดเมื่อไม่ระบุ `by`:
``` dart
Arr.min([3, 1, 4, 1, 5]); // 1
Arr.min(users, by: (u) => u.age); // ผู้ใช้ที่มีอายุน้อยที่สุด
```
#### `Arr.move()`
คืนค่า list ใหม่โดยย้ายสมาชิกที่ตำแหน่ง `from` ไปยังตำแหน่ง `to` โดย `to` ถูก clamp ให้อยู่ในช่วงที่ถูกต้อง:
``` dart
Arr.move(['a', 'b', 'c', 'd'], 0, 2); // ['b', 'c', 'a', 'd']
```
#### `Arr.onlyValues()`
คืนค่าสมาชิกของ list ที่มีอยู่ในค่าที่กำหนดด้วย:
``` dart
Arr.onlyValues([1, 2, 3, 4], [2, 4, 9]); // [2, 4]
```
#### `Arr.partition()`
แบ่ง list เป็นคู่ `[matching, nonMatching]` ตาม predicate:
``` dart
final [evens, odds] = Arr.partition([1, 2, 3, 4], (n) => n.isEven);
// evens: [2, 4], odds: [1, 3]
```
#### `Arr.pluck()`
ดึงค่าที่ key จากแต่ละ map ใน list:
``` dart
Arr.pluck([
{'name': 'Anna'},
{'name': 'Brad'},
], 'name');
// ['Anna', 'Brad']
```
#### `Arr.prepend()`
คืนค่า list ใหม่โดยแทรกค่าไว้ด้านหน้า:
``` dart
Arr.prepend([2, 3], 1); // [1, 2, 3]
```
#### `Arr.push()`
คืนค่า list ใหม่โดยเพิ่มค่าไว้ท้าย:
``` dart
Arr.push([1, 2], 3); // [1, 2, 3]
```
#### `Arr.random()`
คืนค่าสมาชิกสุ่มของ list จะ throw เมื่อ list ว่างเปล่า:
``` dart
Arr.random(['rock', 'paper', 'scissors']); // หนึ่งในสามตัวเลือก
```
#### `Arr.randomMany()`
คืนค่าสมาชิกสุ่มสูงสุด `count` ตัวโดยไม่ซ้ำ:
``` dart
Arr.randomMany([1, 2, 3, 4, 5], 2); // เช่น [3, 1]
```
#### `Arr.reject()`
กรอง list เหลือสมาชิกที่*ไม่*ตรงกับ predicate (ตรงข้ามกับ [`where`](#method-arr-where)):
``` dart
Arr.reject([1, 2, 3, 4], (n) => n.isEven); // [1, 3]
```
#### `Arr.replaceAt()`
คืนค่า list ใหม่โดยแทนที่สมาชิกที่ `index` ด้วย `value` จะ throw `RangeError` เมื่อ `index` อยู่นอกช่วง:
``` dart
Arr.replaceAt(['a', 'b', 'c'], 1, 'B'); // ['a', 'B', 'c']
```
#### `Arr.select()`
คืนค่าแต่ละ map ใน list ที่ลดเหลือเฉพาะ key ที่กำหนด:
``` dart
Arr.select([
{'name': 'Anna', 'role': 'admin', 'age': 30},
{'name': 'Brad', 'role': 'user', 'age': 25},
], ['name', 'role']);
// [{'name': 'Anna', 'role': 'admin'}, {'name': 'Brad', 'role': 'user'}]
```
#### `Arr.shuffle()`
คืนค่าสำเนาของ list ที่ถูกสุ่ม ใช้ `seed` เพื่อให้ได้ผลลัพธ์ที่แน่นอน:
``` dart
Arr.shuffle([1, 2, 3, 4, 5]);
Arr.shuffle([1, 2, 3], seed: 42); // กำหนดได้แน่นอน
```
#### `Arr.sole()`
คืนค่าสมาชิกเดียวที่ตรงกับ predicate จะ throw เมื่อไม่มีหรือมีมากกว่าหนึ่งสมาชิกที่ตรง:
``` dart
Arr.sole([1, 2, 3, 4], predicate: (n) => n == 3); // 3
Arr.sole([1, 2, 3], predicate: (n) => n.isEven); // 2
```
#### `Arr.some()`
คืนค่า `true` เมื่อมีสมาชิกอย่างน้อยหนึ่งตัวผ่าน predicate:
``` dart
Arr.some([1, 2, 3], (n) => n.isEven); // true
Arr.some([1, 3, 5], (n) => n.isEven); // false
```
#### `Arr.sort()`
คืนค่าสำเนาของ list ที่เรียงลำดับแล้ว:
``` dart
Arr.sort([3, 1, 2]); // [1, 2, 3]
Arr.sort(users, compare: (a, b) => a.age - b.age); // เรียงตามอายุจากน้อยไปมาก
```
#### `Arr.sortDesc()`
คืนค่าสำเนาของ list ที่เรียงลำดับจากมากไปน้อย:
``` dart
Arr.sortDesc([3, 1, 2]); // [3, 2, 1]
```
#### `Arr.sortRecursive()`
เรียงลำดับ list แบบ recursive list ที่ซ้อนกันจะถูกเรียงในทุกความลึก:
``` dart
Arr.sortRecursive([[3, 1, 2], [9, 7, 8]]);
// [[1, 2, 3], [7, 8, 9]]
```
#### `Arr.sum()`
คืนค่าผลรวมของ list ใช้ `by` เพื่อดึงตัวเลขจากแต่ละสมาชิก:
``` dart
Arr.sum([1, 2, 3]); // 6
Arr.sum(orders, by: (o) => o.total); // ผลรวมยอดรวม
```
#### `Arr.swap()`
คืนค่า list ใหม่โดยสลับตำแหน่งสมาชิกที่ `i` และ `j`:
``` dart
Arr.swap(['a', 'b', 'c'], 0, 2); // ['c', 'b', 'a']
```
#### `Arr.take()`
คืนค่าสมาชิก `count` ตัวแรก หรือ `count` ตัวสุดท้ายหาก `count` เป็นลบ:
``` dart
Arr.take([1, 2, 3, 4, 5], 2); // [1, 2]
Arr.take([1, 2, 3, 4, 5], -2); // [4, 5]
```
#### `Arr.unique()`
คืนค่าสมาชิกที่ไม่ซ้ำกันของ list:
``` dart
Arr.unique([1, 2, 2, 3, 1]); // [1, 2, 3]
```
#### `Arr.where()`
กรอง list เหลือสมาชิกที่ตรงกับ predicate:
``` dart
Arr.where([1, 2, 3, 4], (n) => n.isEven); // [2, 4]
```
#### `Arr.whereNotNull()`
คืนค่า list โดยนำค่า `null` ออก:
``` dart
Arr.whereNotNull([1, null, 2, null, 3]); // [1, 2, 3]
```
#### `Arr.wrap()`
ห่อค่าใน `List` หากยังไม่เป็น list คืนค่า list ว่างเมื่อค่าเป็น `null`:
``` dart
Arr.wrap('foo'); // ['foo']
Arr.wrap([1, 2]); // [1, 2]
Arr.wrap(null); // []
```
## Strings
#### `Str.after()`
คืนค่าส่วนของ `subject` หลังการเกิดขึ้นครั้งแรกของ `search`:
``` dart
Str.after('hello world hello', 'hello'); // ' world hello'
```
#### `Str.afterLast()`
คืนค่าส่วนของ `subject` หลังการเกิดขึ้นครั้งสุดท้ายของ `search`:
``` dart
Str.afterLast('app/Http/Controllers', '/'); // 'Controllers'
```
#### `Str.before()`
คืนค่าส่วนของ `subject` ก่อนการเกิดขึ้นครั้งแรกของ `search`:
``` dart
Str.before('hello world', ' '); // 'hello'
```
#### `Str.beforeLast()`
คืนค่าส่วนของ `subject` ก่อนการเกิดขึ้นครั้งสุดท้ายของ `search`:
``` dart
Str.beforeLast('app/Http/Controllers', '/'); // 'app/Http'
```
#### `Str.between()`
คืนค่าส่วนของ `subject` ระหว่าง `from` และ `to` (greedy):
``` dart
Str.between('[a] foo [b]', '[', ']'); // 'a] foo [b'
```
#### `Str.betweenFirst()`
คืนค่าส่วนที่เล็กที่สุดของ `subject` ระหว่าง `from` และ `to`:
``` dart
Str.betweenFirst('[a] foo [b]', '[', ']'); // 'a'
```
#### `Str.camel()`
แปลงค่าเป็น `camelCase`:
``` dart
Str.camel('foo_bar'); // 'fooBar'
Str.camel('Hello world'); // 'helloWorld'
```
#### `Str.charAt()`
คืนค่าอักขระที่ index ที่กำหนด index ลบนับจากท้าย คืนค่า `null` เมื่ออยู่นอกช่วง:
``` dart
Str.charAt('hello', 1); // 'e'
Str.charAt('hello', -1); // 'o'
Str.charAt('hello', 99); // null
```
#### `Str.contains()`
ตรวจสอบว่า `haystack` มี `needles` ใดๆ อยู่หรือไม่:
``` dart
Str.contains('hello world', 'world'); // true
Str.contains('hello world', ['cat', 'world']); // true
Str.contains('Hello', 'hello', ignoreCase: true); // true
```
#### `Str.containsAll()`
ตรวจสอบว่า `haystack` มี `needles` ทั้งหมดอยู่หรือไม่:
``` dart
Str.containsAll('hello world', ['hello', 'world']); // true
Str.containsAll('hello world', ['hello', 'cat']); // false
```
#### `Str.deduplicate()`
แทนที่ `character` ที่ปรากฏต่อเนื่องกันด้วย instance เดียว:
``` dart
Str.deduplicate('hello world'); // 'hello world'
Str.deduplicate('//path//to//', '/'); // '/path/to/'
```
#### `Str.endsWith()`
ตรวจสอบว่า `haystack` ลงท้ายด้วย `needles` ใดๆ หรือไม่:
``` dart
Str.endsWith('app.dart', '.dart'); // true
Str.endsWith('app.dart', ['.dart', '.ts']); // true
```
#### `Str.excerpt()`
ดึงส่วนย่อของข้อความรอบการเกิดขึ้นครั้งแรกของ `phrase` คืนค่า `null` เมื่อไม่พบ phrase:
``` dart
Str.excerpt(
'This is my favorite quote of all time.',
'favorite',
radius: 5,
);
// '...is my favorite quote ...'
```
#### `Str.finish()`
เติม `cap` instance เดียวต่อท้ายค่า:
``` dart
Str.finish('hello', '!'); // 'hello!'
Str.finish('hello!!!', '!'); // 'hello!'
```
#### `Str.headline()`
แยก string เป็นคำตามขอบเขตตัวพิมพ์ใหญ่ เครื่องหมายขีดล่าง ขีดกลาง และช่องว่าง จากนั้นแปลงเป็น title case:
``` dart
Str.headline('steve_jobs'); // 'Steve Jobs'
Str.headline('EmailNotificationSent'); // 'Email Notification Sent'
```
#### `Str.is_()`
ตรวจสอบว่าค่าตรงกับ pattern ที่กำหนดหรือไม่ โดย asterisk ทำหน้าที่เป็น wildcard:
``` dart
Str.is_('foo.*', 'foo.bar'); // true
Str.is_(['admin/*', 'user/*'], 'admin/profile'); // true
Str.is_('foo', 'bar'); // false
```
> **หมายเหตุ:** เครื่องหมายขีดล่างท้ายชื่อเพื่อหลีกเลี่ยง keyword ที่สงวนไว้ของ Dart คือ `is`
#### `Str.isAscii()`
คืนค่า `true` หากค่ามีเฉพาะอักขระ ASCII 7-bit:
``` dart
Str.isAscii('hello'); // true
Str.isAscii('héllo'); // false
```
#### `Str.isJson()`
คืนค่า `true` หากค่าเป็น JSON ที่ถูกต้อง:
``` dart
Str.isJson('{"a": 1}'); // true
Str.isJson('not json'); // false
```
#### `Str.isUlid()`
คืนค่า `true` หากค่าเป็น ULID (26 ตัวอักษร, Crockford base32):
``` dart
Str.isUlid('01ARZ3NDEKTSV4RRFFQ69G5FAV'); // true
Str.isUlid('not a ulid'); // false
```
#### `Str.isUrl()`
คืนค่า `true` หากค่าเป็น URL ที่ถูกต้อง:
``` dart
Str.isUrl('https://nylo.dev'); // true
Str.isUrl('not a url'); // false
```
#### `Str.isUuid()`
คืนค่า `true` หากค่าเป็น UUID ที่ถูกต้อง (ทุก version):
``` dart
Str.isUuid('a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'); // true
Str.isUuid('hello'); // false
```
#### `Str.kebab()`
แปลงค่าเป็น `kebab-case`:
``` dart
Str.kebab('fooBar'); // 'foo-bar'
Str.kebab('Hello World'); // 'hello-world'
```
#### `Str.lcfirst()`
เปลี่ยนอักขระแรกของค่าเป็นตัวพิมพ์เล็ก:
``` dart
Str.lcfirst('Hello world'); // 'hello world'
```
#### `Str.length()`
คืนค่าความยาวของค่า:
``` dart
Str.length('hello'); // 5
```
#### `Str.limit()`
ตัดค่าให้เหลือจำนวนอักขระที่กำหนดและเพิ่ม suffix:
``` dart
Str.limit('A long sentence', 6); // 'A long...'
Str.limit('A long sentence', 6, '... read'); // 'A long... read'
```
#### `Str.lower()`
แปลงค่าเป็นตัวพิมพ์เล็กทั้งหมด:
``` dart
Str.lower('HELLO'); // 'hello'
```
#### `Str.mask()`
ซ่อนส่วนหนึ่งของ string ด้วยอักขระที่กำหนด เริ่มต้นที่ `index` ยาว `length` ตัวอักษร (หรือจนถึงท้ายเมื่อไม่ระบุ `length`):
``` dart
Str.mask('user@example.com', '*', 3); // 'use*************'
Str.mask('user@example.com', '*', 3, 5); // 'use*****mple.com'
```
#### `Str.match()`
คืนค่า regex match แรกของ `pattern` ใน `subject` หรือ `null` เมื่อไม่พบ:
``` dart
Str.match(RegExp(r'\d+'), 'item 42 in 99 stock'); // '42'
```
> **หมายเหตุ:** นี่คือ regex matcher — แตกต่างจาก helper global [`match`](#method-match) ที่ใช้สำหรับการค้นหาค่าแบบ `Map`
#### `Str.matchAll()`
คืนค่า regex match ทั้งหมดของ `pattern` ใน `subject`:
``` dart
Str.matchAll(RegExp(r'\d+'), 'item 42 in 99 stock'); // ['42', '99']
```
#### `Str.padBoth()`
เติม `pad` ทั้งสองด้านของค่าจนถึง `length`:
``` dart
Str.padBoth('5', 5, '0'); // '00500'
```
#### `Str.padLeft()`
เติมด้านซ้ายของค่า:
``` dart
Str.padLeft('5', 3, '0'); // '005'
```
#### `Str.padNumber()`
เติมศูนย์นำหน้า string ตัวเลข:
``` dart
Str.padNumber('5', 3); // '005'
```
#### `Str.padRight()`
เติมด้านขวาของค่า:
``` dart
Str.padRight('5', 3, '0'); // '500'
```
#### `Str.password()`
สร้างรหัสผ่านแบบสุ่มที่ปลอดภัยด้านการเข้ารหัส สลับ character class ผ่าน named arguments:
``` dart
Str.password(12); // ตัวอักษร + ตัวเลข + สัญลักษณ์
Str.password(12, symbols: false); // ตัวอักษร + ตัวเลขเท่านั้น
Str.password(8, letters: false, symbols: false); // ตัวเลขเท่านั้น
```
#### `Str.position()`
คืนค่า index ของการเกิดขึ้นครั้งแรกของ `needle` ใน `haystack` หรือ `null` เมื่อไม่พบ:
``` dart
Str.position('hello world', 'world'); // 6
Str.position('hello world hello', 'hello', offset: 1); // 12
Str.position('hello', 'cat'); // null
```
#### `Str.random()`
สร้าง string alphanumeric แบบสุ่มที่ปลอดภัยด้านการเข้ารหัสตามความยาวที่กำหนด:
``` dart
Str.random(); // 16 ตัวอักษร เช่น 'aB3k9XzMq7VnPsRt'
Str.random(8); // 8 ตัวอักษร
```
#### `Str.remove()`
นำ `search` ใดๆ ออกจาก `subject`:
``` dart
Str.remove('o', 'hello world'); // 'hell wrld'
Str.remove(['e', 'l'], 'hello world'); // 'ho word'
Str.remove('Hello', 'hello world', caseSensitive: false); // ' world'
```
#### `Str.repeat()`
ทำซ้ำค่าตามจำนวนที่กำหนด:
``` dart
Str.repeat('ab', 3); // 'ababab'
```
#### `Str.replace()`
แทนที่ทุกการเกิดขึ้นของ `search` ด้วย `replace` ใน `subject`:
``` dart
Str.replace('o', '0', 'hello world'); // 'hell0 w0rld'
Str.replace(['o', 'l'], '*', 'hello world'); // 'he*** w*r*d'
```
#### `Str.replaceFirst()`
แทนที่การเกิดขึ้นครั้งแรกของ `search` ด้วย `replace`:
``` dart
Str.replaceFirst('hello', 'hi', 'hello hello'); // 'hi hello'
```
#### `Str.replaceLast()`
แทนที่การเกิดขึ้นครั้งสุดท้ายของ `search` ด้วย `replace`:
``` dart
Str.replaceLast('hello', 'hi', 'hello hello'); // 'hello hi'
```
#### `Str.reverse()`
กลับทิศทางค่า:
``` dart
Str.reverse('hello'); // 'olleh'
```
#### `Str.slug()`
สร้าง slug ที่เป็นมิตรกับ URL จากชื่อเรื่อง:
``` dart
Str.slug('Hello World'); // 'hello-world'
Str.slug('Tech & Code', dictionary: {'&': 'and'}); // 'tech-and-code'
Str.slug('Hello World', separator: '_'); // 'hello_world'
```
#### `Str.snake()`
แปลงค่าเป็น `snake_case` ใช้ delimiter กำหนดเองเพื่อใช้สิ่งอื่นนอกจาก `_`:
``` dart
Str.snake('helloWorld'); // 'hello_world'
Str.snake('helloWorld', '-'); // 'hello-world'
```
#### `Str.squish()`
ตัด whitespace นำหน้า/ท้าย และยุบ whitespace ภายในเป็น space เดียว:
``` dart
Str.squish(' hello world '); // 'hello world'
```
#### `Str.start()`
เริ่มต้นค่าด้วย `prefix` instance เดียว:
``` dart
Str.start('this/string', '/'); // '/this/string'
Str.start('//this/string', '/'); // '/this/string'
```
#### `Str.startsWith()`
ตรวจสอบว่า `haystack` เริ่มต้นด้วย `needles` ใดๆ หรือไม่:
``` dart
Str.startsWith('hello world', 'hello'); // true
Str.startsWith('hello world', ['cat', 'hello']); // true
```
#### `Str.studly()`
แปลงค่าเป็น `StudlyCase` / `PascalCase`:
``` dart
Str.studly('foo_bar'); // 'FooBar'
Str.studly('hello world'); // 'HelloWorld'
```
#### `Str.substr()`
คืนค่า substring เริ่มต้นที่ `start` ยาว `length` อักขระ `start` ลบนับจากท้าย:
``` dart
Str.substr('profile', 4); // 'ile'
Str.substr('profile', 4, 2); // 'il'
Str.substr('profile', -3); // 'ile'
```
#### `Str.substrCount()`
นับการเกิดขึ้นของ `needle` ที่ไม่ทับซ้อนกันใน `haystack`:
``` dart
Str.substrCount('hello hello hello', 'hello'); // 3
```
#### `Str.swap()`
แทนที่หลาย substring โดยใช้ `Map` ของคู่ค้นหา → แทนที่:
``` dart
Str.swap({'foo': 'bar', 'hello': 'hi'}, 'hello foo'); // 'hi bar'
```
#### `Str.take()`
คืนค่า `limit` อักขระแรกของค่า limit ลบคืนค่าจากท้าย:
``` dart
Str.take('Build something amazing!', 5); // 'Build'
Str.take('Build something amazing!', -9); // ' amazing!'
```
#### `Str.title()`
แปลงค่าเป็น `Title Case`:
``` dart
Str.title('a nice title'); // 'A Nice Title'
```
#### `Str.ucfirst()`
เปลี่ยนอักขระแรกของค่าเป็นตัวพิมพ์ใหญ่:
``` dart
Str.ucfirst('hello world'); // 'Hello world'
```
#### `Str.ucsplit()`
แยกค่าเป็นคำตามขอบเขตตัวพิมพ์ใหญ่:
``` dart
Str.ucsplit('fooBarBaz'); // ['foo', 'Bar', 'Baz']
```
#### `Str.ulid()`
สร้าง ULID (Universally Unique Lexicographically Sortable Identifier):
``` dart
Str.ulid(); // เช่น '01ARZ3NDEKTSV4RRFFQ69G5FAV'
```
#### `Str.unwrap()`
นำ `before` instance เดียวออกจากต้น และ `after` (หรือ `before` หาก `after` เป็น null) จากท้าย:
``` dart
Str.unwrap('"value"', '"'); // 'value'
Str.unwrap('html
', '', '
'); // 'html'
```
#### `Str.upper()`
แปลงค่าเป็นตัวพิมพ์ใหญ่ทั้งหมด:
``` dart
Str.upper('hello'); // 'HELLO'
```
#### `Str.uuid()`
สร้าง UUID v4 แบบสุ่ม:
``` dart
Str.uuid(); // เช่น 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'
```
#### `Str.uuid7()`
สร้าง UUID v7 (time-ordered, RFC 9562) UUIDv7 สามารถเรียงลำดับตามเวลาที่สร้าง:
``` dart
Str.uuid7(); // เช่น '018e0dc4-8b3f-7a2c-9d01-b1f6c87a92e3'
```
#### `Str.wordCount()`
คืนค่าจำนวนคำของค่า:
``` dart
Str.wordCount('hello there friend'); // 3
```
#### `Str.words()`
จำกัดค่าให้เหลือจำนวนคำที่กำหนด:
``` dart
Str.words('Perfectly balanced, as all things should be.', 3);
// 'Perfectly balanced, as...'
```
#### `Str.wrap()`
ห่อค่าด้วย `before` และ `after` เมื่อไม่ระบุ `after` จะใช้ `before` ทั้งสองด้าน:
``` dart
Str.wrap('value', '"'); // '"value"'
Str.wrap('html', '', '
'); // 'html
'
```
## Numbers
#### `Number.abbreviate()`
คืนค่ารูปแบบย่อของตัวเลข (`1K`, `1M`, `1B`):
``` dart
Number.abbreviate(1500); // '2K'
Number.abbreviate(1500, maxPrecision: 1); // '1.5K'
Number.abbreviate(2_500_000); // '3M'
```
#### `Number.average()`
คืนค่าเฉลี่ยเลขคณิตของค่าต่างๆ หรือ `0` เมื่อว่างเปล่า:
``` dart
Number.average([1, 2, 3, 4]); // 2.5
```
#### `Number.between()`
คืนค่า `true` เมื่อค่าอยู่ระหว่าง `min` และ `max` (inclusive):
``` dart
Number.between(5, min: 0, max: 10); // true
Number.between(15, min: 0, max: 10); // false
```
#### `Number.ceil()`
ปัดเศษขึ้นของค่าตามความแม่นยำที่กำหนด:
``` dart
Number.ceil(1.2); // 2.0
Number.ceil(1.234, 2); // 1.24
```
#### `Number.clamp()`
จำกัดค่าให้อยู่ระหว่าง `min` และ `max` (inclusive):
``` dart
Number.clamp(5, 0, 10); // 5
Number.clamp(15, 0, 10); // 10
Number.clamp(-1, 0, 10); // 0
```
#### `Number.currency()`
จัดรูปแบบตัวเลขเป็นค่าสกุลเงิน ใช้ locale และสกุลเงินที่กำหนดค่าไว้เป็นค่าเริ่มต้น:
``` dart
Number.currency(1234.56); // '$1,234.56'
Number.currency(1234.56, currency: 'EUR'); // '€1,234.56'
Number.currency(1234.56, locale: 'de_DE', currency: 'EUR');
// '1.234,56 €'
```
#### `Number.defaultCurrency()`
คืนค่ารหัสสกุลเงินเริ่มต้นที่ใช้โดยเมธอดการจัดรูปแบบ:
``` dart
Number.defaultCurrency(); // 'USD'
```
#### `Number.defaultLocale()`
คืนค่า locale เริ่มต้นที่ใช้โดยเมธอดการจัดรูปแบบ:
``` dart
Number.defaultLocale(); // 'en_US'
```
#### `Number.degrees()`
แปลง radian เป็นองศา:
``` dart
Number.degrees(3.14159); // ~180.0
```
#### `Number.duration()`
จัดรูปแบบจำนวนวินาทีเป็นช่วงเวลาที่อ่านได้ รูปแบบสั้นคืน `'1h 2m 5s'`; รูปแบบยาวคืน `'1:02:05'`:
``` dart
Number.duration(3661); // '1h 1m 1s'
Number.duration(3661, short: false); // '1:01:01'
Number.duration(45); // '45s'
```
#### `Number.fileSize()`
จัดรูปแบบจำนวน byte เป็นขนาดไฟล์ที่อ่านได้:
``` dart
Number.fileSize(1024); // '1 KB'
Number.fileSize(1500, maxPrecision: 1); // '1.5 KB'
Number.fileSize(1024 * 1024 * 1024); // '1 GB'
```
#### `Number.floor()`
ปัดเศษลงของค่าตามความแม่นยำที่กำหนด:
``` dart
Number.floor(1.7); // 1.0
Number.floor(1.234, 2); // 1.23
```
#### `Number.forHumans()`
คืนค่ารูปแบบตัวเลขที่อ่านได้ (`1 thousand`, `1 million`):
``` dart
Number.forHumans(1500); // '2 thousand'
Number.forHumans(1500, maxPrecision: 1); // '1.5 thousand'
Number.forHumans(2_500_000); // '3 million'
```
#### `Number.format()`
จัดรูปแบบตัวเลขด้วยตัวคั่นที่รองรับ locale:
``` dart
Number.format(1234567); // '1,234,567'
Number.format(1234.5, precision: 2); // '1,234.50'
Number.format(1234567, locale: 'de_DE'); // '1.234.567'
```
#### `Number.gcd()`
ตัวหารร่วมมากของจำนวนเต็มสองจำนวน:
``` dart
Number.gcd(12, 18); // 6
```
#### `Number.lcm()`
ตัวคูณร่วมน้อยของจำนวนเต็มสองจำนวน:
``` dart
Number.lcm(4, 6); // 12
```
#### `Number.lerp()`
interpolation เชิงเส้นระหว่าง `a` และ `b` ด้วย `t` (`0..1`):
``` dart
Number.lerp(0, 100, 0.25); // 25.0
```
#### `Number.max()`
คืนค่าที่มากที่สุดใน iterable:
``` dart
Number.max([3, 1, 4, 1, 5, 9, 2, 6]); // 9
```
#### `Number.median()`
คืนค่ามัธยฐานของค่าต่างๆ หรือ `0` เมื่อว่างเปล่า:
``` dart
Number.median([1, 3, 5]); // 3.0
Number.median([1, 2, 3, 4]); // 2.5
```
#### `Number.min()`
คืนค่าที่น้อยที่สุดใน iterable:
``` dart
Number.min([3, 1, 4, 1, 5, 9, 2, 6]); // 1
```
#### `Number.ordinal()`
คืนค่ารูปแบบ ordinal ของตัวเลข (`1st`, `2nd`, `3rd`, `4th`):
``` dart
Number.ordinal(1); // '1st'
Number.ordinal(2); // '2nd'
Number.ordinal(21); // '21st'
Number.ordinal(112); // '112th'
```
#### `Number.pairs()`
สร้างคู่ (sub-range) จาก range ถึง `to` โดย step ด้วย `by`:
``` dart
Number.pairs(25, 10); // [[0, 9], [10, 19], [20, 25]]
Number.pairs(25, 10, offset: 0); // [[0, 10], [10, 20], [20, 25]]
```
#### `Number.parseFloat()`
แปลง string ที่รองรับ locale เป็น `double` คืนค่า `null` เมื่อล้มเหลว:
``` dart
Number.parseFloat('1,234.56'); // 1234.56
Number.parseFloat('1.234,56', locale: 'de_DE'); // 1234.56
Number.parseFloat('not a number'); // null
```
#### `Number.parseInt()`
แปลง string ที่รองรับ locale เป็น `int` คืนค่า `null` เมื่อล้มเหลว:
``` dart
Number.parseInt('1,234'); // 1234
Number.parseInt('1.234', locale: 'de_DE'); // 1234
```
#### `Number.percentage()`
จัดรูปแบบตัวเลขเป็นเปอร์เซ็นต์ ตัวเลขถือเป็นค่าเปอร์เซ็นต์เต็ม:
``` dart
Number.percentage(10); // '10%'
Number.percentage(10.5, precision: 1); // '10.5%'
```
#### `Number.radians()`
แปลงองศาเป็น radian:
``` dart
Number.radians(180); // ~3.14159
```
#### `Number.random()`
คืนค่าจำนวนเต็มสุ่มใน `[min, max]` (inclusive) ใช้ `seed` เพื่อได้ลำดับที่กำหนดได้:
``` dart
Number.random(min: 1, max: 100); // int ใดก็ได้ 1..100
Number.random(min: 0, max: 9, seed: 42); // กำหนดได้แน่นอน
```
#### `Number.range()`
สร้าง list ของจำนวนเต็มจาก `start` (inclusive) ถึง `end` (inclusive) โดย step ด้วย `step`:
``` dart
Number.range(1, 5); // [1, 2, 3, 4, 5]
Number.range(0, 10, step: 2); // [0, 2, 4, 6, 8, 10]
Number.range(5, 1, step: -1); // [5, 4, 3, 2, 1]
```
#### `Number.round()`
ปัดเศษค่าตามความแม่นยำที่กำหนด:
``` dart
Number.round(1.5); // 2.0
Number.round(1.234, 2); // 1.23
```
#### `Number.scale()`
re-map ค่าจาก range หนึ่งไปยังอีก range หนึ่ง:
``` dart
Number.scale(0.5, fromMin: 0, fromMax: 1, toMin: 0, toMax: 100); // 50.0
Number.scale(75, fromMin: 0, fromMax: 100, toMin: -1, toMax: 1); // 0.5
```
#### `Number.spell()`
เขียนตัวเลขเป็นคำในภาษาอังกฤษ:
``` dart
Number.spell(0); // 'zero'
Number.spell(123); // 'one hundred twenty-three'
Number.spell(1_234_567); // 'one million two hundred thirty-four thousand five hundred sixty-seven'
```
#### `Number.spellOrdinal()`
เขียนรูปแบบ ordinal ของตัวเลขเป็นคำในภาษาอังกฤษ:
``` dart
Number.spellOrdinal(1); // 'first'
Number.spellOrdinal(2); // 'second'
Number.spellOrdinal(21); // 'twenty-first'
```
#### `Number.sum()`
คืนค่าผลรวมของค่าต่างๆ:
``` dart
Number.sum([1, 2, 3]); // 6
```
#### `Number.toBytes()`
แปลงขนาดไฟล์เป็น byte ตรงข้ามกับ [`fileSize`](#method-number-filesize) ใช้ string ที่แปลงได้หรือตัวเลขพร้อม `unit`:
``` dart
Number.toBytes('1.5 KB'); // 1536
Number.toBytes(1.5, 'KB'); // 1536
Number.toBytes(1, 'GB'); // 1073741824
Number.toBytes('not bytes'); // null
```
#### `Number.trim()`
นำศูนย์ท้ายออกจากส่วนทศนิยมของค่า:
``` dart
Number.trim(12.0); // '12'
Number.trim(12.30); // '12.3'
Number.trim(12.345); // '12.345'
```
#### `Number.useCurrency()`
กำหนดรหัสสกุลเงินเริ่มต้นที่ใช้โดยเมธอดการจัดรูปแบบ:
``` dart
Number.useCurrency('EUR');
Number.currency(99); // '€99.00'
```
#### `Number.useLocale()`
กำหนด locale เริ่มต้นที่ใช้โดยเมธอดการจัดรูปแบบ:
``` dart
Number.useLocale('de_DE');
Number.format(1234567); // '1.234.567'
```
## Objects
`Obj` มีเครื่องมือสำหรับทำงานกับ map โดยใช้ path แบบ **dot-notation** สมาชิกของ List สามารถระบุด้วย integer index ได้ (เช่น `'users.0.name'`)
#### `Obj.add()`
เพิ่มค่าที่ `key` เฉพาะเมื่อยังไม่มีค่าอยู่ที่นั่น:
``` dart
final user = {'name': 'Anna'};
Obj.add(user, 'role', 'admin');
// user: {'name': 'Anna', 'role': 'admin'}
Obj.add(user, 'name', 'Brad'); // no-op — name มีค่าอยู่แล้ว
```
#### `Obj.deepEquals()`
คืนค่า `true` เมื่อสองค่ามีโครงสร้างเท่ากัน (เปรียบเทียบ recursive ของ `Map` และ `List`):
``` dart
Obj.deepEquals({'a': [1, 2]}, {'a': [1, 2]}); // true
Obj.deepEquals({'a': 1}, {'a': 2}); // false
```
#### `Obj.divide()`
แบ่ง map เป็นคู่ `[keys, values]`:
``` dart
Obj.divide({'name': 'Desk', 'price': 100});
// [['name', 'price'], ['Desk', 100]]
```
#### `Obj.dot()`
ทำให้ map ที่ซ้อนกันแบนเป็น map ระดับเดียวที่ใช้ dot-path เป็น key:
``` dart
Obj.dot({'a': {'b': 1, 'c': 2}});
// {'a.b': 1, 'a.c': 2}
```
#### `Obj.except()`
คืนค่า map ใหม่ที่มีทุก entry ยกเว้นที่มี key ที่กำหนด:
``` dart
Obj.except({'name': 'Anna', 'role': 'admin', 'age': 30}, ['age']);
// {'name': 'Anna', 'role': 'admin'}
```
#### `Obj.exists()`
คืนค่า `true` เมื่อ map มี key ที่กำหนดอยู่ที่ระดับบนสุด (ไม่ใช่การ traverse ด้วย dot-notation):
``` dart
Obj.exists({'a.b': 1}, 'a.b'); // true
Obj.exists({'a': {'b': 1}}, 'a.b'); // false (ใช้ `has` สำหรับการ traverse)
```
#### `Obj.flip()`
สลับ key และ value เมื่อ value ซ้ำกัน entry สุดท้ายจะชนะ:
``` dart
Obj.flip({'one': 1, 'two': 2}); // {1: 'one', 2: 'two'}
```
#### `Obj.forget()`
นำ key (dot notation) ออกจาก map คืนค่า map เพื่อ chaining:
``` dart
final user = {'profile': {'name': 'Anna', 'email': 'a@b'}};
Obj.forget(user, 'profile.email');
// user: {'profile': {'name': 'Anna'}}
```
#### `Obj.get()`
คืนค่าที่ `key` โดยใช้ dot notation หรือค่า default เมื่อ path ไม่มีอยู่ Key ระดับบนสุดที่มีจุดจริงมีความสำคัญกว่าการ traverse:
``` dart
final user = {'profile': {'name': 'Anna', 'age': 30}};
Obj.get(user, 'profile.name'); // 'Anna'
Obj.get(user, 'profile.email'); // null
Obj.get(user, 'profile.email', 'unknown'); // 'unknown'
// List indices:
Obj.get({'users': [{'name': 'A'}]}, 'users.0.name'); // 'A'
```
#### `Obj.getBool()`
คืนค่าที่ `key` โดยแปลงเป็น `bool` หรือค่า default ตัวเลขเป็น truthy เมื่อไม่ใช่ศูนย์; string รู้จัก `'true'`/`'false'`/`'1'`/`'0'`/`'yes'`/`'no'`/`'on'`/`'off'` (case-insensitive):
``` dart
Obj.getBool({'flag': 'yes'}, 'flag'); // true
Obj.getBool({'flag': 0}, 'flag'); // false
Obj.getBool({}, 'flag', false); // false
```
#### `Obj.getDouble()`
คืนค่าที่ `key` โดยแปลงเป็น `double` หรือค่า default:
``` dart
Obj.getDouble({'price': '9.99'}, 'price'); // 9.99
Obj.getDouble({'price': 10}, 'price'); // 10.0
```
#### `Obj.getInt()`
คืนค่าที่ `key` โดยแปลงเป็น `int` หรือค่า default:
``` dart
Obj.getInt({'count': '42'}, 'count'); // 42
Obj.getInt({'count': 3.7}, 'count'); // 3 (ตัดทศนิยม)
Obj.getInt({}, 'count', 0); // 0
```
#### `Obj.getList()`
คืนค่าที่ `key` เมื่อเป็น `List` มิฉะนั้นคืนค่า default:
``` dart
Obj.getList({'items': [1, 2, 3]}, 'items'); // [1, 2, 3]
Obj.getList({'items': 'oops'}, 'items', []); // []
```
#### `Obj.getMap()`
คืนค่าที่ `key` เมื่อเป็น `Map` มิฉะนั้นคืนค่า default:
``` dart
Obj.getMap({'meta': {'a': 1}}, 'meta'); // {'a': 1}
Obj.getMap({'meta': null}, 'meta', {}); // {}
```
#### `Obj.getString()`
คืนค่าที่ `key` โดยแปลงเป็น `String` หรือค่า default:
``` dart
Obj.getString({'name': 'Anna'}, 'name'); // 'Anna'
Obj.getString({'count': 42}, 'count'); // '42'
Obj.getString({}, 'name', 'Guest'); // 'Guest'
```
#### `Obj.has()`
คืนค่า `true` เมื่อ map มีค่าที่ `key` โดยใช้ dot notation:
``` dart
final user = {'profile': {'name': 'Anna'}};
Obj.has(user, 'profile.name'); // true
Obj.has(user, 'profile.email'); // false
```
#### `Obj.hasAll()`
คืนค่า `true` เมื่อทุก key ที่กำหนด resolve ได้ใน map:
``` dart
Obj.hasAll({'a': 1, 'b': 2}, ['a', 'b']); // true
Obj.hasAll({'a': 1, 'b': 2}, ['a', 'c']); // false
```
#### `Obj.hasAny()`
คืนค่า `true` เมื่อ key ใดๆ ที่กำหนด resolve ได้ใน map:
``` dart
Obj.hasAny({'a': 1}, ['a', 'b']); // true
Obj.hasAny({'a': 1}, ['x', 'y']); // false
```
#### `Obj.mapKeys()`
คืนค่า map ใหม่โดยแต่ละ key ถูก transform ด้วย `fn`:
``` dart
Obj.mapKeys({'firstName': 'Anna'}, (k) => k.toLowerCase());
// {'firstname': 'Anna'}
```
#### `Obj.mapValues()`
คืนค่า map ใหม่โดยแต่ละ value ถูก transform ด้วย `fn`:
``` dart
Obj.mapValues({'a': 1, 'b': 2}, (v) => v * 10);
// {'a': 10, 'b': 20}
```
#### `Obj.merge()`
รวม `source` เข้ากับ `target` แบบ recursive เมื่อ key ซ้ำ `source` ชนะ; map ที่ซ้อนกันจะถูกรวม:
``` dart
Obj.merge(
{'a': {'x': 1}, 'b': 2},
{'a': {'y': 9}, 'b': 22},
);
// {'a': {'x': 1, 'y': 9}, 'b': 22}
```
#### `Obj.only()`
คืนค่า map ใหม่ที่มีเฉพาะ entry ที่มี key ที่กำหนด:
``` dart
Obj.only({'name': 'Anna', 'role': 'admin', 'age': 30}, ['name', 'role']);
// {'name': 'Anna', 'role': 'admin'}
```
#### `Obj.prependKeysWith()`
เติม prefix ให้ทุก key ระดับบนสุดใน map:
``` dart
Obj.prependKeysWith({'name': 'Anna', 'age': 30}, 'user_');
// {'user_name': 'Anna', 'user_age': 30}
```
#### `Obj.pull()`
คืนค่าที่ `key` และนำออกจาก map:
``` dart
final user = {'name': 'Anna', 'temp': 'token'};
final temp = Obj.pull(user, 'temp'); // 'token'
// user: {'name': 'Anna'}
```
#### `Obj.query()`
encode map เป็น URL query string:
``` dart
Obj.query({'name': 'Anna', 'tags': ['a', 'b']});
// 'name=Anna&tags%5B0%5D=a&tags%5B1%5D=b'
Obj.query({'filter': {'role': 'admin'}});
// 'filter%5Brole%5D=admin'
```
#### `Obj.set()`
กำหนดค่าที่ `key` โดยสร้าง map ที่ซ้อนกันตาม path mutate map ใน place และคืนค่าเพื่อ chaining:
``` dart
final user = {};
Obj.set(user, 'profile.email', 'a@b');
// user: {'profile': {'email': 'a@b'}}
```
#### `Obj.undot()`
ขยาย map ที่มี key แบบจุดกลับเป็นโครงสร้างซ้อนกัน (ตรงข้ามกับ [`dot`](#method-obj-dot)):
``` dart
Obj.undot({'a.b': 1, 'a.c': 2});
// {'a': {'b': 1, 'c': 2}}
```
#### `Obj.whereNotEmpty()`
คืนค่า map ใหม่โดยนำ entry ที่มีค่า `null` หรือว่างเปล่า (`String`, `Iterable` หรือ `Map` ว่างเปล่า) ออก:
``` dart
Obj.whereNotEmpty({'name': 'Anna', 'tags': [], 'bio': ''});
// {'name': 'Anna'}
```
#### `Obj.whereNotNull()`
คืนค่า map ใหม่โดยนำ entry ที่มีค่า `null` ออก:
``` dart
Obj.whereNotNull({'name': 'Anna', 'email': null});
// {'name': 'Anna'}
```
## เบ็ดเตล็ด
ฟังก์ชัน global เหล่านี้อยู่ใน `helper.dart` และสามารถใช้ได้ทุกที่ที่ import `nylo_framework`
#### `api()`
helper ลัดสำหรับส่ง API request ผ่าน `NyApiService` ดูหน้า [Networking](/docs/7.x/networking) สำหรับตัวเลือกทั้งหมด:
``` dart
await api((request) =>
request.get('https://jsonplaceholder.typicode.com/posts'));
```
#### `dataToModel()`
แปลง raw data (โดยทั่วไปเป็น JSON `Map`) เป็น model ที่ลงทะเบียนใน `config/decoders.dart` type parameter เป็นสิ่งจำเป็น:
``` dart
final user = dataToModel(data: {'name': 'Anna', 'age': 30});
```
#### `dump()`
แสดงค่าบน console เคารพ flag `APP_DEBUG` ของแอป เว้นแต่ `alwaysPrint: true`:
``` dart
dump('Hello World');
dump(user, tag: 'current user');
dump(payload, alwaysPrint: true);
```
#### `event()`
เรียก event ของ type ที่กำหนดโดยใช้ `Nylo.events()` ดู [Events](/docs/7.x/events) สำหรับการใช้งานทั้งหมด:
``` dart
await event(data: {'user': 'Anna'});
```
#### `getAsset()`
คืนค่า path เต็มสำหรับ asset ในไดเรกทอรี `/assets`:
``` dart
final path = getAsset('videos/welcome.mp4');
// 'assets/videos/welcome.mp4'
```
#### `getEnv()`
คืนค่าจาก env ที่สร้างขึ้น (`env.g.dart`) คืนค่า default เมื่อ key ไม่ถูกตั้งค่า:
``` dart
final apiUrl = getEnv('API_URL');
final debug = getEnv('APP_DEBUG', defaultValue: false);
```
#### `getImageAsset()`
คืนค่า path เต็มสำหรับรูปภาพใน `/assets/images/`:
``` dart
Image.asset(getImageAsset('logo.png'));
```
#### `loadJson()`
โหลดไฟล์ JSON จาก assets bundle ผลลัพธ์ถูก cache ไว้โดยค่าเริ่มต้น:
``` dart
final config = await loadJson>('config/app.json');
```
#### `match()`
จับคู่ค่ากับ `Map` ของ case และคืนค่าที่สอดคล้องกัน throw เมื่อไม่มี case ที่ตรงและไม่มี `defaultValue`:
``` dart
final color = match(
status,
() => {
'active': 'green',
'inactive': 'red',
'pending': 'orange',
},
defaultValue: 'grey',
);
```
> **หมายเหตุ:** นี่คือการค้นหาค่าแบบ `Map` — แตกต่างจาก [`Str.match`](#method-str-match) ที่ทำ regex matching
#### `now()`
คืนค่า `DateTime` ปัจจุบัน:
``` dart
final timestamp = now();
```
#### `nyHexColor()`
แปลง string สีในรูปแบบ hex เป็น `Color` รับค่า 6 หรือ 8 หลัก พร้อมหรือไม่มี `#` นำหน้า:
``` dart
final brand = nyHexColor('#FF6B35');
final translucent = nyHexColor('80FF6B35'); // 8 หลัก (alpha ก่อน)
```
#### `printDebug()`, `printError()`, `printInfo()`, `printWarning()`, `printSuccess()`, `printVerbose()`, `printAlert()`, `printEmergency()`
logger ที่ติดแท็ก severity บน console ดูหน้า [Logging](/docs/7.x/logging) สำหรับการจัดรูปแบบ output และ flag `alwaysPrint`:
``` dart
printInfo('User signed in');
printError('Payment failed', context: {'order_id': 42});
printDebug({'state': state});
```
#### `setBadgeNumber()`, `clearBadgeNumber()`
กำหนดหรือล้างจำนวน badge ของไอคอนแอป ดู [Local Notifications](/docs/7.x/local-notifications) สำหรับรายละเอียดการตั้งค่า platform:
``` dart
await setBadgeNumber(3);
await clearBadgeNumber();
```
#### `showNextLog()`
บังคับให้ log `NyLogger` ถัดไปแสดงแม้ `APP_DEBUG` เป็น `false` มีประโยชน์สำหรับ diagnostic ครั้งเดียวใน release build:
``` dart
showNextLog();
NyLogger.info('This will print regardless of APP_DEBUG');
```
#### `sleep()`
หน่วงการทำงานตาม duration ที่กำหนด argument แรกคือวินาที; argument ที่สองเป็นตัวเลือกเพิ่ม microsecond:
``` dart
await sleep(2); // 2 วินาที
await sleep(0, 500_000); // 500 มิลลิวินาที
```
#### `trans()`
คืนค่า string ที่แปลแล้วตาม key ดู [Localization](/docs/7.x/localization) สำหรับการตั้งค่า:
``` dart
final greeting = trans('home.welcome');
final personalized = trans('home.hello', arguments: {'name': 'Anna'});
```