Extenso.js

> Uma biblioteca avançada para escrever números por extenso (em português).

Features

- [x] Números até duodecilhões.
- [x] Números negativos.
- [x] Números decimais.
- [x] Valores monetários (BRL, EUR e mais).
- [x] Preferências de dialetos (Brasil, Portugal e mais).
- [x] Preferências de gênero.

Instalação

Instale-o com seu gerenciador preferido:

- npm: npm install extenso
- Yarn: yarn add extenso

Uso

``js
var extenso = require('extenso')
`

Sintaxe

`
extenso(number[, options])
`

$3

Obs.: Parâmetro obrigatório.

- Tipo: string ou number

> O número que deverá ser escrito por extenso.

Se o valor for do tipo number, então 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, é muito recomendado que os números sejam encapsulados em string devivo ao fato que no JavaScript números (do tipo number) maiores que 9 quatrilhões perdem valores sendo imprecisos (experimente este artigo para mais informações [Tableless]).

Números envolvidos em strings deverão seguir o formato natural de escrita de números. Você poder usar - no início para representar números negativos e vírgula (,) ou ponto (.) para separação de milhares e decimais, onde por padrão segue-se o formato de escrita do Brasil podendo alterar as prefencias (como será visto no parâmetro number.decimalSeparator).

$3

Obs.: Parâmetro opcional.

- Tipo: object

> Configurações opcionais de escrita.

- mode (string)
- locale (string)
- negative (string)
- currency (object)
- currency.type (string)
- number (object)
- number.gender (string)
- number.decimal (string)
- number.decimalSeparator (string)

#### mode

> 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.

##### Exemplo

`js
extenso('42') // 'quarenta e dois'
extenso('42', { mode: 'number' }) // 'quarenta e dois'
extenso('42', { mode: 'currency' }) // 'quarenta e dois reais'
`

#### negative

> 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.

##### Exemplo

`js
extenso('-42') // 'quarenta e dois negativo'
extenso('-42', { negative: 'formal' }) // 'quarenta e dois negativo'
extenso('-42', { negative: 'informal' }) // 'menos quarenta e dois'
`

#### locale

> 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.

##### Exemplo

`js
extenso('16') // 'dezesseis'
extenso('16', { locale: 'br' }) // 'dezesseis'
extenso('16', { locale: 'pt' }) // 'dezasseis'
`

#### currency.type

> 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.

##### Exemplo

`js
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'
`

#### number.gender

> 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.

##### Exemplo

`js
extenso('42') // 'quarenta e dois'
extenso('42', { number: { gender: 'm' } }) // 'quarenta e dois'
extenso('42', { number: { gender: 'f' } }) // 'quarenta e duas'
`

#### number.decimal

> Define o modo de escrita do valor decimal.

- formal (valor padrão) - Para escrever no modo formal.
- informal - Para escrever no modo informal.

##### Exemplo

`js
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'
`

#### number.decimalSeparator

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

##### Observação

Quando o separador de decimal é o . (ponto) automaticamente o separador de
milhar será o , (vírgula) e vice-versa.

##### Exemplo

`js
extenso('3,14')
extenso('3,14', { number: { decimalSeparator: 'comma' } })
extenso('3.14', { number: { decimalSeparator: 'dot' } })

// 'três inteiros e quatorze centésimos'
`

Contribuição

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.

$3

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.

TODO

- [ ] Traduzir o README.md em inglês (README-en.md`).

Licença

MIT © Matheus Alves