;+
;
; @file_comments
; Retrieve portion of string up to token.
;
; @categories
; String
;
; @param STRING {in}{required}
; String to be split. Contains text after in, out token on output.
;
; @param TOKEN {in}{required}
; Token to use in splitting old.
;
; @keyword TRIM
; set to remove leading blanks from old before returning.
;
; @keyword HELP
; print useful message and exit.
;
; @returns
; new   -- portion of string up to token.              out
; old   -- portion of old after token.                 out, in
;
; @restrictions
; Input parameter old is modified.
; Token may be one or more characters.
; if token is not found, returns old and sets old to ''.
;
; @examples
;       If old is 'foo44 bar', then strtok( old, '44' ) would return
;       'foo', and upon return, old will be left with ' bar'.  If /TRIM
;       were set, old would be 'bar' on return.
;
;       If old='xyz', then new=strtok(old,'a') would return with
;       new='xyz' and old=''.
;
; @history
;       $Log: strtok.pro,v $
;       Revision 1.3  1996/06/14 20:00:27  mcraig
;       Updated Copyright info.
;
;       Revision 1.2  1996/05/09 00:22:17  mcraig
;       Added built in help.
;
;       Revision 1.1  1996/01/31 18:47:37  mcraig
;       Initial revision
;
; Thanks:
;       To D. Linder who wrote GETTOK, part of the goddard library,
;       upon which this is based.
;
; Release:
;       $Name: Rel_1_2 $
;
; Copyright:
;  Copyright (C) 1996 The Regents of the University of California, All
;  Rights Reserved.  Written by Matthew W. Craig.
;  See the file COPYRIGHT for restrictions on distributing this code.
;  This code comes with absolutely NO warranty; see DISCLAIMER for details.
;
; @version
; $Id$
;
;-
FUNCTION strtok, string, token, TRIM=trim, HELP=Help
;
  compile_opt idl2, strictarrsubs
;

; Back to the caller if error occurs.
    On_error, 2

    IF (n_params() NE 2) OR keyword_set(Help) THEN BEGIN
        offset = '   '
        print, offset+'Retrieve portion of string up to token.'
        print, offset+'new = strtok( old, token )'
        print, offset+'Inputs:'
        print, offset+offset+'old   -- String to be split.  Contains text after    in, out'
        print, offset+offset+'         token on output.'
        print, offset+offset+'token -- Token to use in splitting old.              in'
        print, offset+'Keywords:'
        print, offset+offset+'/TRIM -- set to remove leading blanks from old '
        print, offset+offset+'         before returning.'
        print, offset+offset+'/HELP -- print useful message and exit.'
        print, offset+'Outputs:'
        print, offset+offset+'new   -- portion of string up to token.              out'
        print, offset+offset+'old   -- portion of old after token.                 out, in'
        print, offset+'Side effects:'
        print, offset+offset+'Input parameter old is modified.'
        print, offset+'Notes:'
        print, offset+offset+'Token may be one or more characters.'
        print, offset+offset+"If token is not found, returns old and sets old to ''."
        print, offset+'Examples:'
        print, offset+offset+"If old is 'foo44 bar', then strtok( old, '44' ) would return'"
        print, offset+offset+"  'foo', and upon return, old will be left with ' bar'.  If /TRIM"
        print, offset+offset+"  were set, old would be 'bar' on return."
;'
        print, offset+offset+"If old='xyz', then new=strtok(old,'a') would return with"
        print, offset+offset+"  new='xyz' and old=''."
        return, -1
    ENDIF

    pos = strpos(string, token)

    IF (pos GE 0) THEN BEGIN
        front = strmid(string, 0, pos)
        string = strmid(string, pos + strlen(token), strlen(string))
        IF keyword_set(trim) THEN string = strtrim(string, 1)
        return, front
    ENDIF

    front = string
    string = ''
    return, front

END