std.convert

Overview

The convert package provides a series of Convert functions for converting strings to specific types.

For example, the string true can be converted to the Boolean type true, and the string 123 can be converted to the integer type 123.

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

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

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 Formattable 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'

Parameter flags:

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

  Code:

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

  Results:

  "-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, + is not supported.

  Code:

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

  Results:

  "       +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.convert.*
  
  main() {
      var c: Int32 = 1
      print("\"${c.format("#10x")}\"")
  }
  

  Results:

  "       0x1"
  

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

  Code:

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

  Results:

  "-000000020"
  

Parameter width:

• 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.convert.*
  
  main() {
      var c: Int32 = 20
      println("\"${c.format("1")}\"")
      println("\"${c.format("+4")}\"")
  }
  

  Results:

  "20"
  " +20"
  

Parameter precision:

• 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.convert.*
  
  main() {
      var e: Float32 = 1234.1
      println("\"${e.format("20.20")}\"")
      var c: Int32 = -20
      println("\"${c.format("10.8")}\"")
  }
  

  Results:

  "1234.09997558593750000000"
  " -00000020"
  

Parameter specifier:

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

  b | B indicate printing in binary format.

  o | O indicate printing in octal format.

  x | X indicate printing in hexadecimal format.

  Code:

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

  Results:

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

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

  e | E indicate scientific notation, lowercase, and uppercase.

  g | G stand for general, which are expressed in decimal or scientific notation, with the simplified notation used for printing.

  Code:

  import std.convert.*
  
  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")}\"")
  }
  

  Results:

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

API List

Interface