System.String.Format 方法 (IFormatProvider, String, Object[])

方法描述

将指定字符串中的格式项替换为指定数组中相应对象的字符串表示形式。 指定的参数提供区域性特定的格式设置信息。

语法定义(C# System.String.Format 方法 (IFormatProvider, String, Object[]) 的用法)

public static string Format(
	IFormatProvider provider,
	string format,
	params Object[] args
)

参数/返回值

参数值/返回值 参数类型/返回类型 参数描述/返回描述
provider System-IFormatProvider 一个提供区域性特定的格式设置信息的对象。
format System-String 符合格式字符串(参见“备注”)。
args System-Object[] 一个对象数组,其中包含零个或多个要设置格式的对象。
返回值 System.String format 的副本,其中的格式项已替换为 args 中相应对象的字符串表示形式。

提示和注释

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其字符串表示形式,并将该表示形式嵌入字符串中。 .NET Framework 提供了广泛的格式设置支持,下面的格式设置主题中对此有更详细的描述:

有关 Format、AppendFormat 等方法以及 WriteLine 的某些重载所支持的复合格式设置功能的更多信息,请参见复合格式。

有关数值格式说明符的更多信息,请参见标准数字格式字符串和自定义数字格式字符串。

有关日期和时间格式说明符的更多信息,请参见标准日期和时间格式字符串和自定义日期和时间格式字符串。

有关枚举格式说明符的更多信息,请参见枚举格式字符串。

有关格式设置的更多信息,请参见格式化类型。

provider 参数提供用于减缓格式化过程的自定义信息和特定于区域性的信息。 provider 参数是 IFormatProvider 的实现,其 GetFormat 方法由 String.Format(IFormatProvider, String, Object[]) 方法调用。 此方法必须返回类型与 formatType 参数的类型相同的对象以提供格式设置信息。 provider 参数的 GetFormat 方法会被调用一次或多次,具体取决于 args 中对象的特定类型,如下所述:

始终向该方法传递一个表示 ICustomFormatter 类型的 Type 对象。

对于相应数据类型为日期和时间值的每个格式项,向该方法传递一个表示 DateTimeFormatInfo 类型的 Type 对象。

对于相应数据类型为数值的每个格式项,向该方法传递一个表示 NumberFormatInfo 类型的 Type 对象。

有关更多信息,请参见 格式化类型 主题的“格式提供程序”部分。 “示例”部分提供了一个自定义格式提供程序的示例,该提供程序将数值输出为具有嵌入连字符的客户帐号。

format 参数由零或多个文本序列与零或多个索引占位符混合组成,其中索引占位符称为格式项,对应于与此方法的参数列表中的对象。 格式设置过程将每个格式项替换为相应对象值的字符串表示形式。

格式项的语法如下:

{index[,length][:formatString]}

方括号中的元素是可选的。 下表描述每个元素。 有关复合格式设置功能(包括格式项的语法)的更多信息,请参见复合格式。

元素

说明

索引

要设置格式的对象的参数列表中的位置(从零开始)。 如果 index 位置没有参数,将引发 FormatException。 如果由 index 指定的对象为 null,则格式项将被 String.Empty 替换。

,length

要设置格式的对象的字符串表示形式中包含的最小字符数。 如果该值是正的,则要设置格式的对象右对齐;如果该值是负的,则左对齐。 如果指定 length,则需要使用逗号。

:formatString

要设置格式的对象支持的标准或自定义格式字符串。 formatString 的可能值与该对象的 ToString(format) 方法支持的值相同。 如果没有指定 formatString,并且要设置格式的对象实现了 IFormattable 接口,则将传递 null 作为用作 IFormattable.ToString 格式字符串的 format 参数的值。

注意

有关日期和时间值使用的标准和自定义格式字符串的信息,请参见标准日期和时间格式字符串和自定义日期和时间格式字符串。 有关数值使用的标准和自定义格式字符串的信息,请参见标准数字格式字符串和自定义数字格式字符串。 有关枚举使用的标准格式字符串的信息,请参见枚举格式字符串。

必须使用前导大括号字符和尾部大括号字符,即“{”和“}”。 若要在 format 中指定单个大括号字符,请指定两个前导大括号字符或尾部大括号字符;即“{{”或“}}”。

如果 format 的值为“Thank you for your purchase of {0:####} copies of Microsoft®.NET (Core Reference).”,且 arg[0] 是值为 123 的 Int16 ,则返回值将为:

“Thank you for your purchase of 123 copies of Microsoft®.NET (Core Reference).”

如果 format 的值为“Brad's dog has {0,-8:G} fleas.”,arg[0] 是值为 42 的 Int16(在此示例中,下划线表示填充空格),则返回值为:

“Brad's dog has 42______ fleas.”

System.String.Format 方法 (IFormatProvider, String, Object[])例子

下面的示例定义了一个客户号格式提供程序,该提供程序将整数值格式设置为 x-xxxxx-xx 形式的客户帐户。

using System;

public class TestFormatter
{
   public static void Main()
   {
      int acctNumber = 79203159;
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:G}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:S}", acctNumber));
      Console.WriteLine(String.Format(new CustomerFormatter(), "{0:P}", acctNumber));
      try {
         Console.WriteLine(String.Format(new CustomerFormatter(), "{0:X}", acctNumber));
      }
      catch (FormatException e) {
         Console.WriteLine(e.Message);
      }
   }
}

public class CustomerFormatter : 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) 
   {                       
      if (! this.Equals(formatProvider))
      {
         return null;
      }
      else
      {
         if (String.IsNullOrEmpty(format)) 
            format = "G";

         string customerString = arg.ToString();
         if (customerString.Length < 8)
            customerString = customerString.PadLeft(8, '0');

         format = format.ToUpper();
         switch (format)
         {
            case "G":
               return customerString.Substring(0, 1) + "-" +
                                     customerString.Substring(1, 5) + "-" +
                                     customerString.Substring(6);
            case "S":                          
               return customerString.Substring(0, 1) + "/" +
                                     customerString.Substring(1, 5) + "/" +
                                     customerString.Substring(6);
            case "P":                          
               return customerString.Substring(0, 1) + "." +
                                     customerString.Substring(1, 5) + "." +
                                     customerString.Substring(6);
            default:
               throw new FormatException( 
                         String.Format("The '{0}' format specifier is not supported.", format));
         }
      }   
   }
}
// The example displays the following output:
//       7-92031-59
//       7-92031-59
//       7/92031/59
//       7.92031.59
//       The 'X' format specifier is not supported.

异常

异常 异常描述
ArgumentNullException format 或 args 为 null。
FormatException
  • format 无效。
  • 格式项的索引小于零或大于等于 args 数组的长度。

命名空间

namespace: System

程序集: mscorlib(在 mscorlib.dll 中)

版本信息

.NET Framework 受以下版本支持:4、3.5、3.0、2.0、1.1、1.0 .NET Framework Client Profile 受以下版本支持:4、3.5 SP1 受以下版本支持:

适用平台

Windows 7, Windows Vista SP1 或更高版本, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008(不支持服务器核心), Windows Server 2008 R2(支持 SP1 或更高版本的服务器核心), Windows Server 2003 SP2 .NET Framework 并不是对每个平台的所有版本都提供支持。有关支持的版本的列表,请参见.NET Framework 系统要求。