CultureBR.DataTypes 1.0.1

<div align="center">

Biblioteca com diversos tipos de dados brasileiros como CEP, CPF, CNPJ com suas respectivas validações e formatadores.

<a href="https://www.nuget.org/packages/CultureBR.DataTypes"><img alt="Nuget" src="https://img.shields.io/nuget/v/CultureBR.DataTypes"></a> <br/> dotnet add package CultureBR.DataTypes

</div>

• O que é
• Como Funciona
  • O que é um valor inválido
• Validação e formatação
  • Validação
  • Formatação

O que é

É uma biblioteca que oferece alguns ValueTypes de dados brasileiros contendo suas respectivas validações e formatações. Também pode ser usado somente para validação e formatação dos tipos caso não seja do interesse usar como ValueType. A tentativa é oferecer uma biblioteca que manipule essas strings com o mínimo de alocação de memória possível através do uso de Span<char> e semelhantes.

Como funciona

Os tipos podem receber tanto strings quanto valores numéricos porém essa atribuição só é concluída se o valor for válido, caso contrário é lançada um ArgumentException. Exemplo:

    CPF cpf = "698.534.560-36";
    cpf == "698.534.560-36"; //true

    CPF cpf = " 698534. 5603  6"; //Input sujo porém válido.
    Console.WriteLine(cpf); //"698.534.560-36"

    CPF cpf = 69853456036;
    Console.WriteLine(cpf); //"698.534.560-36"

O que é um valor inválido

É considerado um valor inválido quando este valor não atende as regras do tipo específico usado.

• Espaços em branco são aceitos tanto no início, meio e final da string.
• Caracteres como '.', ',', '-', '/' são aceitos mesmo fora da formatação padrão.
• Desde que o valor seja válido o dado pode vir sujo como descrito acima que o valor do tipo será atribuido formatado corretamente.

Validação e formatação

Validação

A validação pode ser feita pelo método IsValid e tem 2 níveis de rigor:

    public enum ValidationLevel
    {
        Soft = 0,
        Hard = 1,
    }

• Soft: Aceita dados sujos para serem validados. É o valor padrão. Exemplo: " 89.49 1.969/0001 -16" ou "8949..1969/0 0011-6"
• Hard: A validação não aceita um dado sujo. É necessário que o dado a ser validado não contenha espaços em branco ou dados não numéricos fora de posição ou em excesso. Aceita dado somente númerico. Exemplo: "89.491.969/0001-16" ou "89491969000116"

    bool success = CPF.IsValid("698.534.560-36");
    bool success = CPF.IsValid("698.534.560-36", ValidationLevel.Hard);

A validação também pode ser feita através do método TryParse. Esta validação é sempre feita no modo Soft que aceita um input sujo.

    bool success = CPF.TryParse("698.534.560-36", out formattedCpf);
    bool success = CPF.TryParse(69853456036, out formattedCpf);

Formatação

Usando o método Parse é retornada uma string formatada no tipo desejado. Caso o input esteja em um formato inválido será lançada uma exceção do tipo ArgumentException.

    string cpf = CPF.Parse(" 698534. 56036");
    string cpf = CPF.Parse(69853456036);
    Console.WriteLine(cpf); //"698.534.560-36"

Além de retornar se é válido, o método TryParse é retornada uma string formatada no tipo desejado. Caso o input esteja em um formato inválido a string retornada no out é null e não é lançada nenhuma exceção.

    bool success = CPF.TryParse("698.534.560-36", out formattedCpf);
    Console.WriteLine(formattedCpf); //"698.534.560-36"
    
    bool success = CPF.TryParse(69853456036, out formattedCpf);
    Console.WriteLine(formattedCpf); //"698.534.560-36"