;-------------------------------------------------------------
;+
; NAME:
;       GETWRD
; PURPOSE:
;       Return the n'th word from a text string.
; CATEGORY:
; CALLING SEQUENCE:
;       wrd = getwrd(txt, n, [m])
; INPUTS:
;       txt = text string to extract from.         in
;       n = word number to get (first = 0 = def).  in
;       m = optional last word number to get.      in
; KEYWORD PARAMETERS:
;       Keywords:
;         LOCATION = l.  Return word n string location.
;         DELIMITER = d. Set word delimiter (def = space).
;         /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.
;         /NOTRIM suppresses whitespace trimming on ends.

; OUTPUTS:
;       wrd = returned word or words.              out
; COMMON BLOCKS:
; NOTES:
;       Note: 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.
; MODIFICATION 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.
;       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.
;-
;-------------------------------------------------------------

        FUNCTION GETWRD, TXTSTR, NTH, MTH, help=hlp, location=ll,$
           delimiter=delim, notrim=notrim, last=last

        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,'   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).'
          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,'Note: 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.
        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.
        X = BYTE(TXTSTR) 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.

        NWDS = TOTAL(Y)                                 ; Number of words.
        LOC = Z                                         ; Word start locations.
        LEN = Z2 - Z - 1                                ; Word lengths.

        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(txtstr,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(TXTSTR,ll,LOC(MTH)-LOC(NTH)+LEN(MTH))
        endif else begin
          RETURN, strtrim(STRMID(TXTSTR,ll,LOC(MTH)-LOC(NTH)+LEN(MTH)), 2)
        endelse

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

        END