source: trunk/SRC/ToBeReviewed/STRING/getwrd.pro @ 325

;+
;
; @file_comments
; Return the n'th word from a text string.
;
; @categories
; String
;
; @param TXTSTR {in}{required} {type=string or array of strings}
; text string to extract from.
; The first element is used if txt is an array.
;
; @param NTH {in}{required} {type=integer} {default=0}
; word number to get (first = 0 = def)
;
; @param MTH {in}{optional} {type=integer}
; optional last word number to get.
;
; @keyword LOCATION
; = l.  Return word n string location.
;
; @keyword DELIMITER
; = d. Set word delimiter (def = space & tab).
;
; @keyword LAST
; means n is offset from last word.  So n=0 gives
; last word, n=-1 gives next to last, ...
; If n=-2 and m=0 then last 3 words are returned.
;
; @keyword NOTRIM
; suppresses whitespace trimming on ends.
;
; @keyword NWORDS
; = n. Returns number of words in string.
;
; @returns
; wrd = returned word or words.
;
; @uses
; getwrd_com
;
; @restrictions
; If a NULL string is given (txt="") then the last string
; given is used.  This saves finding the words again.
; If m > n wrd will be a string of words from word n to
; word m.  If no m is given wrd will be a single word.
; n<0 returns text starting at word abs(n) to string end
; If n is out of range then a null string is returned.
; See also nwrds.
;
; @history
;       Ray Sterner,  6 Jan, 1985.
;       R. Sterner, Fall 1989 --- converted to SUN.
;       R. Sterner, Jan 1990 --- added delimiter.
;       R. Sterner, 18 Mar, 1990 --- added /LAST.
;       R. Sterner, 31 Jan, 1991 --- added /NOTRIM.
;       R. Sterner, 20 May, 1991 --- Added common and NULL string.
;       R. Sterner, 13 Dec, 1992 --- Made tabs equivalent to spaces.
;       R. Sterner,  4 Jan, 1993 --- Added NWORDS keyword.
;       R. Sterner, 2001 Jan 15 --- Fixed to use first element if not a scalar.
;       Johns Hopkins University Applied Physics Laboratory.
;
; Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
; This software may be used, copied, or redistributed as long as it is not
; sold and this copyright notice is reproduced on each copy made.  This
; routine is provided as is without any express or implied warranties
; whatsoever.  Other limitations apply as described in the file disclaimer.txt.
;
; @version
; $Id$
;
;-
        FUNCTION getwrd, txtstr, nth, mth, HELP=hlp, LOCATION=ll,$
           DELIMITER=delim, NOTRIM=notrim, LAST=last, NWORDS=nwords

        common getwrd_com, txtstr0, nwds, loc, len

        if (n_params(0) lt 1) or keyword_set(hlp) then begin
          print," Return the n'th word from a text string."
          print,' wrd = getwrd(txt, n, [m])'
          print,'   txt = text string to extract from.         in'
          print,'     The first element is used if txt is an array.'
          print,'   n = word number to get (first = 0 = def).  in'
          print,'   m = optional last word number to get.      in'
          print,'   wrd = returned word or words.              out'
          print,' Keywords:'
          print,'   LOCATION = l.  Return word n string location.'
          print,'   DELIMITER = d. Set word delimiter (def = space & tab).'
          print,'   /LAST means n is offset from last word.  So n=0 gives'
          print,'     last word, n=-1 gives next to last, ...'
          print,'     If n=-2 and m=0 then last 3 words are returned.'
          print,'   /NOTRIM suppresses whitespace trimming on ends.'
          print,'   NWORDS=n.  Returns number of words in string.'
          print,'Note: If a NULL string is given (txt="") then the last string'
          print,'      given is used.  This saves finding the words again.'
          print,'      If m > n wrd will be a string of words from word n to'
          print,'      word m.  If no m is given wrd will be a single word.'
          print,'      n<0 returns text starting at word abs(n) to string end'
          print,'      If n is out of range then a null string is returned.'
          print,'      See also nwrds.'
          return, -1
        endif

        if n_params(0) lt 2 then nth = 0                ; Def is first word.
        IF N_PARAMS(0) LT 3 THEN MTH = NTH              ; Def is one word.

        if strlen(txtstr[0]) gt 0 then begin
          ddel = ' '                                    ; Def del is a space.
          if n_elements(delim) ne 0 then ddel = delim   ; Use given delimiter.
          TST = (byte(ddel))[0]                         ; Del to byte value.
          tb = byte(txtstr[0])                          ; String to bytes.
          if ddel eq ' ' then begin                     ; Check for tabs?
            w = where(tb eq 9B, cnt)                    ; Yes.
            if cnt gt 0 then tb[w] = 32B                ; Convert any to space.
          endif
          X = tb NE TST                                 ; Non-delchar (=words).
          X = [0,X,0]                                   ; 0s at ends.

          Y = (X-SHIFT(X,1)) EQ 1                       ; Diff=1: word start.
          Z = WHERE(SHIFT(Y,-1) EQ 1)                   ; Word start locations.
          Y2 = (X-SHIFT(X,-1)) EQ 1                     ; Diff=1: word end.
          Z2 = WHERE(SHIFT(Y2,1) EQ 1)                  ; Word end locations.

          txtstr0 = txtstr[0]                           ; Move string to common.
          NWDS = long(TOTAL(Y))                         ; Number of words.
          LOC = Z                                       ; Word start locations.
          LEN = Z2 - Z - 1                              ; Word lengths.
        endif else begin
          if n_elements(nwds) eq 0 then begin           ; Check if first call.
            print,' Error in getwrd: must give a '+$
              'non-NULL string on the first call.'
            return, -1                                  ; -1 = error flag.
          endif
        endelse

        nwords = nwds                                   ; Set nwords

        if keyword_set(last) then begin                 ; Offset from last.
          lst = nwds - 1
          in = lst + nth                                ; Nth word.
          im = lst + mth                                ; Mth word.
          if (in lt 0) and (im lt 0) then return, ''    ; Out of range.
          in = in > 0                                   ; Smaller of in and im
          im = im > 0                                   ;  to zero.
          if (in gt lst) and (im gt lst) then return,'' ; Out of range.
          in = in < lst                                 ; Larger of in and im
          im = im < lst                                 ;  to be last.
          ll = loc[in]                                  ; Nth word start.
          return, strtrim(strmid(txtstr0,ll,loc[im]-loc[in]+len[im]), 2)
        endif

        N = ABS(NTH)                                    ; Allow nth<0.
        IF N GT NWDS-1 THEN RETURN,''                   ; out of range, null.
        ll = loc[n]                                     ; N'th word position.
        IF NTH LT 0 THEN GOTO, NEG                      ; Handle nth<0.
        IF MTH GT NWDS-1 THEN MTH = NWDS-1              ; Words to end.

        if keyword_set(notrim) then begin
          RETURN, STRMID(TXTSTR0,ll,LOC[MTH]-LOC[NTH]+LEN[MTH])
        endif else begin
          RETURN, strtrim(STRMID(TXTSTR0,ll,LOC[MTH]-LOC[NTH]+LEN[MTH]), 2)
        endelse

NEG:    if keyword_set(notrim) then begin
          RETURN, STRMID(TXTSTR0,ll,9999)
        endif else begin
          RETURN, strtrim(STRMID(TXTSTR0,ll,9999), 2)
        endelse

        END