help lookfor_val
-------------------------------------------------------------------------------

Title

     lookfor_val -- Search value pattern in current dataset


Syntax

     Basic syntax

        lookfor_val [, pattern(pattern)]

     Full syntax

        lookfor_val [varlist] [if] [in] [, options]


    options                Description
    -------------------------------------------------------------------------
      pattern(pattern)     search values matching pattern

    search
      insensitive          perform case-insensitive search
      missing              do not exclude missing values
      string               search string variables
      numeric              search numeric variables
      format(%fmt)         use fmt for numeric values

    results
      values               display and save in r() values matching pattern
      describe             describe variables with values matching pattern
      list                 list variables with values matching pattern
      tabulate             tabulate variables with values matching pattern
      separate(str)        use str as separator in returned results
      noprint              do not display results
    -------------------------------------------------------------------------

    pattern is one string, possibly including the wildcard characters *
        and/or ?, where the former means 0 or more characters, the latter
        means exactly 1 character.


Description

    lookfor_val searches the current dataset for values matching a specified
    pattern. Variables in which values matching pattern are found, are listed
    and their names are returned in r(varlist).

    If varlist is not specified, it defaults to _all. Not specifying pattern
    sets the pattern to * meaning all (non-missing) values.

    lookfor_val is typically used to search string variables.  However, if
    not specified otherwise, string and numeric variables are searched.


Options

    pattern(pattern) specifies the value pattern to be searched.  The
        wildcards * and ? may be used, where the former means zero or more
        characters and the latter means exactly one character.  Compound
        double quotes are needed if pattern contains double quotes. Double
        quotes are needed if pattern contains leading or trailing blanks, and
        are not needed otherwise. If not specified, pattern defaults to *.

        +--------+
    ----+ search +-----------------------------------------------------------

    insensitive performs a case-insensitve search. The option only affects
        the search in string variables.

    missing treats missing values as valid. Default is to exclude missing
        values. Specify missing if you specified missing values (i.e. "" or
        one of ., .a, .b, ..., .z) in pattern. Specifying missing without
        specifying pattern sets pattern to "", or . if numeric is also
        specified.

    string specifies that string variables be searched. Default is to search
        string and numeric variables. Specify string to search string
        variables only.

    numeric specifies that numeric variables be searched. Default is to
        search string and numeric variables. Specify numeric to search
        numeric variables only.

    format(%fmt) uses fmt searching for pattern in numeric variables. Default
        is to use variables' output format. This option is seldom used. It
        may be used to replicate behavior of older versions of the program.
        If you want to do this, sepcify fmt as 18.0g.

        +---------+
    ----+ results +----------------------------------------------------------

    values lists and saves in r(values_varname) distinct values matching
        pattern. If specified, variable names are neither listed nor returned
        in r(varlist).

    describe describes variables with values matching pattern. This option
        may not be used with values.

    list lists values matching pattern. This option implies values. Values
        will be returned in r(values_varname) but will not be displayed.

    tabulate tabulates values matching pattern. This option implies values.
        Values will be returned in r(values_varname) but will not be
        displayed.

    separate(str) uses str as separator between elements in returned results.
        Default separator is " ".

    noprint does not display returned results.


Remarks

    lookfor_val returns erroneous results if a value contains an unbalanced
    compound double quote (`" or "'), but does not issue an error message.
    These characters are likely to break other Stata commands (e.g. 
    levelsof), so these commands might be used to check for potential
    problems.


Examples

        . sysuse auto
        . lookfor_val ,pattern(*v*) string
        . lookfor_val ,pattern(*v*) string values
        . lookfor_val ,pattern(*v*) string values insensitive
        . lookfor_val make ,pattern(*A*) tabulate

        . lookfor_val ,pattern(*07?) numeric

                  
Saved results

    lookfor_val saves one of the following in r():

      r(varlist)          variables with values matching pattern (not with
                            values)
      r(values_varname)   values in varname matching pattern (option values
                            only)


Acknowledgments

    Bug reports from Matthew White led to fruitful discussions and a major
    revison of the code.


Author

    Daniel Klein, University of Kassel, klein.daniel.81@gmail.com


Also see

    Online: ds, lookfor
    if installed: lookfor_all, findname