view release on metacpan or  search on metacpan

docs/EN.AmberDB-Locale_User-Guide.md  view on Meta::CPAN

# 3. Circumflex / accent normalization
$tr->normalize_word("kârın");       # "karin"
$tr->normalize_word("ÂLÎM");        # "alim"

# 4. Word-final consonant devoicing / phonetic assimilation
$tr->normalize_word("tevhid");      # "tevhit"  (d$ => t)
$tr->normalize_word("gazab");       # "gazap"   (b$ => p)
$tr->normalize_word("mehmed");      # "mehmet"  (d$ => t)
```

#### `search_pattern($query)`

Converts a search query string into a locale-aware regex pattern matching regional character variants:

```perl
my $pattern = $tr->search_pattern("Türkiye");
# Produces regex token pattern matching Turkish and ASCII variants (e.g. "t[uü]rk[iıİI]y[eE]")
```

#### `search_regex($string, $pattern)`

Performs a case-insensitive, locale-aware regex match of `$pattern` inside target `$string`. Returns `1` on match, `0` otherwise:

```perl
my $found = $tr->search_regex("İstanbul Boğazı", "istanbul"); # 1
my $match = $tr->search_regex("Ä°zmir Kordon", $pattern);       # 1
```

---

### 5.7 HTML Entity Decoding

#### `decode_entities($string)`

```perl
$lang->decode_entities("& < > € € ç");
# "& < > € € ç"
```

Three stages:
1. **Hex numeric:** `&#x20AC;` → `€`
2. **Decimal numeric:** `&#8364;` → `€`
3. **Named entities:** Universal set (`&amp;`, `&lt;`, `&nbsp;`, `&euro;`, etc.) + locale-specific extras (`&ccedil;`, `&scaron;`, `&gbreve;`, etc.)

---

### 5.8 UTF-8 Safe Substring

#### `substring($string, [$offset], $length)`

```perl
my $tr = AmberDB::Locale->new(language => "tr");
$tr->substring("Çanakkale", 0, 4);     # "Çana"  (4 characters, not 4 bytes!)
$tr->substring("Ä°stanbul", 2, 3);      # "tan"

# Also safe with raw UTF-8 byte strings:
my $raw = encode('UTF-8', "Şanlıurfa");
$tr->substring($raw, 0, 5);            # "Şanlı" (correctly re-encoded)
```

> Checks whether the string is decoded using `Encode::is_utf8()`. If it's raw bytes, the `decode → substr → encode` chain is applied; this prevents multibyte characters from being cut in half.

---

### 5.9 Date/Time Operations

#### `format_date($time [, $pattern_or_style])`

```perl
my $tr = AmberDB::Locale->new(language => "tr");
my $epoch = time();   # e.g.: 2026-08-09

$tr->format_date($epoch);                    # "09.08.2026"
$tr->format_date($epoch, 'medium');          # "9 AÄŸu 2026"
$tr->format_date($epoch, 'long');            # "9 AÄŸustos 2026"
$tr->format_date($epoch, 'full');            # "Pazar, 9 AÄŸustos 2026"
$tr->format_date($epoch, 'time');            # "14:30"
$tr->format_date($epoch, 'datetime');        # "09.08.2026 14:30"

# Custom pattern
$tr->format_date($epoch, 'YYYY-MM-DD');     # "2026-08-09"
$tr->format_date($epoch, 'DD/MM/YYYY');     # "09/08/2026"

# Also accepts date strings
$tr->format_date("2026-08-09", 'full');     # "Pazar, 9 AÄŸustos 2026"
```

**Supported tokens:**

| Token | Meaning | Example |
|---|---|---|
| `YYYY` / `YY` | 4/2-digit year | 2026 / 26 |
| `MMMM` / `MMM` / `MM` / `M` | Month name / short / 2-digit / single | AÄŸustos / AÄŸu / 08 / 8 |
| `DD` / `D` | Day (2-digit / single) | 09 / 9 |
| `dddd` / `ddd` | Day name / short | Pazar / Paz |
| `HH` / `H` | Hour | 14 / 14 |
| `mm` / `m` | Minute | 05 / 5 |
| `ss` / `s` | Second | 09 / 9 |

**Accepted input formats:**
- Unix timestamp: `1786345200`
- Date string: `2026-08-09`, `2026/08/09`, `2026.08.09`
- Date + time: `2026-08-09 14:30:00`, `2026-08-09T14:30`

#### `parse_date($string [, %opts])`

```perl
my $epoch = $tr->parse_date("09.08.2026");            # Unix timestamp
my $h     = $tr->parse_date("09.08.2026", hash => 1);
# { year => 2026, month => 8, day => 9, hour => 0, minute => 0, second => 0 }
```

> The short date format automatically detects whether it's `DD.MM.YYYY` or `MM/DD/YYYY` based on the locale's `date_format.short` value.

---

### 5.10 Number and Currency Formatting

#### `format_number($num [, %opts])`

```perl