;+
;
; @file_comments
; replace one (or more) character(s)/string(s) in a string
; --- OBSOLETE --- you should better use <pro>strsed</pro>
;
; @categories
; String
;
; @param STR {in}{required}
; the string to be changed
;
; @param ARG2 {in}{required}
; position of the character(s) to be replaced or a string to be changed in STR.
;
; @param RCHAR {in}{required}
; replacement character/string
;
; @returns
; another string
;
; @restrictions
; Known shortcoming: if index is an array, it must contain all
; valid elements (only the first entry is checked).
;
; @examples
;        ; 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
;
; @history
;        mgs, 02 Jun 1998: VERSION 1.00
; 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"
;
;        sebastien Masson (smlod\@ipsl.jussieu.fr)
;
; @version
; $Id$
;
;-
FUNCTION strrepl,str,arg2,rchar
;
  compile_opt idl2, strictarrsubs, obsolete
;

   if (n_elements(str) eq 0) then return,''

                                ; convert strign and replace character to byte
   BStr = byte(str)
   new = byte(rchar)
   if size(arg2, /type) EQ 7 then begin
      old = byte(arg2)
      index = strpos(str, arg2)
      pos = index
      while strpos(str, arg2, pos+1) NE -1 do BEGIN
         pos = strpos(str, arg2, 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 = arg2
      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