Number Formatting

/**
 * Create a number formatter from a specifier string
 * @param specifier - Format specifier string (e.g., ".2f", "$,.2f", "+.1%")
 * @returns Function that formats numbers according to the specifier
 */
function format(specifier: string): (n: number) => string;

/**
 * Format a single number using a specifier string
 * @param specifier - Format specifier string
 * @param number - Number to format
 * @returns Formatted string representation
 */
function format(specifier: string, number: number): string;

import { format } from "d3";

// Basic decimal formatting
const f = format(".2f");
f(42.123); // "42.12"

// Currency formatting
const currency = format("$,.2f");
currency(1234.567); // "$1,234.57"

// Percentage formatting
const percent = format(".1%");
percent(0.123); // "12.3%"

// Scientific notation
const scientific = format(".2e");
scientific(12345); // "1.23e+4"

// Direct formatting
format(".0f", 42.8); // "43"

interface FormatSpecifier {
  fill: string;        // Fill character (default: space)
  align: string;       // Alignment: "<" (left), ">" (right), "^" (center), "=" (pad after sign)
  sign: string;        // Sign: "-" (negative only), "+" (always), " " (space for positive)
  symbol: string;      // Symbol: "$" (currency), "#" (binary/octal/hex prefix)
  zero: boolean;       // Zero padding
  width: number;       // Minimum field width
  comma: boolean;      // Thousands separator
  precision: number;   // Decimal precision
  trim: boolean;       // Trim trailing zeros ("~" modifier)
  type: string;        // Format type: "e", "f", "g", "r", "s", "%", "p", "b", "o", "d", "x", "X", "c"
}

/**
 * Parse a format specifier string into its components
 * @param specifier - Format specifier string
 * @returns FormatSpecifier object with parsed components
 */
function formatSpecifier(specifier: string): FormatSpecifier;

// Fixed-point notation
format(".2f")(3.14159); // "3.14"

// Exponential notation
format(".2e")(1234); // "1.23e+3"

// General format (fixed or exponential as appropriate)
format(".3g")(1234); // "1.23e+3"
format(".3g")(0.001234); // "0.00123"

// Rounded to significant digits
format(".3r")(1234.5); // "1230"

// SI prefix notation
format(".3s")(1234567); // "1.23M"

// Percentage
format(".1%")(0.123); // "12.3%"

// Binary, octal, decimal, hexadecimal
format("b")(42); // "101010"
format("o")(42); // "52"
format("d")(42); // "42"
format("x")(42); // "2a"
format("X")(42); // "2A"

/**
 * Create a precision formatter for a numeric range
 * @param step - Step size or representative value for precision calculation
 * @returns Format function with appropriate precision
 */
function formatPrefix(specifier: string, value: number): (n: number) => string;

/**
 * Format with SI prefix notation and appropriate precision
 * @param specifier - Base format specifier
 * @param value - Reference value for determining prefix
 * @returns Format function with SI prefix
 */
function formatPrefix(specifier: string, value: number): (n: number) => string;

import { formatPrefix } from "d3";

// SI prefix formatting
const f = formatPrefix(",.0", 1e6);
f(1234567); // "1M"
f(1234); // "1k"

// Appropriate precision for scale
const precision = formatPrefix(".1", 0.01);
precision(0.0123); // "12.3m"

/**
 * Create a new locale with custom formatting rules
 * @param definition - Locale definition object
 * @returns Locale object with format methods
 */
function formatLocale(definition: LocaleDefinition): Locale;

/**
 * Get the default locale
 * @returns Current default locale object
 */
function formatDefaultLocale(): Locale;

interface LocaleDefinition {
  decimal: string;           // Decimal separator (e.g., ".")
  thousands: string;         // Thousands separator (e.g., ",")
  grouping: number[];        // Grouping pattern (e.g., [3])
  currency: [string, string]; // Currency prefix and suffix (e.g., ["$", ""])
  numerals?: string[];       // Numeral substitution strings
  percent: string;           // Percent symbol (e.g., "%")
  minus: string;             // Minus sign (e.g., "−")
  nan: string;               // Not-a-number representation (e.g., "NaN")
}

interface Locale {
  format(specifier: string): (n: number) => string;
  formatPrefix(specifier: string, value: number): (n: number) => string;
}

import { formatLocale, formatDefaultLocale } from "d3";

// Create French locale
const frenchLocale = formatLocale({
  decimal: ",",
  thousands: " ",
  grouping: [3],
  currency: ["", " €"],
  percent: " %",
  minus: "−",
  nan: "N/D"
});

const frenchFormat = frenchLocale.format("$,.2f");
frenchFormat(1234.56); // "1 234,56 €"

// Set as default
formatDefaultLocale(frenchLocale);

// Common locale identifiers
const localeEnUs: LocaleDefinition;  // English (US) - default
const localeEnGb: LocaleDefinition;  // English (UK)
const localeFrFr: LocaleDefinition;  // French (France)
const localeDeDe: LocaleDefinition;  // German (Germany)
const localeEsEs: LocaleDefinition;  // Spanish (Spain)
const localeItIt: LocaleDefinition;  // Italian (Italy)
const localeJaJp: LocaleDefinition;  // Japanese (Japan)
const localeKoKr: LocaleDefinition;  // Korean (Korea)
const localeZhCn: LocaleDefinition;  // Chinese (China)
const localeRuRu: LocaleDefinition;  // Russian (Russia)