Formatar Moeda Brasileira (BRL)

[camilamaia]

Seu pedido de recurso está relacionado a um problema? Por favor, descreva.

Preciso de uma função que formate valores numéricos (float) em reais (R$) de forma adequada, retornando uma string formatada. Isso é útil para garantir que os valores monetários sejam apresentados corretamente em sistemas e relatórios.

Por exemplo, converter 1234.56 para "R$ 1.234,56".

Descreva a solução que você gostaria

• Uma função format_brl, que recebe um valor numérico (float) e retorna uma string formatada com o símbolo de reais (R$) e os separadores adequados para milhares e decimais.
• A função deve verificar se a entrada é válida (por exemplo, se é um número). Se a entrada for inválida, a função deve retornar None.
• A função deve lidar com entradas como 0, valores negativos, e números grandes.
• A função deve seguir o padrão de formatação brasileiro, onde o ponto (.) separa os milhares e a vírgula (,") separa os decimais.
• A função deve retornar None para entradas como: strings, None, valores não numéricos ou estruturas de dados complexas.

Descreva alternativas que você considerou

1. Seguir até o passo 8 do guia de contribuição.

2. Como parte do passo 8, criar o arquivo: brutils-python/brutils/currency.py.

   def format_brl(value): # type: (float) -> str | None
       """
       Formats a given float as Brazilian currency (R$).
   
       This function takes a float value and returns a formatted string representing
       the value as Brazilian currency, using the correct thousand and decimal separators.
   
       Args:
           value (float): The numeric value to be formatted.
   
       Returns:
           str or None: A string formatted as Brazilian currency, or None if the input is invalid.
   
       Example:
           >>> format_brl(1234.56)
           "R$ 1.234,56"
           >>> format_brl(0)
           "R$ 0,00"
           >>> format_brl(-9876.54)
           "R$ -9.876,54"
           >>> format_brl(None)
           None
           >>> format_brl("not a number")
           None
       """
       # implementar a lógica da função aqui

3. Como parte do passo 9, criar o arquivo de teste: brutils-python/tests/test_currency.py.

   from unittest import TestCase
   from brutils.currency import format_brl
   
   class TestCurrency(TestCase):
       def test_format_brl(self):
           # Testes para valores válidos
           self.assertEqual(format_brl(1234.56), "R$ 1.234,56")
           self.assertEqual(format_brl(0), "R$ 0,00")
           self.assertEqual(format_brl(987654321.99), "R$ 987.654.321,99")
           self.assertEqual(format_brl(-9876.54), "R$ -9.876,54")
   
           # Testes para valores inválidos
           self.assertIsNone(format_brl(None))  # Valor nulo
           self.assertIsNone(format_brl("1234.56"))  # String numérica
           self.assertIsNone(format_brl([]))  # Lista
           self.assertIsNone(format_brl({}))  # Dicionário
           self.assertIsNone(format_brl(set()))  # Conjunto
           self.assertIsNone(format_brl("not a number"))  # String não numérica
   
           # implementar mais casos de teste aqui se necessário

4. Seguir os passos seguintes do guia de contribuição.

Contexto adicional

A função deve seguir o padrão brasileiro de formatação de moeda e considerar todos os edge cases possíveis, como valores negativos, zeros, e entradas inválidas.

[morais90]

bora!

[github-actions]

Issue 426 atribuida a morais90 🚀"
"Verifique o guia de contribuição para mais informações sobre como submeter sua Pull Request."