mf_tokens.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 28mar2005}{...}
{cmd:help mata tokens()}
{hline}
{* index tokens()}{...}
{* index parsing}{...}

{title:Title}

{p 4 4 2}
{bf:[M-5] tokens() -- Obtain tokens from string}


{title:Syntax}

{p 8 12 2}
{it:string rowvector}
{cmd:tokens(}{it:string scalar s}{cmd:)}

{p 8 12 2}
{it:string rowvector}
{cmd:tokens(}{it:string scalar s}{cmd:,}
{it:string scalar parsechars}{cmd:)}


{title:Description}

{p 4 4 2}
{cmd:tokens(}{it:s}{cmd:)} returns the contents of {it:s}, split into words.

{p 4 4 2}
{cmd:tokens(}{it:s}{cmd:,} {it:parsechars}{cmd:)}
returns the contents of {it:s} split into tokens based on {it:parsechars}.

{p 4 4 2}
{cmd:tokens(}{it:s}{cmd:)} 
is equivalent to {cmd:tokens(}{it:s}{cmd:, " ")}.


{title:Remarks}

{p 4 4 2}
{cmd:tokens()} is commonly used to split a string 
containing a sequence of variable names into a 
rowvector, each element of which contains a single variable name:

	{cmd:tokens("mpg weight displacement") = ("mpg", "weight", "displacement")}

{p 4 4 2}
Many of the Stata interface functions require that variable names be specified
in this form.  This is required, for instance, by 
{bf:{help mf_st_data:st_data()}} and  
{bf:{help mf_st_view:st_view()}}.

{p 4 4 2}
Say you have an ado-file that calls private Mata function 
{cmd:mysub()} to perform a task.  The varlist that is to be used 
is passed from the ado-file to the Mata function and was originally obtained
from the user:


	{hline 50} example.ado {hline 4}
	{cmd}program example
		syntax varlist [if] [in]
		marksample touse
		{txt}...{cmd}
		mata: mysub("`varlist'", "`touse'")
		{txt}...{cmd}
	end

	mata void mysub(string scalar varlist, string scalar touse)
	{c -(}
		{txt}...{cmd}
		st_view(V, ., tokens(varlist), touse)
		{txt}...{cmd}
	{c )-}{txt}
	{hline 50} example.ado {hline 4}

{p 4 4 2}
{bf:{help mf_st_view:st_view()}} requires that its third argument
be a rowvector of variable names.  Our
ado-file passed in a single string that had all the variable names, listed one
after the other, so we could not simply code

		{cmd:st_view(V, ., varlist, touse)}

{p 4 4 2}
Perhaps {cmd:varlist} contains "mpg weight displacement".  
{cmd:tokens()} converts {cmd:varlist} to the form {cmd:st_view()} requires,
namely the row vector ("mpg", "weight", "displacement").


{title:Conformability}

    {cmd:tokens(}{it:s}{cmd:,} {it:parsechars}{cmd:)}
		 {it:s}:  1 {it:x} 1
	{it:parsechars}:  1 {it:x} 1
	    {it:result}:  1 {it:x w}, {it:w} = number of words (tokens) in {it:s}.


{title:Diagnostics}

{p 4 4 2}
    If {it:s} contains "", {cmd:tokens()} returns J(1,0,"").

{p 4 4 2}
    If {it:s} contains double-quoted or compound-double-quoted material,
    the quotes are stripped and that material is returned as a single token.
    E.g., 

	{cmd:tokens(`"this "is an" example"') = ("this", "is an", "example")}

{p 4 4 2}
    If {it:s} contains quoted material and the quotes do not match, results 
    are as if the appropriate number of close quotes were added to the 
    end of {it:s}.  E.g, 

	{cmd:tokens(`"this "is an example"') = ("this", "is an example")}


{title:Source code}

{p 4 4 2}
Function is built-in.


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-5] tokens()}

{p 4 13 2}
Online:  help for 
{bf:{help m4_string:[M-4] string}}
{p_end}