Uma biblioteca avançada para escrever números por extenso (em português).
- Números até duodecilhões.
- Números negativos.
- Números decimais.
- Valores monetários (BRL, EUR e mais).
- Escala curta e longa.
- Preferências de dialetos (Brasil, Portugal e mais).
- Preferências de gênero.
npm install extenso
Ou com Yarn: yarn add extenso
.
var extenso = require('extenso')
extenso(number[, options])
Obs.: Parâmetro obrigatório.
- Tipo:
string
,number
oubigint
O número que deverá ser escrito por extenso.
Se o valor for do tipo number
, ele deve ser um número com parte inteira segura, ou seja, o valor deve ser válido na verificação com Number.isSafeInteger()
. No entanto, é altamente recomendado que os números sejam encapsulados em string devido ao fato de que, no JavaScript, números (do tipo number
) maiores que 9 quatrilhões perdem precisão. Alternativamente, pode-se utilizar números BigInt
(do tipo bigint
) adicionando n
no final, por exemplo, 10000000000000001n
(leia este artigo para mais informações).
Números envolvidos em strings deverão seguir o formato natural de escrita de números. Você pode usar -
no início para representar números negativos e vírgula (,
) ou ponto (.
) para separação de milhares e decimais, seguindo, por padrão, o formato de escrita do Brasil. Esse formato pode ser alterado conforme a preferência, utilizando o parâmetro number.decimalSeparator
.
Obs.: Parâmetro opcional.
- Tipo:
object
Configurações opcionais de escrita.
mode
(string)locale
(string)negative
(string)scale
(* string *)currency
(object)currency.type
(string)number
(object)number.gender
(string)number.decimal
(string)number.decimalSeparator
(string)
Define o modo de escrita do número.
Pode ser:
number
(valor padrão) - Para escrever números simples.currency
- Para escrever valores monetários.
extenso('42') // 'quarenta e dois'
extenso('42', { mode: 'number' }) // 'quarenta e dois'
extenso('42', { mode: 'currency' }) // 'quarenta e dois reais'
Define o modo de escrita do valor negativo.
formal
(valor padrão) - Para escrever o número no modo formal.informal
- Para escrever o número no modo informal.
extenso('-42') // 'quarenta e dois negativo'
extenso('-42', { negative: 'formal' }) // 'quarenta e dois negativo'
extenso('-42', { negative: 'informal' }) // 'menos quarenta e dois'
Define a escala de escrita (curta ou longa).
As escalas curta e longa são dois sistemas de escrita dos números. A escala curta é a utilizado no Brasil, enquanto que a escala longa é a utilizada no restante dos paises de lingua portuguesa.
A escrita diverge somente em números iguais ou superiores a um milhar de milhões (>= 10e9
), números inferiores a isso seguem com a escrita idêntica em ambas as escalas.
Mais informações aqui [Wikipédia].
short
(valor padrão) - Para escrever o número utilizando a escala curta.long
- Para escrever o número utilizando a escala longa.
extenso('2.000.000.001') // 'dois bilhões e um'
extenso('2.000.000.001', { scale: 'short' }) // 'dois bilhões e um'
extenso('2.000.000.001', { scale: 'long' }) // 'dois mil milhões e um'
Define a localização para o modo de escrita.
A escrita de alguns números pode váriar de país para país (e talvez até de região para região), por exemplo, o número 16 é escrito dezesseis no Brasil, enquanto que em Portugal é escrito dezasseis. A configuração dessas diferenças é feita aqui.
br
(valor padrão) - Para escrever no dialeto do Brasil.pt
- Para escrever no dialeto de Portugal.
extenso('16') // 'dezesseis'
extenso('16', { locale: 'br' }) // 'dezesseis'
extenso('16', { locale: 'pt' }) // 'dezasseis'
Define o código ISO da moeda em que o número deverá ser escrito.
BRL
(valor padrão) - Para escrever valores em Real brasileiro.EUR
- Para escrever valores em Euro.CVE
- Para escrever valores em Escudo cabo-verdiano.MZN
- Para escrever valores em Metical moçambicano.
extenso('42', { mode: 'currency' }) // 'quarenta e dois reais'
extenso('42', { mode: 'currency', currency: { type: 'BRL' } }) // 'quarenta e dois reais'
extenso('42', { mode: 'currency', currency: { type: 'EUR' } }) // 'quarenta e dois euros'
extenso('42', { mode: 'currency', currency: { type: 'CVE' } }) // 'quarenta e dois escudos'
extenso('42', { mode: 'currency', currency: { type: 'MZN' } }) // 'quarenta e dois meticais'
Define o gênero do número que será escrito.
Alguns números podem ser representados tanto no modo masculino quanto no modo feminino, por exemplo, 42 pode ser escrito como quarenta e dois ou 42 ou quarenta e duas.
m
(valor padrão) - Para escrever no modo masculino.f
- Para escrever no modo feminino.
extenso('42') // 'quarenta e dois'
extenso('42', { number: { gender: 'm' } }) // 'quarenta e dois'
extenso('42', { number: { gender: 'f' } }) // 'quarenta e duas'
Define o modo de escrita do valor decimal.
formal
(valor padrão) - Para escrever no modo formal.informal
- Para escrever no modo informal.
extenso('3,14') // 'três inteiros e quatorze centésimos'
extenso('3,14', { number: { decimal: 'formal' } }) // 'três inteiros e quatorze centésimos'
extenso('3,14', { number: { decimal: 'informal' } }) // 'três vírgula quatorze'
Define o separador de inteiro e decimal.
comma
(valor padrão) - Para usar vírgula como separador (ex.3,14
).dot
- Para usar ponto como separador (ex.:3.14
)
Quando o separador de decimal é o .
(ponto) automaticamente o separador de
milhar será o ,
(vírgula) e vice-versa.
extenso('3,14')
extenso('3,14', { number: { decimalSeparator: 'comma' } })
extenso('3.14', { number: { decimalSeparator: 'dot' } })
// 'três inteiros e quatorze centésimos'
Oi, você é de Portugal, Angola, Moçambique ou qualquer outro país que usa fala português? Viu alguma escrita de números que é diferente no seu país? Então abra uma issue e vamos discutir como adaptar essas caracteristicas ao projeto para deixá-lo o mais completo possível.
Viu algum erro ou qualquer coisa que pode ser melhorada?
Você pode, portanto:
- Abrir uma issue.
- Enviar um pull request.
- Comentar no trecho do código que você acredita que pode ser melhorado.
Tendo em vista a participação de falantes da língua portuguesa, escreva:
- Nome de váriaveis, funções e outras coisas do tipo em inglês.
- Nome dos arquivos e diretórios em inglês.
- Issues, pull requests e comentários em português.
- Descrição dos testes em português.
- Regra 1: Deve ter o formato: Deve(m) + verbo + descrição.
- Regra 2: Nunca use ponto final na descrição.
- Mensagem de commits em português.
- Regra 1: Inicie-os sempre em caixa alta.
- Regra 2: Nunca use ponto final na descrição.
- Traduzir o
README.md
em inglês (README-en.md
).
MIT © Matheus Alves