Documentation Index
Fetch the complete documentation index at: https://persian-tools.usestrict.dev/llms.txt
Use this file to discover all available pages before exploring further.
Comma Formatting
The comma formatting utilities help you add or remove thousands separators in numeric values for better readability.
Available Functions
Add Commas
addCommas() - Add thousands separators
Remove Commas
removeCommas() - Remove thousands separators
Basic Usage
import { addCommas, removeCommas } from '@persian-tools/persian-tools';
Adding Commas
Format numbers with thousands separators for improved readability:
addCommas(1234); // "1,234"
addCommas(1234567); // "1,234,567"
addCommas(1234567890); // "1,234,567,890"
With Decimal Places
addCommas(1234.56); // "1,234.56"
addCommas(9876543.21); // "9,876,543.21"
addCommas(1000.0); // "1,000"
addCommas("1234567"); // "1,234,567"
addCommas("9876.543"); // "9,876.543"
Removing Commas
Remove existing thousands separators from formatted numbers:
removeCommas("1,234,567"); // 1234567
removeCommas("9,876,543.21"); // 9876543.21
removeCommas("1,000"); // 1000
String Output Option
removeCommas("1,234,567", { returnString: true }); // "1234567"
removeCommas("9,876.54", { returnString: true }); // "9876.54"
Advanced Examples
function processNumberInput(input: string) {
// Remove existing commas for calculation
const numericValue = removeCommas(input);
// Add commas for display
const displayValue = addCommas(numericValue);
return {
numeric: numericValue,
formatted: displayValue,
isValid: !isNaN(numericValue),
};
}
processNumberInput("1,234,567");
// { numeric: 1234567, formatted: "1,234,567", isValid: true }
function formatCurrency(amount: number, currency = "تومان") {
const formatted = addCommas(amount);
const persian = digitsEnToFa(formatted);
return `${persian} ${currency}`;
}
formatCurrency(1250000); // "۱,۲۵۰,۰۰۰ تومان"
formatCurrency(999999, "ریال"); // "۹۹۹,۹۹۹ ریال"
Batch Processing
const numbers = [1234, 56789, 123456789];
const formatted = numbers.map((num) => ({
original: num,
withCommas: addCommas(num),
persian: digitsEnToFa(addCommas(num)),
}));
// Results:
// [
// { original: 1234, withCommas: "1,234", persian: "۱,۲۳۴" },
// { original: 56789, withCommas: "56,789", persian: "۵۶,۷۸۹" },
// { original: 123456789, withCommas: "123,456,789", persian: "۱۲۳,۴۵۶,۷۸۹" }
// ]
Edge Cases
addCommas(null); // ""
addCommas(undefined); // ""
addCommas(NaN); // ""
addCommas("invalid"); // ""
removeCommas(""); // 0
removeCommas("abc"); // NaN
removeCommas(null); // 0
addCommas("1,234,567"); // "1,234,567" (no change)
removeCommas(1234567); // 1234567 (no change)
Negative Numbers
addCommas(-1234567); // "-1,234,567"
removeCommas("-1,234,567"); // -1234567
Very Large Numbers
addCommas(123456789012345); // "123,456,789,012,345"
addCommas(1e15); // "1,000,000,000,000,000"
TypeScript Support
import { addCommas, removeCommas } from "persian-tools";
// Type-safe usage
const formatted: string = addCommas(1234567);
const numeric: number = removeCommas("1,234,567");
// With options
interface RemoveCommasOptions {
returnString?: boolean;
}
const result: string = removeCommas("1,234", { returnString: true });
- Cache results for frequently used values
- Use number input when possible (faster than string)
- Consider memoization for repeated operations
Real-world Use Cases
Invoice Generation
interface InvoiceItem {
description: string;
quantity: number;
unitPrice: number;
total: number;
}
function formatInvoiceItem(item: InvoiceItem) {
return {
...item,
formattedUnitPrice: addCommas(item.unitPrice),
formattedTotal: addCommas(item.total),
persianTotal: digitsEnToFa(addCommas(item.total)),
};
}
Financial Dashboard
function createFinancialSummary(data: number[]) {
const total = data.reduce((sum, val) => sum + removeCommas(val.toString()), 0);
return {
rawTotal: total,
formattedTotal: addCommas(total),
persianTotal: digitsEnToFa(addCommas(total)),
items: data.map((val) => addCommas(val)),
};
}
function validateNumberInput(input: string) {
const cleaned = removeCommas(input);
return {
isValid: !isNaN(cleaned) && cleaned > 0,
numericValue: cleaned,
formattedValue: addCommas(cleaned),
errorMessage: isNaN(cleaned) ? "عدد معتبر وارد کنید" : null,
};
}
Integration Patterns
React Component
function NumberInput({ value, onChange }: { value: number; onChange: (val: number) => void }) {
const [displayValue, setDisplayValue] = useState(addCommas(value));
const handleChange = (input: string) => {
const numeric = removeCommas(input);
if (!isNaN(numeric)) {
onChange(numeric);
setDisplayValue(addCommas(numeric));
}
};
return (
<input
value={displayValue}
onChange={e => handleChange(e.target.value)}
placeholder="مبلغ را وارد کنید"
/>
);
}
Data Processing Pipeline
const numberProcessor = {
parse: (input: string) => removeCommas(input),
format: (num: number) => addCommas(num),
localize: (num: number) => digitsEnToFa(addCommas(num)),
pipeline: (input: string) => {
const parsed = numberProcessor.parse(input);
const formatted = numberProcessor.format(parsed);
const localized = numberProcessor.localize(parsed);
return { parsed, formatted, localized };
},
};
Digit Conversion
Convert between Persian, Arabic, and English digits
Number to Words
Convert numbers to Persian words
Words to Number
Convert Persian words to numbers
Text Analyzer
Analyze text and number content