basis/formatting/formatting-docs.factor

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