{smcl}
{* 13apr2003}{...}
{hline}
help for {hi:vallist}{right:[P.Joly]}
{hline}

{title:List distinct values of a variable}

{p 8 25}
{cmd:vallist}
{it:varname}
[{cmd:if} {it:exp}]
[{cmd:in} {it:range}]
[{cmd:,}
      {cmd:sort}
      {cmd:freq}
      {cmdab:rev:erse}
      {cmdab:miss:ing}
      {cmdab:nol:abels}
      {cmdab:q:uoted}
      {cmdab:m:ax(}{it:#}{cmd:)}
      {cmdab:w:ords}
      {cmdab:f:ormat(%}{it:fmt}{cmd:)}
      {cmdab:s:ep(}{it:string}{cmd:)}
      {cmdab:not:rim}
      {cmd:local(}{it:macname}{cmd:)}
]


{title:Description}

{p}
{cmd:vallist} puts a list of the distinct values of {it:varname},
which may be numeric or string, into returned macro {cmd:r(list)}
and displays that list.
Values are listed according to the order in which they appear in
the data unless option {cmd:sort} or {cmd:freq} is specified.
Missing values are ignored unless {cmd:missing} is specified.

{p}
{cmd:vallist} may be used interactively, but is most likely to be
useful to programmers dealing with categorical or counted data.


{title:Remarks}

{p 0 3}
{hi:1.} Earlier versions of {cmd:vallist} produced a sorted list.
Starting with version 3.0, the list may be sorted as an option.

{p 0 3}
{hi:2.} Numerical variables containing non-integer values are displayed
using {it:varname}'s display format which may be overridden by
option {cmd:format()}.
The output format is therefore similar (if not identical) to the
output of the {help list} command.
Programmers who do not want to allow the listing of fractional
values are advised to use the {cmd:levels} command instead,
considered safer for this very reason.


{title:Options}

{p 0 4}
{cmd:sort} requests that the list be sorted alphanumerically.
Variables with value labels are sorted according to their
numerical value.

{p 0 4}
{cmd:freq} requests that the list be sorted in descending order of
frequency.  (Ties are broken up arbitrarily.)

{p 0 4}
{cmd:reverse} causes {cmd:vallist} to begin selecting distinct values
starting from the bottom (last observation) of the data as opposed
to the top (first observation).
If specified with {cmd:sort} or {cmd:freq} it produces the list of
distinct values in reverse alphanumerical order or reverse
(ascending) order of frequency, respectively.

{p 0 4}
{cmd:missing} specifies that missing values should also be listed.
Missing (i.e. empty) values of string variables are specified as
{cmd:"missing"}.
Note that this description may be truncated with the {cmd:max()}
option.

{p 0 4}
{cmd:nolabels} suppresses the use of labels for numeric variables
with value labels.

{p 0 4}
{cmd:quoted} specifies that values should be placed in {cmd:`" "'}.
This may be useful for string values or value labels containing
embedded spaces.

{p 0 4}
{cmd:max(}{it:#}{cmd:)} specifies that at most the first {it:#}
characters of text (string values or value labels) should be used for
each value.
For example, {cmd:max(32)} may be needed to cut down text to elements
acceptable in Stata 7 as matrix row or column names.

{p 0 4}
{cmd:words} specifies that text should be truncated to the first whole
`word', that is, at just before the first space after a non-space
character.
For example, a string value of {cmd:"foo bar"} would be represented by
{cmd:"foo"}.

{p 0 4}
{cmd:format(%}{it:fmt}{cmd:)} specifies a {help format} for use.
This is likely to be most useful with non-integer numeric values.
A string format should be specified for string values or numeric
values with value labels.

{p 0 4}
{cmd:sep(}{it:string}{cmd:)} specifies a separator other than a space,
which is the default.

{p 0 4}
{cmd:notrim} suppresses trimming of leading and trailing spaces from
string values or value labels.

{p 0 4}
{cmd:local(}{it:macname}{cmd:)} puts the list into local macro
{it:macname}.

{p 0 4}
The sequence of operations is {cmd:max()}, {cmd:words},
{cmd:format()}, {cmd:sep()}.


{title:Saved results}

{p 8 12}
{cmd:r(list)} contains the list of distinct values.


{title:Examples}

{p 4 8}{inp:. sysuse auto}{p_end}
{p 4 8}{inp:. vallist rep78}{p_end}
{p 4 8}{inp:. vallist rep78, sort}{p_end}
{p 4 8}{inp:. vallist gear_ratio, reverse}{p_end}
{p 4 8}{inp:. vallist mpg if foreign, sep(,) sort}{p_end}
{p 4 8}{inp:. vallist foreign, nolabels local(vals)}


{title:Author}

Patrick Joly, Industry Canada
pat.joly@utoronto.ca


{title:Acknowledgements}

{p}
The original author was Nicholas J. Cox. With his full permission
{cmd:vallist} is now maintained by the current author.
Fred Wolfe suggested that missing values be listable and raised the
problem of embedded spaces.


{title:Also see}

{p 0 19}
On-line:  help for
      {help tabulate},
      {help listutil},
      {help levels} (if installed)
{p_end}