Como: definir e usar provedores de formatos numéricos personalizados
O .NET oferece controle abrangente sobre a representação de cadeias de caracteres de valores numéricos. Ele dá suporte aos seguintes recursos para personalizar o formato de valores numéricos:
Cadeias de caracteres de formato numérico padrão, que fornecem um conjunto predefinido de formatos para converter números para suas representações de cadeia de caracteres. Você pode usá-las com qualquer método de formatação numérica, como Decimal.ToString(String), que tem um parâmetro
format. Para obter detalhes, confira Cadeias de caracteres de formato numérico padrão.Cadeias de caracteres de formato numérico personalizado, que fornecem um conjunto de símbolos que podem ser combinados para definir especificadores de formato numérico personalizado. Elas também podem ser usadas com qualquer método de formatação numérica, como Decimal.ToString(String), que tem um parâmetro
format. Para ver detalhes, confira Cadeias de caracteres de formato numérico personalizado.Os objetos CultureInfo ou NumberFormatInfo personalizados que definem os símbolos e padrões de formato usados para exibir as representações de cadeia de caracteres de valores numéricos. Você pode usá-las com qualquer método de formatação numérica, como ToString, que tem um parâmetro
provider. Normalmente, o parâmetroprovideré usado para especificar a formatação específica à cultura.
Em alguns casos (como quando um aplicativo deve exibir um número de conta formatado, um número de identificação ou um código postal) essas três técnicas são inadequadas. O .NET também permite que você defina um objeto de formatação que não é um objeto CultureInfo ou NumberFormatInfo para determinar como um valor numérico é formatado. Este tópico fornece informações passo a passo para implementar esse tipo de objeto, bem como um exemplo que formata números de telefone.
Define um provedor de formato personalizado
Defina uma classe que implementa as interfaces IFormatProvider e ICustomFormatter.
Implementar o método de IFormatProvider.GetFormat . GetFormat é um método de retorno de chamada que o método de formatação (como o método String.Format(IFormatProvider, String, Object[])) invoca para recuperar o objeto que é o responsável por executar a formatação personalizada. Uma implementação típica de GetFormat faz o seguinte:
Determina se o objeto Type passado como método de parâmetro representa uma interface ICustomFormatter.
Se o parâmetro representar a interface ICustomFormatter, GetFormat retorna um objeto que implementa a interface ICustomFormatter que é responsável por fornecer a formatação personalizada. Normalmente, o objeto de formatação personalizado retorna a si próprio.
Se o parâmetro não representar a interfaceICustomFormatter, GetFormat retorna
null.
Implementar o método de Format . Este método é chamado pelo método String.Format(IFormatProvider, String, Object[]) e é responsável por retornar a representação de cadeia de caracteres de um número. Implementar o método normalmente envolve o seguinte:
Opcionalmente, verifique se o método é legitimamente destinado a fornecer serviços de formatação examinando o parâmetro
provider. Para formatar objetos que implementam IFormatProvider e ICustomFormatter, isso envolve testar o parâmetroproviderpara igualdade com o objeto de formatação atual.Determine se o objeto de formatação deve dar suporte a especificadores de formato personalizado. (Por exemplo, um especificador de formato "N" pode indicar que um número de telefone dos EUA deve ser gerado no formato NANP e um "I" pode indicar a saída no formato E. 123 da Recomendação ITU-T.) Se especificadores de formato forem usados, o método deve tratar o especificador de formato específico. Ele é passado para o método no parâmetro
format. Se nenhum especificador estiver presente, o valor do parâmetroformatserá String.Empty.Recupere o valor numérico passado para o método como o parâmetro
arg. Execute as manipulações que forem necessárias para convertê-lo em sua representação de cadeia de caracteres.Retorne a representação de cadeia de caracteres do parâmetro
arg.
Usa um objeto de formatação numérico personalizado
Crie uma nova instância da classe de formatação personalizada.
Chame o método de formatação String.Format(IFormatProvider, String, Object[]) e passe para ele o objeto de formatação personalizado, o especificador de formatação (ou String.Empty, se um não for usado) e o valor numérico a ser formatado.
Exemplo
O exemplo a seguir define um provedor de formato numérico personalizado chamado TelephoneFormatter, que converte um número que representa um número de telefone dos EUA para seu formato NANP ou E.123. O método lida com dois especificadores de formato, "N" (que gera o formato NANP) e "I" (que gera o formato internacional E.123).
using System;
using System.Globalization;
public class TelephoneFormatter : IFormatProvider, ICustomFormatter
{
public object GetFormat(Type formatType)
{
if (formatType == typeof(ICustomFormatter))
return this;
else
return null;
}
public string Format(string format, object arg, IFormatProvider formatProvider)
{
// Check whether this is an appropriate callback
if (! this.Equals(formatProvider))
return null;
// Set default format specifier
if (string.IsNullOrEmpty(format))
format = "N";
string numericString = arg.ToString();
if (format == "N")
{
if (numericString.Length <= 4)
return numericString;
else if (numericString.Length == 7)
return numericString.Substring(0, 3) + "-" + numericString.Substring(3, 4);
else if (numericString.Length == 10)
return "(" + numericString.Substring(0, 3) + ") " +
numericString.Substring(3, 3) + "-" + numericString.Substring(6);
else
throw new FormatException(
string.Format("'{0}' cannot be used to format {1}.",
format, arg.ToString()));
}
else if (format == "I")
{
if (numericString.Length < 10)
throw new FormatException(string.Format("{0} does not have 10 digits.", arg.ToString()));
else
numericString = "+1 " + numericString.Substring(0, 3) + " " + numericString.Substring(3, 3) + " " + numericString.Substring(6);
}
else
{
throw new FormatException(string.Format("The {0} format specifier is invalid.", format));
}
return numericString;
}
}
public class TestTelephoneFormatter
{
public static void Main()
{
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0}", 0));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0}", 911));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0}", 8490216));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0}", 4257884748));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:N}", 0));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:N}", 911));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:N}", 8490216));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:N}", 4257884748));
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:I}", 4257884748));
}
}
Public Class TelephoneFormatter : Implements IFormatProvider, ICustomFormatter
Public Function GetFormat(formatType As Type) As Object _
Implements IFormatProvider.GetFormat
If formatType Is GetType(ICustomFormatter) Then
Return Me
Else
Return Nothing
End If
End Function
Public Function Format(fmt As String, arg As Object, _
formatProvider As IFormatProvider) As String _
Implements ICustomFormatter.Format
' Check whether this is an appropriate callback
If Not Me.Equals(formatProvider) Then Return Nothing
' Set default format specifier
If String.IsNullOrEmpty(fmt) Then fmt = "N"
Dim numericString As String = arg.ToString
If fmt = "N" Then
Select Case numericString.Length
Case <= 4
Return numericString
Case 7
Return Left(numericString, 3) & "-" & Mid(numericString, 4)
Case 10
Return "(" & Left(numericString, 3) & ") " & _
Mid(numericString, 4, 3) & "-" & Mid(numericString, 7)
Case Else
Throw New FormatException( _
String.Format("'{0}' cannot be used to format {1}.", _
fmt, arg.ToString()))
End Select
ElseIf fmt = "I" Then
If numericString.Length < 10 Then
Throw New FormatException(String.Format("{0} does not have 10 digits.", arg.ToString()))
Else
numericString = "+1 " & Left(numericString, 3) & " " & Mid(numericString, 4, 3) & " " & Mid(numericString, 7)
End If
Else
Throw New FormatException(String.Format("The {0} format specifier is invalid.", fmt))
End If
Return numericString
End Function
End Class
Public Module TestTelephoneFormatter
Public Sub Main
Console.WriteLine(String.Format(New TelephoneFormatter, "{0}", 0))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0}", 911))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0}", 8490216))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0}", 4257884748))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:N}", 0))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:N}", 911))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:N}", 8490216))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:N}", 4257884748))
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:I}", 4257884748))
End Sub
End Module
O provedor de formato numérico personalizado pode ser usado apenas com o método String.Format(IFormatProvider, String, Object[]). As outras sobrecargas de métodos de formatação numérica (como ToString) que têm um parâmetro do tipo IFormatProvider passam para a implementação IFormatProvider.GetFormat um objeto Type que representa o tipo NumberFormatInfo. Por sua vez, eles esperam que o método retorne um objeto NumberFormatInfo. Se isso não acontecer, o provedor de formato numérico personalizado será ignorado e o objeto NumberFormatInfo da cultura atual será usada em seu lugar. No exemplo, o método TelephoneFormatter.GetFormat trata da possibilidade de ele ser passado inadequadamente para um método de formatação numérico examinando o parâmetro do método e retornando null se ele representar um tipo diferente de ICustomFormatter.
Se um provedor de formato numérico personalizado der suporte a um conjunto de especificadores de formato, forneça um comportamento padrão se nenhum especificador de formato for fornecido no item de formato usado na chamada de método String.Format(IFormatProvider, String, Object[]). No exemplo, "N" é o especificador de formato padrão. Isso permite que um número a ser convertido em um número de telefone formatado, fornecendo um especificador de formato explícito. O exemplo a seguir ilustra essa chamada de método.
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0:N}", 4257884748));
Console.WriteLine(String.Format(New TelephoneFormatter, "{0:N}", 4257884748))
Mas também permite que a conversão ocorra se nenhum especificador de formato estiver presente. O exemplo a seguir ilustra essa chamada de método.
Console.WriteLine(String.Format(new TelephoneFormatter(), "{0}", 4257884748));
Console.WriteLine(String.Format(New TelephoneFormatter, "{0}", 4257884748))
Se nenhum especificador de formato padrão for definido, sua implementação do método ICustomFormatter.Format deve incluir código como o seguinte para que o .NET possa fornecer a formatação a que seu código não dá suporte.
if (arg is IFormattable)
s = ((IFormattable)arg).ToString(format, formatProvider);
else if (arg != null)
s = arg.ToString();
If TypeOf (arg) Is IFormattable Then
s = DirectCast(arg, IFormattable).ToString(fmt, formatProvider)
ElseIf arg IsNot Nothing Then
s = arg.ToString()
End If
No caso deste exemplo, o método que implementa ICustomFormatter.Format se destina a servir como um método de retorno de chamada para o método String.Format(IFormatProvider, String, Object[]). Portanto, ele examina o parâmetro formatProvider para determinar se ele contém uma referência ao objeto TelephoneFormatter atual. No entanto, o método também pode ser chamado diretamente do código. Nesse caso, você pode usar o parâmetro formatProvider para fornecer um objeto CultureInfo ou NumberFormatInfo que fornece informações de formatação específicas da cultura.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de