Currency (BRL)

Format

• JavaScript library
• Python library37 cases fail
• Go library4 cases fail
• Ruby library15 cases fail
• Rust library
• .NET library3 cases fail
• Erlang library

Formats a number in the BRL pattern 1.234,56.

• A number keeps its sign and its decimals. options.symbol (default false) prefixes the result with R$ (-R$ 1,50 for a negative one). options.precision sets the decimal places (default 2, clamped to 0 to 20; a precision that is not a finite number is 2).
• The function reads a string as currency.parse reads it, except that a value without any separator is whole units (1234 formats as 1.234,00).
• A string with no digit reads as 0: abc and the empty string format as 0,00, and null also gives 0,00. A value that is not a finite number (NaN, infinite) or cannot be coerced to a number (a symbol, a plain object) returns an empty string. Any other non-string value goes through Number(), so true formats as 1,00 and [] as 0,00.

import { formatCurrency } from '@brazilian-utils/brazilian-utils';

formatCurrency(10); // 10,00
formatCurrency(10756.11); // 10.756,11
formatCurrency(10756.123, { precision: 3 }); // 10.756,123
formatCurrency(1234.56, { symbol: true }); // R$ 1.234,56
formatCurrency(-1050); // -1.050,00 (a number's sign is preserved)
formatCurrency('123456'); // 123.456,00 (a plain digit string is read as a whole number)
formatCurrency('1.234,56'); // 1.234,56 (the last "," or "." followed by 1 to 2 digits is the decimal separator)
formatCurrency('-10.5'); // -10,50 (a leading "-" is preserved)
formatCurrency(Number.NaN); // "" (non finite numbers format as an empty string)

Parse

• JavaScript library
• Python library
• Go library4 cases fail
• Ruby library3 cases fail
• Rust library1 case fails
• .NET library5 cases fail
• Erlang library

Parses a BRL amount string (such as R$ 1.234,56) into a number.

• The last , or . followed by 1 to 2 digits (up to options.precision, when larger) is the decimal separator. Every other , or . is a thousands separator.
• The function reads a value without any separator as cents (divided by 10 to the power of the precision, default 2).
• Only a - before the first digit makes the result negative (-R$ 1,00 is -1). An accounting negative such as (R$ 1,00) or a trailing sign as in 1,00- parses to 1. An empty string is 0.
• Every character that is not a digit or a separator is dropped, so 1e5 reads as the digits 15 and parses to 0.15.
• options.precision (default 2, clamped to 0 to 20) is the number of digits read as minor units: the divisor for a value without separator and the largest decimal group. A precision that is not a finite number is 2.

import { parseCurrency } from '@brazilian-utils/brazilian-utils';

parseCurrency('R$ 1.234,56'); // 1234.56
parseCurrency('1234,56'); // 1234.56
parseCurrency('R$ 0,50'); // 0.5
parseCurrency('R$ 1.234'); // 1234 ("." followed by 3 digits is a thousands separator)
parseCurrency('1,5'); // 1.5
parseCurrency('1234'); // 12.34 (no separator at all keeps the cents convention)
parseCurrency('-R$ 1,00'); // -1 (a leading "-" is preserved)
parseCurrency('R$ 1,001', { precision: 3 }); // 1.001
parseCurrency(''); // 0

Write out in words

• JavaScript library
• Python library31 cases fail
• Go library7 cases fail
• Ruby library2 cases fail
• Rust library6 cases fail
• .NET library5 cases fail
• Erlang library

Writes an amount in reais in Brazilian Portuguese words ("por extenso"), as on checks and contracts.

For example, 1523.45 becomes "mil quinhentos e vinte e três reais e quarenta e cinco centavos".

• The function truncates value (does not round it) to 2 decimal places.
• Singular and plural agree ("um real", "um centavo", "zero reais"). Every other amount takes the plural ("dois reais", "um milhão e um reais").
• The function adds the prefix "menos" to a negative amount, except when the amount truncates to nothing: -0.001 is "zero reais".
• The function takes no options. A round million, billion or trillion of reais takes "de" ("um milhão de reais"), and the centavos, when there are any, follow ("um bilhão de reais e cinquenta centavos").
• Above about 90 trillion reais (Number.MAX_SAFE_INTEGER / 100) a number cannot hold cents, so the amount is read as whole reais. The cents are read off the decimal notation of the value, so floating point noise does not change them (1.15 is "um real e quinze centavos").

import { convertCurrencyToWords } from '@brazilian-utils/brazilian-utils';

convertCurrencyToWords(1523.45); // "mil quinhentos e vinte e três reais e quarenta e cinco centavos"
convertCurrencyToWords(1); // "um real"
convertCurrencyToWords(0.01); // "um centavo"
convertCurrencyToWords(1000000); // "um milhão de reais"
convertCurrencyToWords(0); // "zero reais"
convertCurrencyToWords(-5.5); // "menos cinco reais e cinquenta centavos"
convertCurrencyToWords(-0.001); // "zero reais" (truncates to nothing)