; docformat = 'rst'
;
; NAME: 
;    toSciNote
; PURPOSE:
;    Convert a value to its scientific notation with LaTeX syntax
;
;+
; :Description:
;    Convert a value to its scientific notation with LaTeX syntax
;
; :Categories:
;    Math
;    
; :Params:
;    value: in, required, type=float/double
;      Array of values to be converted
;    sigma: in, optional, type=float/double
;      Standard deviation associated with the values
;    sigmAlt: in, optional, type=float/double
;      Second standard deviation associated with the values, if set,
;      sigma is the lower deviation and sigmAlt the upper.
;
; :Keywords:
;    digit: in, optional, type=integer, default=2
;      The number of digit to display
;    power: in, optional, type=integer
;      If set, use this common exponent value
;    latex: in, optional, type=boolean, default=1
;      If set, report the scientific notation in LaTeX format
;    idl: in, optional, type=boolean, default=0
;      If set, report the scientific notation in IDL format
;
; :Examples:
;    A few values convert to scientific LaTeX notation::
;      IDL> print, toSciNote( 1.234e5 )
;      IDL> print, toSciNote( 1.234e5, 5e4 )
;      IDL> print, toSciNote( 1.234e5, 5e4, 2e4 )
;      IDL> print, toSciNote( 1.234e5, 5e4, 2e4, digit=1 )
;      IDL> print, toSciNote( 1.234e5, 5e4, 2e4, power=3 )
;
; :Uses:
;
; :Author:
;    B.Carry (OCA)
;
; :History:
;    Change History::
;      Written in Apr 2017, B. Carry (OCA)
;      2017 May - B. Carry (OCA) - Added latex/IDL keywords to choose format
;-
function toSciNote, value, sigma, sigmAlt, digit=digit, power=power, latex=latex, idl=idl
  COMPILE_OPT hidden, idl2
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---    I -- Initialization And Input Verification              -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--I.1-- Syntax Validation  -------------------------------------------------------------------;
  if not keyword_set(value) then begin
    message, /ioError, 'Syntax: txt = toSciNote( value [, sigma, sigmAlt, digit=, power=] )'
  endif


 ;--I.2-- Single Value, One, or Two Uncertainties?  --------------------------------------------;
  version = 3
  if not keyword_set(sigmAlt) then version = 2
  if not keyword_set(sigma)   then begin
    sigma = 0.
    version = 1
  endif
  if not keyword_set(sigmAlt) then sigmAlt = sigma

  
 ;--I.3-- Default Number of Digits  ------------------------------------------------------------;
  if not keyword_set(digit) then digit=2
  
  
 ;--I.4-- Upper and Lower Limits  --------------------------------------------------------------;
  bot = value-sigma
  top = value+sigmAlt
  diffL = sigma   
  diffH = sigmAlt 
  

 ;--I.5-- IDL or LaTeX Format?  ----------------------------------------------------------------;
  fVec = [keyword_Set(idl), keyword_set(latex)]
  if total(fVec) eq 0 or total(fVec) eq 2 then mode=1 else begin
    if keyword_set(idl)   then mode=2
    if keyword_set(latex) then mode=1
  endelse
  
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
;---  TAG ---   II -- Finding Power of Ten for Output                    -----------------------;
;-----------------------------------------------------------------------------------------------;
;-----------------------------------------------------------------------------------------------;
 ;--II.1-- Convert Values to Strings  ----------------------------------------------------------;
  valStr = strTrim(string(value, format='(E9.1)'),2)
  valExp = round(float(strMid(valStr,4,3)))

  botStr = strTrim(string(bot, format='(E9.1)'),2)
  if bot lt 0 then botExp=round(float(strMid(botStr,5,3))) else botExp = round(float(strMid(botStr,4,3)))
  if bot eq 0 then botExp=valExp

  topStr = strTrim(string(top, format='(E9.1)'),2)
  topExp = round(float(strMid(topStr,4,3)))
  

;  print, bot, value, top
;  print, botExp, valExp, topExp


 ;--II.2-- Set Power of Ten Exponent  ----------------------------------------------------------;
  if n_elements(power) then refExp=power else refExp = min( [botExp, valExp, topExp] )


 ;--II.3-- Compute Relative Variations  --------------------------------------------------------;
  lOut = diffL * 10.^(-refExp)
  vOut = value * 10.^(-refExp)
  hOut = diffH * 10.^(-refExp)


 ;--II.4-- Define String Formats  --------------------------------------------------------------;
  fmtVal = '(F15.'+strTrim(string(digit,format='(I)'),2)+')'
  fmtBot = '(F15.'+strTrim(string(digit,format='(I)'),2)+')'
  fmtTop = '(F15.'+strTrim(string(digit,format='(I)'),2)+')'
  

 ;--II.5-- Build Scientific Notation for LaTex  ------------------------------------------------;
  case mode of
    1: begin

     ;--II.5.1-- Powers of Ten
      if refExp eq 0 then pow10='' else pow10=' \times 10^{'+strTrim(string( refExp, format='(I)'),2)+'}'

     ;--II.5.2-- Build the Line
      case version of 
        1: line = strTrim(string( vOut, format=fmtVal),2) + pow10
        2: begin
           if strCmp(pow10,'') then begin
             line = strTrim(string( vOut, format=fmtVal),2)+' \pm '+strTrim(string( lOut, format=fmtBot),2)
           endif else begin
             line = '('+strTrim(string( vOut, format=fmtVal),2)+$
                    ' \pm '+strTrim(string( lOut, format=fmtBot),2)+')' + pow10
           endelse
        end
        3: line = strTrim(string( vOut, format=fmtVal),2)+$
                  '_{-'+strTrim(string( lOut, format=fmtBot),2)+'}'+$
                  '^{+'+strTrim(string( hOut, format=fmtTop),2)+'}'+ pow10
      endcase
    end


 ;--II.6-- Build Scientific Notation for IDL  --------------------------------------------------;
    2: begin

     ;--II.6.1-- Powers of Ten
      if refExp eq 0 then pow10='' else pow10=' x 10!U'+strTrim(string( refExp, format='(I)'),2)+'!N'

     ;--II.6.2-- Build the Line
      case version of 
        1: line = strTrim(string( vOut, format=fmtVal),2) + pow10
        2: line = '('+strTrim(string( vOut, format=fmtVal),2)+$
                  ' +/- '+strTrim(string( lOut, format=fmtBot),2)+')' + pow10
        3: line = strTrim(string( vOut, format=fmtVal),2)+$
                  '!D-'+strTrim(string( lOut, format=fmtBot),2)+'!N'+$
                  '!U+'+strTrim(string( hOut, format=fmtTop),2)+'!N'+ pow10
      endcase
    end
  endcase

  return, line

end