toPersianDigits

⚠️ Version Recommendation: Always install and use the latest version of rtl-text-tools (npm install rtl-text-tools@latest). While this specific feature was introduced in an earlier version, the latest release includes crucial bug fixes, better edge-case handling, and improved legacy browser compatibility. Avoid pinning your project to an old version just to use this function.

Converts standard Latin digits (0-9) into Extended Persian numerals (۰-۹). This is the standard digit format used in Persian (Farsi), Urdu, Dari, and Pashto locales.

(Note: If you need Arabic/Egyptian digits instead, use toArabicDigits(). If you are using the main fixRTL() function, Persian digits are applied automatically by default.)

📝 Syntax

toPersianDigits(text: string): string

Parameters

Name	Type	Description
text	string	The text containing Latin digits to convert.

Returns

• string : The text with all Latin digits replaced by Persian-Indic numerals. Returns the original string unchanged if it is empty, null, or contains no digits.

💡 Examples

Basic Usage

import { toPersianDigits } from 'rtl-text-tools';

toPersianDigits("Price 123");     // "Price ۱۲۳"
toPersianDigits("Year 2024");     // "Year ۲۰۲۴"
toPersianDigits("Hello world");   // "Hello world" (No digits to convert)
toPersianDigits("");              // "" (Empty string)

Mixed Content

It safely ignores non-digit characters and only transforms the numbers:

import { toPersianDigits } from 'rtl-text-tools';

toPersianDigits("Total: $50.00"); 
// Output: "Total: $۵۰.۰۰"

⚙️ Technical Details & Compatibility

• IE11 Compatibility: The function uses the standard String.prototype.replace() method with a regular expression and a callback function. It intentionally avoids modern methods like String.prototype.replaceAll() to ensure full compatibility with legacy browsers like IE11.
• Performance: It uses a direct character lookup map (PERSIAN_DIGITS) inside the replace callback, making the conversion extremely fast even for large strings.
• Safe Execution: If the input is falsy (e.g., null, undefined, or ""), it immediately returns the input without throwing an error.

📜 Version History

• v0.2.0: Added toPersianDigits() to convert Latin numbers to Persian numerals (۰-۹).