Treasury bill fixes

[Neil Booth <neil daikokuya demon co uk>]

This fixes the Treasury Bill functions, and improves their
documentation.  There were obvious typos in the code before.

Excel uses an (arbitrary) constraint of <= 365 days between settlement
and maturity, rather than 1 year like it documents, so I've kept the
Excel constraint for compatibiility, but documented it more precisely.

I've also updated MW's comment, as he was doing the right thing <tm>.

Neil.

        * fn-financial.c (help_tbilleq, help_tbillprice, help_tbillyeild):
        Clarify documentation, and make it more precise.
        * (tbilleq, tbillprice, tbillyield): Should be 365 not 356.

Index: fn-financial.c
===================================================================
RCS file: /cvs/gnome/gnumeric/src/functions/fn-financial.c,v
retrieving revision 1.111
diff -u -p -r1.111 fn-financial.c
--- fn-financial.c      2001/12/21 23:51:27     1.111
+++ fn-financial.c      2002/01/12 09:29:38
@@ -1892,15 +1892,18 @@ static char *help_tbilleq = {
        N_("@FUNCTION=TBILLEQ\n"
           "@SYNTAX=TBILLEQ(settlement,maturity,discount)\n"
           "@DESCRIPTION="
-          "TBILLEQ function returns the bond-yield equivalent (BEY) for "
-          "a treasury bill.  TBILLEQ is equivalent to (365 * @discount) / "
-          "(360 - @discount * DSM) where DSM is the days between @settlement "
-          "and @maturity. "
-          "\n"
-          "If @settlement is after @maturity or the @maturity is set to "
-          "over one year later than the @settlement, TBILLEQ returns "
-          "#NUM! error. "
-          "If @discount is negative, TBILLEQ returns #NUM! error. "
+          "TBILLEQ returns the bond-equivalent yield (BEY) for a "
+          "treasury bill on the settlement date, given its discount yield.  "
+          "It is equivalent to (365 * @discount) / (360 - @discount * DSM) "
+          "where DSM is the days between @settlement and @maturity.  "
+          "This calculation follows the conventions of the U.S. treasury "
+          "bill market, and is probably of little use in other markets. "
+          "\n"
+          "If @settlement is after @maturity or @maturity is more than "
+          "365 days after @settlement, TBILLEQ returns the #NUM! error. "
+          "@discount is the discount yield, as a percentage (so a 5% "
+          "yield is input as 0.05, not 5).  If @discount is negative, "
+          "TBILLEQ returns the #NUM! error. "
           "\n"
           "@EXAMPLES=\n"
           "\n"
@@ -1919,12 +1922,11 @@ gnumeric_tbilleq (FunctionEvalInfo *ei, 
 
        dsm = maturity - settlement;
 
-       if (settlement > maturity || discount < 0 || dsm > 356)
+       if (settlement > maturity || discount < 0 || dsm > 365)
                 return value_new_error (ei->pos, gnumeric_err_NUM);
 
        divisor = 360 - discount * dsm;
-       /* This test probably isn't right, but it is better that not checking
-          at all.  --MW.  */
+       /* Avoid division by zero, which indicates bogus inputs.  */
        if (divisor == 0)
                return value_new_error (ei->pos, gnumeric_err_DIV0);
 
@@ -1937,15 +1939,17 @@ static char *help_tbillprice = {
        N_("@FUNCTION=TBILLPRICE\n"
           "@SYNTAX=TBILLPRICE(settlement,maturity,discount)\n"
           "@DESCRIPTION="
-          "TBILLPRICE function returns the price per $100 value for a "
-          "treasury bill where @settlement is the settlement date and "
-          "@maturity is the maturity date of the bill.  @discount is the "
-          "treasury bill's discount rate. "
-          "\n"
-          "If @settlement is after @maturity or the @maturity is set to "
-          "over one year later than the @settlement, TBILLPRICE returns "
-          "#NUM! error. "
-          "If @discount is negative, TBILLPRICE returns #NUM! error. "
+          "TBILLPRICE returns the price of a treasury bill on the "
+          "settlement date, per $100 face value, given its discount "
+          "yield.  It does the reverse of the function TBILLYIELD.  "
+          "@settlement is the settlement date and @maturity is the maturity "
+          "date of the bill.  @discount is the bill's discount rate. "
+          "\n"
+          "If @settlement is after @maturity or @maturity is more than "
+          "365 days after @settlement, TBILLEQ returns the #NUM! error. "
+          "@discount is the discount yield, as a percentage (so a 5% "
+          "yield is input as 0.05, not 5).  If @discount is negative, "
+          "TBILLEQ returns the #NUM! error. "
           "\n"
           "@EXAMPLES=\n"
           "\n"
@@ -1964,7 +1968,7 @@ gnumeric_tbillprice (FunctionEvalInfo *e
 
        dsm = maturity - settlement;
 
-       if (settlement > maturity || discount < 0 || dsm > 356)
+       if (settlement > maturity || discount < 0 || dsm > 365)
                 return value_new_error (ei->pos, gnumeric_err_NUM);
 
        res = 100 * (1.0 - (discount * dsm) / 360.0);
@@ -1978,14 +1982,17 @@ static char *help_tbillyield = {
        N_("@FUNCTION=TBILLYIELD\n"
           "@SYNTAX=TBILLYIELD(settlement,maturity,pr)\n"
           "@DESCRIPTION="
-          "TBILLYIELD function returns the yield for a treasury bill. "
-          "@settlement is the settlement date and @maturity is the "
-          "maturity date of the bill.  @discount is the treasury bill's "
-          "discount rate. "
-          "\n"
-          "If @settlement is after @maturity or the @maturity is set to "
-          "over one year later than the @settlement, TBILLYIELD returns "
-          "#NUM! error. "
+          "TBILLYIELD returns the yield of a treasury bill on the "
+          "settlement date, given its price, using the discount yield "
+          "convention.  It does the reverse of the function TBILLPRICE. "
+          "@settlement is the settlement date and @maturity is the maturity "
+          "date of the bill.  @discount is the bill's discount rate. "
+          "\n"
+          "If @settlement is on or after @maturity or @maturity is more than "
+          "365 days after @settlement, TBILLEQ returns the #NUM! error. "
+          "@discount is the discount yield, as a percentage (so a 5% "
+          "yield is input as 0.05, not 5).  If @discount is negative, "
+          "TBILLEQ returns the #NUM! error. "
           "If @pr is negative, TBILLYIELD returns #NUM! error. "
           "\n"
           "@EXAMPLES=\n"
@@ -2005,7 +2012,7 @@ gnumeric_tbillyield (FunctionEvalInfo *e
 
        dsm = maturity - settlement;
 
-       if (pr <= 0 || dsm <= 0 || dsm > 356)
+       if (pr <= 0 || dsm <= 0 || dsm > 365)
                 return value_new_error (ei->pos, gnumeric_err_NUM);
 
        res = (100.0 - pr) / pr * (360.0 / dsm);