; $Id$
;-------------------------------------------------------------
;+
; NAME:
;        STRREPL (function)
;
; PURPOSE:
;        replace one (or more) character(s)/string(s) in a string
;
; CATEGORY:
;        string routines
;
; CALLING SEQUENCE:
;        Result = STRREPL(str, index, rchar)
;
; INPUTS:
;        STR -> the string to be changed
;
;        INDEX -> position of the character(s) to be replaced or a
;        string to be changed in STR.
;
;        RCHAR -> replacement character/string
;
; KEYWORD PARAMETERS: none
;
;
; OUTPUTS:
;        another string
;
; SUBROUTINES:
;
; REQUIREMENTS:
;
; NOTES:
;        Known shortcoming: if index is an array, it must contain all
;        valid elements (only the first entry is checked).
;
; EXAMPLE:
;        ; Convert one letter into upper case
;
;        abc = 'abcdefghijklmnopqrstuvwxyz'
;        print,strrepl(abc,strpos(abc,'m'),'M')
;
;        ; prints "abcdefghijklMnopqrstuvwxyz"
;
;
;        ; Use with strwhere function
;        a = 'abcabcabc'
;        print,strrepl(a,strwhere(a,'a'),'#')
;
;        ; prints  "#bc#bc#bc#bc#bc"
;
;       IDL> print, strrepl(a,'bc','!eeee!')
;       a!eeee!a!eeee!a!eeee!
;       IDL> print, strrepl(a,'b','0000')
;       a0000ca0000ca0000
;       IDL> print, strrepl(a,'toto','0000')
;       abcabcabc
;
; MODIFICATION HISTORY:
;        mgs, 02 Jun 1998: VERSION 1.00
;        sebastien Masson (smlod@ipsl.jussieu.fr)
;
;-
; Copyright (C) 1998, Martin Schultz, 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 mgs@io.harvard.edu
; with subject "IDL routine strrepl"
;-------------------------------------------------------------


function strrepl,str,agument1,rchar
;
  compile_opt idl2, strictarrsubs
;
   
   if (n_elements(str) eq 0) then return,''
   
                                ; convert strign and replace character to byte
   BStr = byte(str)
   new = byte(rchar)
   if size(agument1, /type) EQ 7 then begin
      old = byte(agument1)
      index = strpos(str, agument1)
      pos = index
      while strpos(str, agument1, pos+1) NE -1 do BEGIN
         pos = strpos(str, agument1, pos+1)
         index = [index, pos]
      ENDWHILE
; make sure index is in range
      if (index[0] lt 0 OR index[0] ge n_elements(BStr)) THEN return,Str
   ENDIF ELSE BEGIN
      index = agument1
      if (index[0] lt 0 OR index[0] ge n_elements(BStr)) then return,Str
      old = BStr[index[0]]
   ENDELSE
                                ; replace indexed characters in string
   nelenew = n_elements(new)
   neleold = n_elements(old)
   nindex = n_elements(index)
   if nelenew*neleold NE 1 then begin
      if index[0] EQ 0 then $
       BStr = [NEW,  BStr[index[0]+neleold: n_elements(BStr)-1] ] ELSE $
       BStr = [BStr[0:index[0]-1], NEW,  BStr[index[0]+neleold: n_elements(BStr)-1] ]
      if nindex EQ 1 then return,string(BStr)
      if nindex GT 2 then $
       for i = 1, nindex-2 do $
       BStr = [BStr[0:index[i]+i*(nelenew-neleold)-1], NEW $
               , BStr[index[i]+i*(nelenew-neleold)+neleold: n_elements(BStr)-1] ]
      BStr = [BStr[0:index[n_elements(index)-1]+(nindex-1)*(nelenew-neleold)-1], NEW]

   ENDIF ELSE BStr[index] = NEW
                                ; return result as string
   return,string(BStr)
   
end