; $Id: strsci.pro,v 1.1 1998/10/09 19:53:32 mgs Exp $
;-------------------------------------------------------------
;+
; NAME:
;        STRSCI (function)
;
; PURPOSE:                                                 
;        Given a number, returns a string of that          B
;        number in scientific notation format ( e.g. A x 10  )
;
; CATEGORY:
;        String Utilities
;
; CALLING SEQUENCE:
;        Result = STRSCI( DATA [,keywords] )
;
; INPUTS:
;        DATA      -> A floating point or integer number to be
;                     converted into a power of 10.
;
; KEYWORD PARAMETERS:
;        FORMAT    -> The format specification used in the string
;                     conversion for the coefficient part (i.e. the
;                     "A" of "A x 10^B").  Default is '(f12.2)'.  
;
;        /POT_ONLY -> Will return only the "power of 10" part of the
;                     string (i.e. the "10^B").  Default is to return
;                     the entire string (e.g. "A x 10^B" )
;
;        /MANTISSA_ONLY -> return only mantissa of the string
;
;        /SHORT -> return 10^0 as '1' and 10^1 as '10'
;
;        /TRIM -> don't insert blanks 
;
; OUTPUTS:
;        None
;
; SUBROUTINES:
;        None
;
; REQUIREMENTS:
;        None
;
; NOTES:
;        Need a better symbol than the 'x' for the multiplier...
;
; EXAMPLE:
;        Result = STRSCI( 2000000, format='(i1)' )
;        print, result                
;        ;                                                     6
;        ;     prints 2 x 10!u6!n, which gets plotted as 2 x 10 
;        
;
; MODIFICATION HISTORY:
;        bmy, 28 May 1998: VERSION 1.00            B
;           - now returns string of the form A x 10
;        mgs, 29 May 1998:
;           - bug fix: now allows negative numbers
;           - keyword MANTISSA_ONLY added
;           - default format changed to f12.2
;        bmy, 02 Jun 1998:
;           - renamed to STRSCI ("STRing SCIentific notation"),
;        mgs, 03 Jun 1998:
;           - added TRIM keyword
;        mgs, 22 Sep 1998:
;           - added SHORT keyword
;           - modified handling of TRIM keyword
;        mgs, 24 Sep 1998:
;           - bug fix with SHORT flag
;
;-
; Copyright (C) 1998, Bob Yantosca, Harvard University
; This software is provided as is without any warranty
; whatsoever. It may be freely used, copied or distributed
; for non-commercial purposes. This copyright notice must be
; kept with any copy of this software. If this software shall
; be used commercially or sold as part of a larger package,
; please contact the author to arrange payment.
; Bugs and comments should be directed to bmy@io.harvard.edu
; with subject "IDL routine strsci"
;-------------------------------------------------------------


function StrSci, Data, Format=Format, POT_Only=POT_Only, $
             MANTISSA_ONLY=MANTISSA_ONLY,SHORT=SHORT,TRIM=TRIM

   ; Error checking
   on_error, 2

   ; Make sure DATA is passed
   if ( n_elements( Data ) eq 0 ) then begin
 ;    print, 'DATA must be passed to EXP_STR!!'
      return, ''
   endif

   ; Default value for FORMAT 
   if ( not keyword_set( Format   ) ) then Format   = '(f12.2)'
   POT_Only = keyword_set( POT_Only )
   MANTISSA_Only = keyword_set( MANTISSA_Only )

   ; Take the common log of Data
   Log10Data  = alog10( abs(Data) * 1d0 )
   sign = (data lt 0.)

   ; Compute the Mantissa (frac part) and Characteristic (int part)
   Characteristic = fix( Log10Data )
   Mantissa       = Log10Data - Characteristic  
   
   ; String for the coefficient part, 
   ; The coefficient is just antilog of the Mantissa
   A = strtrim( string( 10d0^Mantissa, Format=Format ), 2 )
   if (sign) then A = '-' + A

   ; String for the power of 10 part
   B = '10!u' + strtrim( string( Characteristic ), 2 ) + '!n'
   if (keyword_set(SHORT)) then begin
       if (Characteristic eq 0) then B = '1'
       if (Characteristic eq 1) then B = '10'
   endif

   ; composite string
   result = A + ' x ' + B
   if (keyword_set(SHORT) AND B eq '1') then result = A
   if ( POT_Only ) then result = B
   if (MANTISSA_ONLY ) then result = A

   ; eliminate blanks if TRIM keyword is set
   if (keyword_set(TRIM)) then result = strcompress(result,/remove_all)

   return, result

end