File: manual.txt

-----------------------------------
Currency Convert & Display Classes.
---------- User's Manual ----------
-----------------------------------

1) Overview
----------
The goal of the classes is to ease conversion between currencies
and to perform display of converted values according to local formats.
Display is decoupled from Conversion to enhance software design, ease
updates or debugging and answer to programming needs (currency conversion
is not necessarily followed by display nor pre-computed currency values
need to be converted before display).

Display and Conversion classes use parameters described in the following
sections of this document.

2) Currency Display class
-------------------------
 2.1) Use :
 ----------
Simply include 'class_currency_display.php' in your source code

 2.2) Goal :
 -----------
Currency display greatly varies from a country to another, especially on
the decimal symbol or on negative values.
The CurrencyDisplay class can be set with those local parameters.
Once they are set, you just forget them and you easily display values related to currencies.

 2.3) Display Parameters
 -----------------------
The following parameters (properties) are used by the class :
- $id : identification string related with the currency and freely definable by the user.
It can be used, for example, to store a database information or for debuggging.
- $symbol : contains the currency symbol or string to display (ex: 'F' for french franc')
- $nbDecimal : number of digits to display past the decimal symbol. If the value to display
is an integer and $nbDecimal is not set to 0 then the display is padded with '0' past the
decimal symbol.
- $decimal : character used as decimal symbol ('.', ',', ...).
- $thousands : thousands separator ('', ' ', ',')
- $positivePos : Display format with positive numbers. Possible values are :
	0 = '00Symb'
	1 = '00 Symb'
	2 = 'Symb00'
	3 = 'Symb 00'
- $negativePos : Display format with negative numbers. Possible values are :
	0  = '(Symb00)'
	1  = '-Symb00'
	2  = 'Symb-00'
	3  = 'Symb00-'
	4  = '(00Symb)'
	5  = '-00Symb'
	6  = '00-Symb'
	7  = '00Symb-'
	8  = '-00 Symb'
	9  = '-Symb 00'
	10 = '00 Symb-'
	11 = 'Symb 00-'
	12 = 'Symb -00'
	13 = '00- Symb'
	14 = '(Symb 00)'
	15 = '(00 Symb)'

 2.4) CurrencyDisplay class methods
 ----------------------------------
* Constructor : 
  CurrencyDisplay($id,$symbol,$nbDecimal,$decimal,$thousands,$positivePos,$negativePos);
Creates a new instance of the class with the parameters described above.
Default values are :
	$id		= "euro"
	$symbol		= "€"
	$nbDecimal	= 2	// 2 digits past decimal symbol
	$decimal   	= ","	// Decimal symbol is ','
	$thousands 	= " "	// thousands separator is ' '
	$positivePos	= 1	// Format for positive value : '-Symb00'
	$negativePos	= 8	// Format for negative value : '-00 Symb'
Default values are for the Euro currency with display in Netscape navigator.

* getSymbol()
Returns Currency Symbol string

* getId()
Returns identification Symbol string.

* getValue($nb)
Returns the formated numeric value corresponding to the number $nb passed as parameter.
Does not display currency symbol nor special formatting for negative value.
Warning : if the number as more decimal digits than the class is set for, the number
is rounded. User must provide numbers with the same decimal accuracy expected by the
class. It's not a bug : it's a feature.

* getFullValue($nb)
Display the fully formated numeric value corresponding to the number $nb passed as parameter.
It include display of currency symbol and take intop accounts negative and positive values
particularities.
Warning : if the number as more decimal digits than the class is set for, the number
is rounded. User must provide numbers with the same decimal accuracy expected by the
class. It's not a bug : it's a feature.

 2.5) Tip :
 ----------
Use select_display.php (located in the 'selector' sample) to help you define
the parameters values that fit your need


3) Currency Conversion class
----------------------------
 3.1) Use :
 ----------
Simply include 'class_currency_convert.php' in your source code

 3.2) Goal :
 -----------
Currency conversion is a boring, repettive task for developpers. It also relies on well defined rules.
But risks of errors grow, on multi-currencies sites, with the number of conversions.
The CurrencyConvert class gathers the various rules and reduce of error :
Once the class corresponding to a conversion between two currencies is instantiated,
multiple conversions can be repeatedly performed.

 3.3) Convert Parameters
 -----------------------
The following parameters (properties) are used by the class :
- $idFrom : identification string related with the currency TO BE CONVERTED, also known
as the SOURCE currency. the label is freely definable by the user. It can be used,
for example, for programming need, to store a database information or for debuggging.
- $idTo : Label used to identify the the currency TO CONVERT, also known as the TARGET currency.
- $rate : conversion rate between the SOURCE and TARGET currencies
- $rounding : specify how the TARGET value is rounded.
examples : a $rounding of 0.01 gives values rounded to 2 decimal digits, rounding of 0.5
produces values rounded by steps of 0.5 (19.5, 20, 20.5, ...).
- $roundType : Kind of rounding. Possible values are : 
	0 = Inferior (using floor() function) ,
	1 = Normal (using round() function) ,
	2 = Superior (using ceil() function) ,
	3 = None (number is returned 'as is' or with implicit rounding)
NOTE : the couple ( $rounding, $roundtype ) allows to perform every possible kind of conversion.
- $nbDecimal : number of decimal digits. Can be padded with '0' if the value has not enough
decimal digits to match this defined in parameter (ex: 3.4 with $nbDecimal=2 gives 3.40) 

 3.4) CurrencyConvert class methods
 ----------------------------------
* Constructor : 
CurrencyConvert($rate,$rounding,$roundType,$nbDecimal,$idFrom,$idTo)
Creates a new instance of the class with the parameters described above.

* From()
Returns the name of the source currency

* To()
Returns the name of the target currency

* getValue($nb)
Returns the numeric value, suitable for use with the CurrencyDisplay class

* getStringValue($nb)
Returns a string, instead of an int or float, formated with the number of decimal digits defined by
the $nbDecimal parameter. The value is also suitable with CurrencyDisplay class through an implicit
or explicit float/integer casting.

 3.5) Tip :
 ----------
Use select_convert.php (located in the 'selector' sample) to help you define
the parameters values that fit your need