[Koha-cvs] CVS: koha/C4 Format.pm,1.3,1.4

[Andrew Arensburger]

Update of /cvsroot/koha/koha/C4
In directory usw-pr-cvs1:/tmp/cvs-serv11276

Modified Files:
        Format.pm 
Log Message:
Added POD.


Index: Format.pm
===================================================================
RCS file: /cvsroot/koha/koha/C4/Format.pm,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -r1.3 -r1.4
*** Format.pm   14 Aug 2002 18:12:51 -0000      1.3
--- Format.pm   23 Sep 2002 13:53:18 -0000      1.4
***************
*** 24,34 ****
  
  use vars qw($VERSION @ISA @EXPORT);
!   
  # set the version for version checking
  $VERSION = 0.01;
!     
  @ISA = qw(Exporter);
  @EXPORT = qw(&fmtstr &fmtdec);
  
  sub fmtstr {
    # format (space pad) a string
--- 24,77 ----
  
  use vars qw($VERSION @ISA @EXPORT);
! 
  # set the version for version checking
  $VERSION = 0.01;
! 
! =head1 NAME
! 
! C4::Format - Functions for pretty-printing strings and numbers
! 
! =head1 SYNOPSIS
! 
!   use C4::Format;
! 
! =head1 DESCRIPTION
! 
! These functions return pretty-printed versions of strings and numbers.
! 
! =head1 FUNCTIONS
! 
! =over 2
! 
! =cut
! 
  @ISA = qw(Exporter);
  @EXPORT = qw(&fmtstr &fmtdec);
  
+ =item fmtstr
+ 
+   $str = &fmtstr($env, $string, $format);
+ 
+ Returns C<$string>, padded with space to a given length.
+ 
+ C<$format> is either C<Ln> or C<Rn>, where I<n> is a positive integer.
+ C<$str> will be either left-padded or right-padded, respectively.
+ 
+ C<&fmtstr> is almost equivalent to
+ 
+   sprintf("%-n.ns", $string);
+ 
+ or
+ 
+   sprintf("%n.ns", $string);
+ 
+ The only difference is that if I<n> is less than the length of
+ C<$string>, then C<&fmtstr> will return the last I<n> characters of
+ C<$string>, whereas C<sprintf> will return the first I<n> characters.
+ 
+ C<$env> is ignored.
+ 
+ =cut
+ #'
  sub fmtstr {
    # format (space pad) a string
***************
*** 40,63 ****
       $strg = substr((" "x$lenst).$strg,0-$lenst,$lenst);
    } elsif  ($align eq "C" ) {
!      $strg = 
         substr((" "x(($lenst/2)-(length($strg)/2))).$strg.(" 
"x$lenst),0,$lenst);
    } else {
       $strg = substr($strg.(" "x$lenst),0,$lenst);
!   } 
    return ($strg);
  }
  
  sub fmtdec {
    # format a decimal
    # $fmt is [$][,]n[m]
    my ($env,$numb,$fmt)address@hidden;
    my $curr = substr($fmt,0,1);
    if ($curr eq "\$") {
      $fmt = substr($fmt,1,length($fmt)-1);
    };
    my $comma = substr($fmt,0,1);
    if ($comma eq ",") {
      $fmt = substr($fmt,1,length($fmt)-1);
    };
    my $right;
    my $left = substr($fmt,0,1);
--- 83,157 ----
       $strg = substr((" "x$lenst).$strg,0-$lenst,$lenst);
    } elsif  ($align eq "C" ) {
!      $strg =
         substr((" "x(($lenst/2)-(length($strg)/2))).$strg.(" 
"x$lenst),0,$lenst);
    } else {
       $strg = substr($strg.(" "x$lenst),0,$lenst);
!   }
    return ($strg);
  }
  
+ =item fmtdec
+ 
+   $str = &fmtdec($env, $number, $format)
+ 
+ Returns a pretty-printed version of C<$number>.
+ 
+ C<$format> specifies how to print the number. It is of the form
+ 
+   [$][,]n[m]
+ 
+ where I<n> and I<m> are digits, specifying the number of digits to use
+ before and after the decimal, respectively. Thus,
+ 
+   &fmtdec(undef, 123.456, "42")
+ 
+ will return
+ 
+   " 123.45"
+ 
+ If I<n> is smaller than the size of the integer part, only the last
+ I<n> digits will be returned. If I<m> is greater than the number of
+ digits after the decimal in C<$number>, the result will be
+ right-padded with zeros.
+ 
+ If C<$format> has a leading dollar sign, the number is assumed to be a
+ monetary amount. C<$str> will have a dollar sign prepended to the
+ value.
+ 
+ If C<$format> has a comma after the optional dollar sign, the integer
+ part will be split into three-digit groups separated by commas.
+ 
+ =cut
+ #'
+ # FIXME - This is all terribly provincial, not at all
+ # internationalized. I'm pretty sure there's already something out
+ # there that'll figure out the current locale, look up the local
+ # currency symbol (and whether it goes on the left or right), figure
+ # out how numbers are grouped (commas, periods, or what? And how many
+ # digits per group?), and will print the whole thing prettily.
+ # But I can't find it just now. Maybe POSIX::setlocale() or
+ # perllocale(1) might help.
+ # FIXME - Bug:
+ #     fmtdec(undef, 12345.6, ',82') prints "     345.60"
+ #     fmtdec(undef, 12345.6, '$,82') prints ".60"
  sub fmtdec {
    # format a decimal
    # $fmt is [$][,]n[m]
    my ($env,$numb,$fmt)address@hidden;
+ 
+   # FIXME - Use $fmt =~ /^(\$)?(,)?(\d)(\d)?$/ instead of this mess of
+   # substr()s.
+ 
+   # See if there's a leading dollar sign.
    my $curr = substr($fmt,0,1);
    if ($curr eq "\$") {
      $fmt = substr($fmt,1,length($fmt)-1);
    };
+   # See if there's a leading comma
    my $comma = substr($fmt,0,1);
    if ($comma eq ",") {
      $fmt = substr($fmt,1,length($fmt)-1);
    };
+   # See whether one number was given, or two.
    my $right;
    my $left = substr($fmt,0,1);
***************
*** 67,76 ****
      $right = substr($fmt,1,1);
    }
    my $fnumb = "";
    my $tempint = "";
    my $tempdec = "";
    if (index($numb,".") == 0 ){
       $tempint = 0;
!      $tempdec = substr($numb,1,length($numb)-1); 
    } else {
       if (index($numb,".") > 0) {
--- 161,175 ----
      $right = substr($fmt,1,1);
    }
+   # See if $numb is a floating-point number.
    my $fnumb = "";
    my $tempint = "";
    my $tempdec = "";
+   # FIXME - Use
+   #   $numb =~ /(\d+)\.(\d+)/;
+   #   $tempint = $1 + 0;
+   #   $tempdec = $2;
    if (index($numb,".") == 0 ){
       $tempint = 0;
!      $tempdec = substr($numb,1,length($numb)-1);
    } else {
       if (index($numb,".") > 0) {
***************
*** 82,85 ****
--- 181,185 ----
         $tempdec = 0;
       }
+      # If a comma was specified, then comma-separate the integer part
       if ($comma eq ",") {
          while (length($tempdec) > 3) {
***************
*** 88,95 ****
        }
        $fnumb = substr($tempint,-3,3).$fnumb;
!      } else { 
!         $fnumb = $tempint; 
!      } 
    }
    if ($curr eq "\$") {
       $fnumb = fmtstr($env,$curr.$fnumb,"R".$left+1);
--- 188,197 ----
        }
        $fnumb = substr($tempint,-3,3).$fnumb;
!      } else {
!         $fnumb = $tempint;
!      }
    }
+   # If a dollar sign was specified, prepend a dollar sign and
+   # right-justify the number
    if ($curr eq "\$") {
       $fnumb = fmtstr($env,$curr.$fnumb,"R".$left+1);
***************
*** 100,104 ****
          $fnumb = fmtstr($env,$fnumb,"R".$left);
       }
!   }   
    if ($right > 0) {
       $tempdec = $tempdec.("0"x$right);
--- 202,207 ----
          $fnumb = fmtstr($env,$fnumb,"R".$left);
       }
!   }
!   # Right-pad the decimal part to the given number of digits.
    if ($right > 0) {
       $tempdec = $tempdec.("0"x$right);
***************
*** 106,111 ****
       $fnumb = $fnumb.".".$tempdec;
    }
!   return ($fnumb);
  }
  
  END { }       # module clean-up code here (global destructor)
--- 209,229 ----
       $fnumb = $fnumb.".".$tempdec;
    }
!   return ($fnumb);    # FIXME - Shouldn't return a list.
  }
  
  END { }       # module clean-up code here (global destructor)
+ 
+ 1;
+ __END__
+ 
+ =back
+ 
+ =head1 AUTHOR
+ 
+ Koha Developement team <address@hidden>
+ 
+ =head1 SEE ALSO
+ 
+ L<perl>.
+ 
+ =cut