help tknz                                                   also see:  tokenize
-------------------------------------------------------------------------------

Title

    tknz -- Tokenize string into consecutively numbered named macros


Syntax

        tknz varlist|["]string["] [,parse(pchars) stub(string) nochar]

    options                      Description
    -------------------------------------------------------------------------

      stub(stub)      stub to prefix numbered positional macros.

      parse(pchars)   parse character(s)

      nochar          drop non space parsing character


Description

    tknz tokenizes string into tokens, storing the results in the local
    macros stub1, stub2, etc. Tokens are determined based on the parsing
    characters pchars, which defaults to a space if not specified.

    The number of tokens created is returned in s(items).

        +---------+
    ----+ Options +----------------------------------------------------------

    stub(stub) specifies a stub for the macro names. This stub should be
        short enough for the complete names all to be legal. If stub is not
        included the default _1, _2 macro naming is used.

    parse(pchars) specifies the parsing characters.  If parse() is not
        specified, parse(" ") is assumed, and thus the string is split into
        words.

    nochar specifies that the non space parsing character not be included in
        the consecutively numbered macros. (Stata's tokenize includes the non
        space parsing character in the string of tokens and this conveniently
        allows them to be stripped out)

Examples

   . tknz `varlist', s(v)
   . tknz "one,two,three,four", s(v) p(,) nochar


Notes

    Subsequent processing for each item on the list can easily be achieved by
    using:

   forvalues i=1/`s(items)' {
       do something on `v`i'' // where v is the stub
       }

    tknz uses the undocumented macro assignment command c_local which allows
    local macros created by tknz to be used within the context of the
    program, dofile, or command line call to tknz. However, they are not
    available to a new instance created by a subsequent program, which can
    lead to unexpected results or errors.  For example, if you call tknz from
    the command line and then again in a subsequent program or dofile, the
    values you see from the command line by issuing macro dir are not those
    created by the subsequent program, but from the instance created by the
    previous command line call.  Understanding this can save a lot of grief!

Author

    David C. Elliott, Nova Scotia Department of Health, Halifax
    DCElliott@gmail.com


Acknowledgements

    Nicholas J. Cox created the original tknz for adding stubs to the
    numbered positional macros and provided a number of suggestions for
    improving the routine and help file.