{smcl}
{hline}
help for {cmd:sdecode} {right:(Roger Newson)}
{hline}


{title:Decode string variable into numeric using formats for unlabelled values}

{p 8 21 2}
{cmd:sdecode} {varname} {ifin} ,
 [ {cmdab:g:enerate}{cmd:(}{it:{help newvar}}{cmd:)} | {cmd:replace} ]
 [ {cmdab:maxl:ength}{cmd:(}{it:#}{cmd:)} {cmdab:fo:rmat}{cmd:(}{it:{help format:format_spec}}{cmd:)}
   {cmdab:labo:nly} {cmdab:m:issing}
   {cmdab:pr:efix}{cmd:(}{it:string}{cmd:)} {cmdab:su:ffix}{cmd:(}{it:string}{cmd:)} ]

{pstd}
where {it:format_spec} is either a format or a string variable name.


{title:Description}

{pstd}
{cmd:sdecode} ("super {helpb decode}") creates an output string variable with values from
the input numeric variable {varname}, using {help label:labels} if present and {help format:formats} otherwise.
The output string variable may either replace the input numeric variable or be generated
as a new variable named {it:{help newvar}}.
Unlike {helpb decode}, {cmd:sdecode} creates an output string
variable containing the values of the input variable as output by the {helpb tabulate} command
and other Stata output, instead of decoding all unlabelled input values to missing.
{cmd:sdecode} is especially useful if a numeric variable has value labels for some values
but not for others.


{title:Options}

{p 4 8 2}
Either {cmd:generate()} or {cmd:replace} must be specified, but both options may not be specified
at the same time.

{p 4 8 2}{cmd:generate(}{it:{help newvar}}{cmd:)} specifies the name of a new output string variable to be
created.

{p 4 8 2}{cmd:replace} specifies that the output string variable will replace the input
numeric variable, and have the same name, the same {help order:position in the data set},
and the same {help label:variable label} and {help char:characteristics} if present.

{p 4 8 2}{cmd:maxlength(}{it:#}{cmd:)} is optional.
It specifies how many characters of the {help label:value label} to retain.
{it:#} must be an integer between 1 and the {help limits:maximum string variable length},
which is stored in the {help creturn:system parameter} {hi:c(maxstrvarlen)}.
If unset, then {cmd:maxlength()} is set to the {help limits:maximum string variable length}.

{p 4 8 2}{cmd:format(}{it:{help format:format_spec}}{cmd:)} is optional.
It specifies the {help format:format} (or formats) used for decoding unlabelled values of the input numeric variable.
It may be either a {help format} (to be used for all unlabelled values), or the name of a string format variable
(in which case each observation with an unlabelled value is decoded using the format stored in the
string format variable for that observation).
If {cmd:format()} is not specified, then {cmd:sdecode}
uses the format associated with the input numeric variable.

{p 4 8 2}{cmd:labonly} is optional.
It specifies that only labelled values for the input numeric variable
will be decoded to nonmissing string values in the output string variable, and that unlabelled values
will be decoded to a missing string value, as with {helpb decode}.
If {cmd:labonly} is not specified,
then all nonmissing values of the input string variable will be decoded to nonmissing string values, except
for values in observations excluded by the {helpb if} and {helpb in} qualifiers, which are decoded to
a missing string value.

{p 4 8 2}{cmd:missing} is optional.
It specifies that {help missing:missing values} in the input numeric variable
will be decoded (using formats) to non-missing formatted string values (such as {hi:"."}).
If {cmd:missing} is absent, then missing values in the input numeric variable are decoded
to missing string values.

{p 4 8 2}{cmd:prefix(}{it:string}{cmd:)} is optional.
It specifies a prefix string, to be added to the left of the decoded string variable.

{p 4 8 2}{cmd:suffix(}{it:string}{cmd:)} is optional.
It specifies a suffix string, to be added to the right of the decoded string variable.


{title:Remarks}

{pstd}
{cmd:sdecode} is a separate package from {helpb sencode} ("super {helpb encode}"),
which is also downloadable from {help ssc:SSC}.
However, the two packages both have the alternative
{cmd:generate()} and {cmd:replace} options.
They are complementary to the {helpb destring}
command and the {helpb tostring} command,
which are part of official Stata.
{helpb tostring} and {helpb destring}
convert numeric values to and from their formatted string values, respectively, but
they do not use {help label:value labels}, and they do contain precautionary features to prevent the loss of information.
{cmd:sdecode} and {helpb sencode}, on the other hand, do use {help label:value labels}, and
allow the possibility that the mapping from numeric values to string values can be many-to-one.


{title:Examples}

{p 8 12 2}{cmd:. sdecode price, replace}{p_end}

{p 8 12 2}{cmd:. sdecode foreign, replace labonly}{p_end}

{p 8 12 2}{cmd:. sdecode foreign, gene(origin)}{p_end}

{p 8 12 2}{cmd:. sdecode foreign, gene(origin) maxlen(3)}{p_end}

{p 8 12 2}{cmd:. replace foreign=_n/_N if mod(_n,2)}{p_end}
{p 8 12 2}{cmd:. sdecode foreign, gene(origin1)}{p_end}
{p 8 12 2}{cmd:. sdecode foreign, gene(origin2) format(%8.4f)}{p_end}

{p 8 12 2}{cmd:. sdecode rep78, gene(srep78) missing}{p_end}

{p 8 12 2}{cmd:. sdecode price, gene(sprice) prefix($)}{p_end}

{p 8 12 2}{cmd:. sdecode weight, gene(sweight) suffix(" lb")}{p_end}


{title:Author}

{pstd}
Roger Newson, Imperial College London, UK.
Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk}


{title:Also see}

{p 4 13 2}
{bind: }Manual: {hi:[D] compress}, {hi:[D] destring}, {hi:[D] encode}, {hi:[D] format}, {hi:[D] functions}, {hi:[D] generate}, {hi:[D] label}
{p_end}
{p 4 13 2}
On-line: help for {helpb compress}, {helpb decode}, {helpb destring}, {helpb encode}, {helpb format}, {helpb functions}, {helpb generate}, {helpb label}, {helpb tostring}
{break} help for {helpb sencode} if installed
{p_end}