Skip to main content

​
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"

​
String Input

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

​
Form Input Processing

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 }

​
Currency Formatting

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

​
Invalid Input Handling

addCommas(null); // ""
addCommas(undefined); // ""
addCommas(NaN); // ""
addCommas("invalid"); // ""

removeCommas(""); // 0
removeCommas("abc"); // NaN
removeCommas(null); // 0

​
Already Formatted Numbers

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 });

​
Performance Considerations

  • Small numbers (< 1M): ~0.1ms
  • Large numbers (> 1B): ~0.2ms
  • String processing: ~0.15ms average
  • Batch operations: Linear scaling
  • 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)),
	};
}

​
Form Validation

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