basis/formatting/formatting-docs.factor

   1
   2 USING: help.syntax help.markup kernel prettyprint sequences strings ;
   3
   4 IN: formatting
   5
   6 HELP: printf
   7 { $values { "format-string" string } }
   8 { $description
   9     "Writes the arguments (specified on the stack) formatted according to the format string.\n"
  10     $nl
  11     "Several format specifications exist for handling arguments of different types, and "
  12     "specifying attributes for the result string, including such things as maximum width, "
  13     "padding, and decimals.\n"
  14     { $table
  15         { "%%"          "Single %"                   "" }
  16         { "%P.Ds"       "String format"              "string" }
  17         { "%P.DS"       "String format uppercase"    "string" }
  18         { "%c"          "Character format"           "char" }
  19         { "%C"          "Character format uppercase" "char" }
  20         { "%+Pd"        "Integer format"             "fixnum" }
  21         { "%+P.De"      "Scientific notation"        "fixnum, float" }
  22         { "%+P.DE"      "Scientific notation"        "fixnum, float" }
  23         { "%+P.Df"      "Fixed format"               "fixnum, float" }
  24         { "%+Px"        "Hexadecimal"                "hex" }
  25         { "%+PX"        "Hexadecimal uppercase"      "hex" }
  26         { "%[%?, %]"    "Sequence format"            "sequence" }
  27         { "%[%?: %? %]" "Assocs format"              "assocs" }
  28     }
  29     $nl
  30     "A plus sign ('+') is used to optionally specify that the number should be "
  31     "formatted with a '+' preceeding it if positive.\n"
  32     $nl
  33     "Padding ('P') is used to optionally specify the minimum width of the result "
  34     "string, the padding character, and the alignment.  By default, the padding "
  35     "character defaults to a space and the alignment defaults to right-aligned. "
  36     "For example:\n"
  37     { $list
  38         "\"%5s\" formats a string padding with spaces up to 5 characters wide."
  39         "\"%03d\" formats an integer padding with zeros up to 3 characters wide."
  40         "\"%'#5f\" formats a float padding with '#' up to 3 characters wide."
  41         "\"%-10d\" formats an integer to 10 characters wide and left-aligns."
  42     }
  43     $nl
  44     "Digits ('D') is used to optionally specify the maximum digits in the result "
  45     "string. For example:\n"
  46     { $list
  47         "\"%.3s\" formats a string to truncate at 3 characters (from the left)."
  48         "\"%.10f\" formats a float to pad-tail with zeros up to 10 digits beyond the decimal point."
  49         "\"%.5E\" formats a float into scientific notation with zeros up to 5 digits beyond the decimal point, but before the exponent."
  50     }
  51 }
  52 { $examples
  53     { $example
  54         "USING: formatting ;"
  55         "123 \"%05d\" printf"
  56         "00123" }
  57     { $example
  58         "USING: formatting ;"
  59         "0xff \"%04X\" printf"
  60         "00FF" }
  61     { $example
  62         "USING: formatting ;"
  63         "1.23456789 \"%.3f\" printf"
  64         "1.235" }
  65     { $example
  66         "USING: formatting ;"
  67         "12 \"%'#4d\" printf"
  68         "##12" }
  69     { $example
  70         "USING: formatting ;"
  71         "1234 \"%+d\" printf"
  72         "+1234" }
  73     { $example
  74         "USING: formatting ;"
  75         "{ 1 2 3 } \"%[%d, %]\" printf"
  76         "{ 1, 2, 3 }" }
  77     { $example
  78         "USING: formatting ;"
  79         "H{ { 1 2 } { 3 4 } } \"%[%d: %d %]\" printf"
  80         "{ 1:2, 3:4 }" }
  81 } ;
  82
  83 HELP: sprintf
  84 { $values { "format-string" string } { "result" string } }
  85 { $description "Returns the arguments (specified on the stack) formatted according to the format string as a result string." }
  86 { $see-also printf } ;
  87
  88 HELP: strftime
  89 { $values { "format-string" string } }
  90 { $description
  91     "Writes the timestamp (specified on the stack) formatted according to the format string.\n"
  92     $nl
  93     "Different attributes of the timestamp can be retrieved using format specifications.\n"
  94     { $table
  95         { "%a"     "Abbreviated weekday name." }
  96         { "%A"     "Full weekday name." }
  97         { "%b"     "Abbreviated month name." }
  98         { "%B"     "Full month name." }
  99         { "%c"     "Date and time representation." }
 100         { "%d"     "Day of the month as a decimal number [01,31]." }
 101         { "%H"     "Hour (24-hour clock) as a decimal number [00,23]." }
 102         { "%I"     "Hour (12-hour clock) as a decimal number [01,12]." }
 103         { "%j"     "Day of the year as a decimal number [001,366]." }
 104         { "%m"     "Month as a decimal number [01,12]." }
 105         { "%M"     "Minute as a decimal number [00,59]." }
 106         { "%p"     "Either AM or PM." }
 107         { "%S"     "Second as a decimal number [00,59]." }
 108         { "%U"     "Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]." }
 109         { "%w"     "Weekday as a decimal number [0(Sunday),6]." }
 110         { "%W"     "Week number of the year (Monday as the first day of the week) as a decimal number [00,53]." }
 111         { "%x"     "Date representation." }
 112         { "%X"     "Time representation." }
 113         { "%y"     "Year without century as a decimal number [00,99]." }
 114         { "%Y"     "Year with century as a decimal number." }
 115         { "%Z"     "Time zone name (no characters if no time zone exists)." }
 116         { "%%"     "A literal '%' character." }
 117     }
 118 }
 119 { $examples
 120     { $unchecked-example
 121         "USING: calendar formatting io ;"
 122         "now \"%c\" strftime print"
 123         "Mon Dec 15 14:40:43 2008" }
 124 } ;
 125
 126 ARTICLE: "formatting" "Formatted printing"
 127 "The " { $vocab-link "formatting" } " vocabulary is used for formatted printing."
 128 { $subsections
 129     printf
 130     sprintf
 131     strftime
 132 } ;
 133
 134 ABOUT: "formatting"
 135
 136