-------------------------------------------------------------------------------
help for vgettoken                                                  Bill Rising
-------------------------------------------------------------------------------

Pull the First Token from Each Observation of a Variable

        vgettoken result_varname [rest_varname] : source_varname [if exp] [in
              range] , [parse(delimiters) nospace replaceresult replacerest
              nodelimiters

Description

vgettoken does for variables what gettoken does for macros: it pulls a token
from each observation of source_varlist, and stores the result in
result_variable.  If the optional rest_variable is specified, the remainder
(possibly minus the intervening delimiter) is stored in the rest_variable.

Options

parse(delimiters) gives the list of delimiters which are used to separate
    tokens.  If omitted, the only delimiter is whitespace (one or more spaces).
    There is no need to specify space a delimiter, though explicitly specifying
    it will not cause problems.

nospace is used to prevent spaces from being used as delimiters.

nodelimiters is used to prevent delimiters from being stored as tokens.  Note
    that just as with gettoken, spaces are never kept as tokens.

replacereslt allows the result_variable to be overwritten.

replacerest allows the rest_variable to be overwritten.

Example(s)

        . vgettoken foo : bar
            Will take the first word (space delimited!) from each observation
            in bar and put it in the corresponding observation of foo, leaving
            bar unchanged.

        . vgettoken foo rest : bar
            Will take the first word from each observation in bar and put it in
            the corresponding observation of foo, leaving bar unchanged, and
            putting the remaining words into rest.

        . vgettoken foo bar : bar
            Will take the first word from each observation in bar and put it in
            the corresponding observation of foo, and replace bar with the
            remaining words.

        . vgettoken foo : bar, parse(":") nospace
            Will take everything up to the first colon (:) from each
            observation in bar and put it in the corresponding observation of
            foo, leaving bar unchanged.  If the first character of an
            observation of bar is itself a colon, the colon will be placed in
            the corresponding observation of foo.

        . vgettoken foo rest : bar, parse(":") nospace
            Will take everything up to the first colon (:) from each
            observation in bar and put it in the corresponding observation of
            foo, leaving bar unchanged.  If the first character of an
            observation of bar is itself a colon, the colon will be placed in
            the corresponding observation of foo.  The observations in rest
            will contain everything left over, so concatinating foo and rest
            will reconstruct bar.

        . vgettoken foo : bar, parse(":") nospace nodelimiters
            Will take everything up to the first colon (:) from each
            observation in bar and put it in the corresponding observation of
            foo, leaving bar unchanged.  If the first character of an
            observation of bar is itself a colon, an empty observation will be
            placed in the corresponding observation of foo.

        . vgettoken foo rest : bar, parse(":") nospace nodelimiters
            Will take everything up to the first colon (:) from each
            observation in bar and put it in the corresponding observation of
            foo, leaving bar unchanged.  If the first character of an
            observation of bar is itself a colon, the corresponding observation
            of foo will be empty.  The observations in rest will contain
            everything left over, except any leading delimiters (just as would
            happen if spaces were used as the delimiters).

        . vgettoken foo : bar, parse(":|!")
            Will take everything up to either the first space, colon (:),
            vertical bar (|), or exclamation point (!) from each observation in
            bar and put it in the corresponding observation of foo, leaving bar
            unchanged.  If the first character of an observation of bar is
            itself a delimiter, the delimiter will be placed in the
            corresponding observation of foo unless the delimiter is a space
            (or spaces), in which case the observation in foo will be empty.

Notes

While this could possibly be useful for splitting up variables by hand when
working with nasty text files, it will probably be more useful to use vtokenize
to split up the source_variable into all its tokens.

Also see

gettoken, tokenize, vtokenize


Author
Bill Rising 
email: brising@louisville.edu 
web: http://www.louisville.edu/~wrrisi01

snailmail:
Department of Bioinformatics and Biostatistics
University of Louisville
Louisville, KY  40292

Last Updated: December 9, 2003 @ 22:28:15