std.format Package

Function Description

The format package provides the formatting capability to convert Cangjie instances to formatted strings.

This package defines the Formatter interface to specify a unified formatting method and implements the Formatter interface for a series of Cangjie types such as Rune and Int8. Users can also implement the Formatter interface for other types to obtain the formatting function.

When a Cangjie type is converted to a string, the string format, such as the width and alignment mode, can be specified according to the formatting parameter. (In the Formatter interface method, the formatting parameter is used as the input parameter of the function).

The syntax of the formatting parameter is described as follows:

format_spec := [flags][width][.precision][specifier]

flags := '-' | '+' | '#' | '0'

width := integer

precision := integer

specifier := 'b' | 'B' | 'o' | 'O' | 'x' | 'X' | 'e' | 'E' | 'g' | 'G'

flags parameter:

• '-' applies to the Int, UInt, Rune, and Float types, indicating left alignment.

  Code:

  import std.format.*
  
  main() {
      var c : Int32 = -20
      print("\"${c.format("-10")}\"")
  }
  

  Running result:

  "-20       "
  

• '+' applies to the Int, UInt, and Float types. If the value is a positive number, '+' is used. If the value is a negative number, ignore it.

  Code:

  import std.format.*
  
  main() {
      var c: Int32 = 20
      print("\"${c.format("+10")}\"")
  }
  

  Running result:

  "       +20"
  

• '#' is used for printing in binary format. For printing in binary format, '0b' or '0B' is added. For printing in octal format, '0o' or '0O' is added. For printing in hexadecimal format, '0x' or '0X' is added.

  Code:

  import std.format.*
  
  main() {
      var c: Int32 = 1
      print("\"${c.format("#10x")}\"")
  }
  

  Running result:

  "       0x1"
  

• '0' applies to the Int, UInt, and Float types and empty data bits are padded with 0s.

  Code:

  import std.format.*
  
  main() {
      var c: Int32 = -20
      print("\"${c.format("010")}\"")
  }
  

  Running result:

  "-000000020"
  

width parameter:

• The width parameter must be a positive integer and applies to the Int, UInt, Rune, and Float types. The width parameter with a negative sign (–) indicates left-aligned output. If there is no minus sign (–), it indicates right-aligned output. If the value of width is less than that of the parameter to be formatted, no truncation occurs. If the prefix contains + or -, the prefix occupies one character. If the prefix contains 0x or 0o, the prefix occupies two characters.

  Code:

  import std.format.*
  
  main() {
      var c: Int32 = 20
      println("\"${c.format("1")}\"")
      println("\"${c.format("+4")}\"")
  }
  

  Running result:

  "20"
  " +20"
  

precision parameter:

• The precision parameter must be a positive integer and applies to the Int, UInt, and Float types. For a floating-point number, it indicates the number of valid digits after the decimal point. If this parameter is not specified, six decimal places are printed. If the value of precision is less than that of the parameter to be formatted, the floating-point number is rounded off. If the value of precision is greater than that of the parameter to be formatted, the decimal places of the floating-point number are supplemented by values which are not necessarily 0s.

• For an integer, if this parameter is not specified or the specified value is less than that of the parameter to be formatted, the output is the same as the original number. If the value of precision is greater than that of the parameter to be formatted, '0' is padded before the integer.

  Code:

  import std.format.*
  
  main() {
      var e: Float32 = 1234.1
      println("\"${e.format("20.20")}\"")
      var c: Int32 = -20
      println("\"${c.format("10.8")}\"")
  }
  

  Running result:

  "1234.09997558593750000000"
  " -00000020"
  

specifier parameter:

• 'b' | 'B', 'o' | 'O', and 'x' | 'X' apply to the Int and UInt types.

  'b'|'B' indicates printing in binary format.

  'o'|'O' indicates printing in octal format.

  'x'|'X' indicates printing in hexadecimal format.

  Code:

  import std.format.*
  
  main() {
      var a = 20
      println("\"${a.format("b")}\"")
      println("\"${a.format("o")}\"")
      println("\"${a.format("x")}\"")
      println("\"${a.format("X")}\"")
      println("\"${a.format("#X")}\"")
  }
  

  Running result:

  "10100"
  "24"
  "14"
  "14"
  "0X14"
  

• 'e' | 'E' and 'g' | 'G' apply to the Float type.

  'e' | 'E': scientific notation, lowercase and uppercase

  'g' | 'G': general, expressed in decimal or scientific notation, with the simplified notation used for printing

  Code:

  import std.format.*
  
  main() {
      var f: Float32 = 1234.1
      var c: Float32 = 123412341234.1
      println("\"${f.format("20.2e")}\"")
      println("\"${f.format("20G")}\"")
      println("\"${c.format("20G")}\"")
      println("\"${f.format("20")}\"")
      println("\"${c.format("20")}\"")
  }
  

  Running result:

  "            1.23e+03"
  "              1234.1"
  "         1.23412E+11"
  "         1234.099976"
  " 123412340736.000000"
  

API List

Interface