core/math/parser/parser-docs.factor

   1 USING: byte-arrays help.markup help.syntax math
   2 math.parser.private prettyprint make sequences
   3 strings ;
   4
   5 IN: math.parser
   6
   7 ARTICLE: "number-strings" "Converting between numbers and strings"
   8 "These words only convert between real numbers and strings. Complex numbers are constructed by the parser (" { $link "parser" } ") and printed by the prettyprinter (" { $link "prettyprint" } ")."
   9 $nl
  10 "Integers can be converted to and from arbitrary bases. Floating point numbers can only be converted to and from base 10 and 16."
  11 $nl
  12 "Converting numbers to strings:"
  13 { $subsections
  14     number>string
  15     >bin
  16     >oct
  17     >hex
  18     >base
  19 }
  20 "Converting strings to numbers:"
  21 { $subsections
  22     string>number
  23     bin>
  24     oct>
  25     hex>
  26     base>
  27 }
  28 "You can also input literal numbers in a different base (" { $link "syntax-integers" } ")."
  29 { $see-also "prettyprint-numbers" } ;
  30
  31 ABOUT: "number-strings"
  32
  33 HELP: >digit
  34 { $values { "n" "an integer between 0 and 15" } { "ch" "a character" } }
  35 { $description "Outputs a character representation of a digit." }
  36 { $notes "This is one of the factors of " { $link number>string } "." } ;
  37
  38 HELP: digit>
  39 { $values { "ch" "a character" } { "n" integer } }
  40 { $description "Converts a character representation of a digit to an integer." }
  41 { $notes "This is one of the factors of " { $link string>number } "." } ;
  42
  43 HELP: base>
  44 { $values { "str" string } { "radix" "an integer between 2 and 16" } { "n/f" { $maybe real } } }
  45 { $description "Creates a real number from a string representation with the given radix. The radix for floating point literals can be either base 10 or base 16."
  46 $nl
  47 "Outputs " { $link f } " if the string does not represent a number." } ;
  48
  49 { >base base> } related-words
  50
  51 HELP: string>number
  52 { $values { "str" string } { "n/f" { $maybe real } } }
  53 { $description "Creates a real number from a string representation of a number in base 10."
  54 $nl
  55 "Outputs " { $link f } " if the string does not represent a number." } ;
  56
  57 { string>number number>string } related-words
  58
  59 HELP: bin>
  60 { $values { "str" string } { "n/f" { $maybe real } } }
  61 { $description "Creates a real number from a string representation of a number in base 2."
  62 $nl
  63 "Outputs " { $link f } " if the string does not represent a number." } ;
  64
  65 { >bin bin> .b } related-words
  66
  67 HELP: oct>
  68 { $values { "str" string } { "n/f" { $maybe real } } }
  69 { $description "Creates a real number from a string representation of a number in base 8."
  70 $nl
  71 "Outputs " { $link f } " if the string does not represent a number." } ;
  72
  73 { >oct oct> .o } related-words
  74
  75 HELP: hex>
  76 { $values { "str" string } { "n/f" { $maybe real } } }
  77 { $description "Creates a real number from a string representation of a number in base 16."
  78 $nl
  79 "Outputs " { $link f } " if the string does not represent a number." } ;
  80
  81 { >hex hex> .h } related-words
  82
  83 HELP: >base
  84 { $values { "n" real } { "radix" "an integer between 2 and 16" } { "str" string } }
  85 { $description "Converts a real number into a string representation using the given radix. If the number is a " { $link float } ", the radix can be either base 10 or base 16." } ;
  86
  87 HELP: >bin
  88 { $values { "n" real } { "str" string } }
  89 { $description "Outputs a string representation of a number using base 2." } ;
  90
  91 HELP: >oct
  92 { $values { "n" real } { "str" string } }
  93 { $description "Outputs a string representation of a number using base 8." } ;
  94
  95 HELP: >hex
  96 { $values { "n" real } { "str" string } }
  97 { $description "Outputs a string representation of a number using base 16." }
  98 { $examples
  99     { $example
 100         "USING: math.parser prettyprint ;"
 101         "3735928559 >hex ."
 102         "\"deadbeef\""
 103     }
 104     { $example
 105         "USING: math.parser prettyprint ;"
 106         "-15.5 >hex ."
 107         "\"-1.fp3\""
 108     }
 109 } ;
 110
 111 HELP: number>string
 112 { $values { "n" real } { "str" string } }
 113 { $description "Converts a real number to a string." }
 114 { $notes "Printing complex numbers requires the more general prettyprinter facility (see " { $link "prettyprint" } ")." } ;
 115
 116 HELP: #
 117 { $values { "n" real } }
 118 { $description "Appends the string representation of a real number to the end of the sequence being constructed by " { $link make } "." } ;
 119
 120 HELP: bytes>hex-string
 121 { $values { "bytes" sequence } { "hex-string" string } }
 122 { $description "Converts a sequence of bytes (integers in the range [0,255]) to a string of hex numbers in the range [00,ff]." }
 123 { $examples
 124     { $example "USING: math.parser prettyprint ;" "B{ 1 2 3 4 } bytes>hex-string ." "\"01020304\"" }
 125 }
 126 { $notes "Numbers are zero-padded on the left." } ;
 127
 128 HELP: hex-string>bytes
 129 { $values { "hex-string" sequence } { "bytes" byte-array } }
 130 { $description "Converts a sequence of hex numbers in the range [00,ff] to a sequence of bytes (integers in the range [0,255])." }
 131 { $examples
 132     { $example "USING: math.parser prettyprint ;" "\"cafebabe\" hex-string>bytes ." "B{ 202 254 186 190 }" }
 133 } ;
 134
 135 { bytes>hex-string hex-string>bytes } related-words