README
1** Introduction:
2
3With PEAR::Numbers_Words class you can change an integer number
4to simple words. This can be usefull when you need to spell a currency
5value e.g. on an invoice.
6
7You can choose between several languages (language files are located
8in Numbers/Words/ directory).
9
10BTW: if you need to change number to currency, use money_format()
11PHP function (available since 4.3 (not yet released)). But you must
12know that locale LC_MONETARY rules are sometimes unclear.
13
14** Getting started:
15
16First you need to install Numbers_Words PEAR package.
17You can do it (as root) with:
18
19 pear install Numbers_Words
20
21In your php script you need to load Numbers/Words.php header file:
22
23 require_once('Numbers/Words.php');
24
25Then you can call Numbers_Words::toWords() function with two
26arguments: integer number (can be a string with digits) and
27optional locale name (default is en_US):
28
29$ret = Numbers_Words::toWords($num,"en_GB");
30if (PEAR::isError($ret)) {
31 echo "Error: " . $ret->message . "\n";
32 } else {
33 echo "Num $num in British English is '<b>$ret</b>'<p>\n";
34}
35
36For this would display:
37
38Num 12340000000 in British English is '<b>twelve thousand million three hundred forty million</b>'<p>
39
40** Current State:
41
42The current release can be found at the PEAR webpage:
43 http://pear.php.net/package-info.php?package=Numbers_Words
44
45For the time of writting this Readme file, Numbers_spell package has the
46status beta, which means there can be samo bugs, and it is under development.
47This is not mature code.
48
49** Development
50
51This package needs help from people, who can write language modules other
52than Polish and English.
53
54** Package Content:
55
56 Readme.txt - this file
57 ChangeLog - change log
58 test-numbers-words.php - test file showing Numbers_Words example usage
59 Words.php - main class file, that loads language modules on demand
60 Words/lang.{LOCALE_NAME}.php - language modules
61
62There are avaibale the following modules (called by locale name,
63in alphabetical order):
64
65 bg - Bulgarian language (in WIN-1251 charset).
66 Author: Kouber Saparev
67
68 cs - Czech language.
69 Author: Petr 'PePa' Pavel
70
71 de - German language.
72 Author: Piotr Klaban
73
74 dk - Danish language.
75 Author: Jesper Veggerby
76
77 en_100 - Donald Knuth number naming system, in English language.
78 Author: Piotr Klaban
79
80 en_GB - British English notation of numbers, where
81 one billion is 1000000 times one million.
82 1000 times million is just 'thousand million' here.
83 I do not use a word billiard here, because
84 English people do not use it often, and even could not know it.
85 Author: Piotr Klaban
86
87 en_US - American English notation of numbers, where
88 one billion is 1000 times one million
89 Author: Piotr Klaban
90
91 es - Spanish (Castellano) language.
92 Author: Xavier Noguer
93
94 es_AR - Argentinian Spanish language.
95 Author: Martin Marrese
96
97 et - Estonian language.
98 Author: Erkki Saarniit
99
100 fr - French language.
101 Author: Kouber Saparev
102
103 fr_BE - French (Belgium) language.
104 Author: Kouber Saparev, Philippe Bajoit
105
106 he - Hebrew language.
107 Author: Hadar Porat
108
109 hu_HU - Hungarian language.
110 Author: Nils Homp
111
112 id - Indonesia language.
113 Authors: Ernas M. Jamil, Arif Rifai Dwiyanto
114
115 it_IT - Italian language.
116 Authors: Filippo Beltramini, Davide Caironi
117
118 lt - Lithuanian language.
119 Author: Laurynas Butkus
120
121 nl - Dutch language.
122 Author: WHAM van Dinter
123
124 pl - Polish language (in an internet standard charset ISO-8859-2)
125 Author: Piotr Klaban
126
127 pt_BR - Brazilian Portuguese language.
128 Authors: Marcelo Subtil Marcal, Mario H.C.T., Igor Feghali
129
130 ru - Russian language.
131 Author: Andrey Demenev
132
133 sv - Swedich language.
134 Author: Robin Ericsson
135
136 tr_TR - Turkish language.
137 Author: Shahriyar Imanov
138
139** What if numbers have fraction part?
140
141You can split the number by the coma or dot. The example
142function was provided by Ernas M. Jamil (see below).
143I do not know if the splitting and concatenating numbers
144should be supported by Numbers_Words ... Does each language
145spell numbers with a 'coma'/'koma'? What do you think?
146
147function num2word($num, $fract = 0) {
148 require_once('Numbers/Words.php');
149
150 $num = sprintf("%.".$fract."f", $num);
151 $fnum = explode('.', $num);
152
153 $ret = Numbers_Words::toWords($fnum[0],"id");
154 if(!$fract) return $ret;
155
156 $ret .= ' koma '; // point in english
157 $ret .= Numbers_Words::toWords($fnum[1],"id");
158
159 return $ret;
160}
161
162** How to convert decimal part and not fraction part of the currency value?
163
164Rob King send me a patch that would allow to leave fraction part in digits.
165I.e. you can convert 31.01 into 'thirty-one pounds 01 pence':
166
167 require_once('Numbers/Words.php');
168 require_once('Numbers/Words/lang.en_GB.php');
169
170 $obj = new Numbers_Words_en_GB;
171 $convert_fraction = false;
172 print $obj->toCurrencyWords('GBP', '31', '01', $convert_fraction) . "\n";
173
174** How to write new Language Files:
175
176Just copy existing en_US or en_GB etc. file into lang.{your_country/locale code}.php
177and translate digits, numbers, tousands to your language. Then please send it
178to the author to the address makler@man.torun.pl.
179
180** Credits
181
182All changes from other people are desrcribed with details in ChangeLog.
183There are also names of the people who send me patches etc.
184Authors of the language files are mentioned in the language files directly
185as the author.
186
187