core/math/parser/parser-docs.factor

   1 USING: help.markup help.syntax math math.private prettyprint
   2 namespaces strings ;
   3 IN: math.parser
   4
   5 ARTICLE: "number-strings" "Converting between numbers and strings"
   6 "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" } ")."
   7 $nl
   8 "Note that only integers can be converted to and from strings using a representation other than base 10. Calling a word such as " { $link >oct } " on a float will give a result in base 10."
   9 $nl
  10 "Converting numbers to strings:"
  11 { $subsection number>string }
  12 { $subsection >bin }
  13 { $subsection >oct }
  14 { $subsection >hex }
  15 { $subsection >base }
  16 "Converting strings to numbers:"
  17 { $subsection string>number }
  18 { $subsection bin> }
  19 { $subsection oct> }
  20 { $subsection hex> }
  21 { $subsection base> }
  22 "You can also input literal numbers in a different base (" { $link "syntax-integers" } ")."
  23 { $see-also "prettyprint-numbers" } ;
  24
  25 ABOUT: "number-strings"
  26
  27 HELP: digits>integer
  28 { $values { "seq" "a sequence of integers" } { "radix" "an integer between 2 and 36" } { "n" integer } }
  29 { $description "Converts a sequence of digits (with most significant digit first) into an integer." }
  30 { $notes "This is one of the factors of " { $link string>number } "." } ;
  31
  32 HELP: >digit
  33 { $values { "n" "an integer between 0 and 35" } { "ch" "a character" } }
  34 { $description "Outputs a character representation of a digit." }
  35 { $notes "This is one of the factors of " { $link number>string } "." } ;
  36
  37 HELP: digit>
  38 { $values { "ch" "a character" } { "n" integer } }
  39 { $description "Converts a character representation of a digit to an integer." }
  40 { $notes "This is one of the factors of " { $link string>number } "." } ;
  41
  42 HELP: base>
  43 { $values { "str" string } { "radix" "an integer between 2 and 36" } { "n/f" "a real number or " { $link f } } }
  44 { $description "Creates a real number from a string representation with the given radix. The radix is ignored for floating point literals; they are always taken to be in base 10."
  45 $nl
  46 "Outputs " { $link f } " if the string does not represent a number." } ;
  47
  48 { >base base> } related-words
  49
  50 HELP: string>number
  51 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
  52 { $description "Creates a real number from a string representation of a number in base 10."
  53 $nl
  54 "Outputs " { $link f } " if the string does not represent a number." } ;
  55
  56 { string>number number>string } related-words
  57
  58 HELP: bin>
  59 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
  60 { $description "Creates a real number from a string representation of a number in base 2."
  61 $nl
  62 "Outputs " { $link f } " if the string does not represent a number." } ;
  63
  64 { bin> POSTPONE: BIN: bin> .b } related-words
  65
  66 HELP: oct>
  67 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
  68 { $description "Creates a real number from a string representation of a number in base 8."
  69 $nl
  70 "Outputs " { $link f } " if the string does not represent a number." } ;
  71
  72 { oct> POSTPONE: OCT: oct> .o } related-words
  73
  74 HELP: hex>
  75 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
  76 { $description "Creates a real number from a string representation of a number in base 16."
  77 $nl
  78 "Outputs " { $link f } " if the string does not represent a number." } ;
  79
  80 { hex> POSTPONE: HEX: hex> .h } related-words
  81
  82 HELP: >base
  83 { $values { "n" real } { "radix" "an integer between 2 and 36" } { "str" string } }
  84 { $description "Converts a real number into a string representation using the given radix. If the number is a float, the radix is ignored and the output is always in base 10." } ;
  85
  86 HELP: >bin
  87 { $values { "n" real } { "str" string } }
  88 { $description "Outputs a string representation of a number using base 2." } ;
  89
  90 HELP: >oct
  91 { $values { "n" real } { "str" string } }
  92 { $description "Outputs a string representation of a number using base 8." } ;
  93
  94 HELP: >hex
  95 { $values { "n" real } { "str" string } }
  96 { $description "Outputs a string representation of a number using base 16." } ;
  97
  98 HELP: string>float ( str -- n/f )
  99 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
 100 { $description "Primitive for creating a float from a string representation." }
 101 { $notes "The " { $link string>number } " word is more general."
 102 $nl
 103 "Outputs " { $link f } " if the string does not represent a float." } ;
 104
 105 HELP: float>string ( n -- str )
 106 { $values { "n" real } { "str" string } }
 107 { $description "Primitive for getting a string representation of a float." }
 108 { $notes "The " { $link number>string } " word is more general." } ;
 109
 110 HELP: number>string
 111 { $values { "n" real } { "str" string } }
 112 { $description "Converts a real number to a string." }
 113 { $notes "Printing complex numbers requires the more general prettyprinter facility (see " { $link "prettyprint" } ")." } ;
 114
 115 HELP: #
 116 { $values { "n" real } }
 117 { $description "Appends the string representation of a real number to the end of the sequence being constructed by " { $link make } "." } ;