basis/roman/roman-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax math multiline strings ;
   4 IN: roman
   5
   6 HELP: >roman
   7 { $values n: integer str: string }
   8 { $description Converts a number to its lower-case Roman Numeral equivalent. }
   9 { $notes The range for this word is 1-3999, inclusive. }
  10 { $examples
  11     [=[
  12         USING: io roman ;
  13         56 >roman print
  14         lvi
  15     ]=]
  16 } ;
  17
  18 HELP: >ROMAN
  19 { $values n: integer str: string }
  20 { $description Converts a number to its upper-case Roman numeral equivalent. }
  21 { $notes The range for this word is 1-3999, inclusive. }
  22 { $examples
  23     [=[
  24         USING: io roman ;
  25         56 >ROMAN print
  26         LVI
  27     ]=]
  28 } ;
  29
  30 HELP: roman>
  31 { $values str: string n: integer }
  32 { $description Converts a Roman numeral to an integer. }
  33 { $notes The range for this word is i-mmmcmxcix, inclusive. }
  34 { $examples
  35     [=[ USING: prettyprint roman ;
  36         "lvi" roman> .
  37         56
  38     ]=]
  39 } ;
  40
  41 { >roman >ROMAN roman> } related-words
  42
  43 HELP: roman+
  44 { $values x: string y: string z: string }
  45 { $description Adds two Roman numerals. }
  46 { $examples
  47     [=[ USING: io roman ;
  48         "v" "v" roman+ print
  49         x
  50     ]=]
  51 } ;
  52
  53 HELP: roman-
  54 { $values x: string y: string z: string }
  55 { $description Subtracts two Roman numerals. }
  56 { $examples
  57     [=[ USING: io roman ;
  58         "x" "v" roman- print
  59         v
  60     ]=]
  61 } ;
  62
  63 { roman+ roman- } related-words
  64
  65 HELP: roman*
  66 { $values x: string y: string z: string }
  67 { $description Multiplies two Roman numerals. }
  68 { $examples
  69     [=[ USING: io roman ;
  70         "ii" "iii" roman* print
  71         vi
  72     ]=]
  73 } ;
  74
  75 HELP: roman/i
  76 { $values x: string y: string z: string }
  77 { $description Computes the integer division of two Roman numerals. }
  78 { $examples
  79     [=[ USING: io roman ;
  80         "v" "iv" roman/i print
  81         i
  82     ]=]
  83 } ;
  84
  85 HELP: roman/mod
  86 { $values x: string y: string z: string w: string }
  87 { $description Computes the quotient and remainder of two Roman numerals. }
  88 { $examples
  89     [=[ USING: kernel io prettyprint roman ;
  90         "v" "iv" roman/mod [ print ] bi@
  91         i\ni
  92     ]=]
  93 } ;
  94
  95 { roman* roman/i roman/mod } related-words
  96
  97 HELP: ROMAN:
  98 { $description A parsing word that reads the next token and converts it to an integer. }
  99 { $examples
 100     [=[ USING: prettyprint roman ;
 101         ROMAN: v .
 102         5
 103     ]=]
 104 } ;
 105
 106 ARTICLE: "roman" "Roman numerals"
 107 The { $vocab-link "roman" } vocabulary can convert numbers to and from the
 108 Roman numeral system and can perform arithmetic given Roman numerals as input.
 109
 110 A parsing word for literal Roman numerals:
 111 { $subsections POSTPONE: ROMAN: }
 112
 113 Converting to Roman numerals:
 114 { $subsections
 115     >roman
 116     >ROMAN
 117 }
 118
 119 Converting Roman numerals to integers:
 120 { $subsections roman> }
 121
 122 Roman numeral arithmetic:
 123 { $subsections
 124     roman+
 125     roman-
 126     roman*
 127     roman/i
 128     roman/mod
 129 } ;
 130
 131 ABOUT: "roman"