help mata mm_strexpand()
-------------------------------------------------------------------------------

Title

    mm_strexpand() -- Expand string argument


Syntax

        string scalar mm_strexpand(s, list)

        string scalar mm_strexpand(s, list, default)

        string scalar mm_strexpand(s, list, default, unique)

        string scalar mm_strexpand(s, list, default, unique, errtxt)

        real scalar   _mm_strexpand(res, s, list [, default, unique])

    where

                     s:  string scalar s
                  list:  string vector list
               default:  string scalar default
                unique:  real scalar unique
                errtxt:  string scalar errtxt


Description

    mm_strexpand() returns the first element in string vector list that
    matches string s if abbreviated to the number of characters contained in
    s.  mm_strexpand() aborts with error, if no match is found.

    mm_strexpand() returns string default, if s is empty (or empty string, if
    default is omitted).

    If list contains several possible matches, the first match is returned by
    mm_strexpand(). However, unique!=0 causes mm_strexpand() to abort with
    error in the case of multiple matches.

    mm_strexpand()'s standard error message is "3499 "s" invalid" if no match
    is found or "3498 "s" invalid" if unique!=0 and multiple matches are
    found. Use string errtxt to specify an alternative error text. The error
    code is always 3499 or 3498.

    _mm_strexpand() is like mm_strexpand() except that the expanded string,
    if a match is found, is stored in res and, rather than aborting with
    error, the error code is returned. The error code is 0 if no error
    occurred. The type of res does not matter. It is replaced.


Remarks

    mm_strexpand() is useful to parse string scalar arguments in Mata
    functions that are intended to be used interactively. Suppose that you
    want to program a function kerneldensity(x, kernel) where kernel is one
    of "epanechnikov", "biweight", "gaussian", or "epan2". Coding

        : function kerneldensity(x, | string scalar kernel)
        > {
        >         k = mm_strexpand(kernel,("epanechnikov", "biweight",
        >          "gaussian", "epan2"), "gaussian")
        >         ...
        > }

    enables the user to type abbreviated kernel names.  For example,

        : kerneldensity(x, "e") 

    uses the epanechnikov kernel. Furthermore, note that "gaussian" is the
    default in this example. Thus

        : kerneldensity(x) 

    uses the gaussian kernel.

    _mm_strexpand() can be used, for example, as follows:

        : function kerneldensity(x, | string scalar kernel)
        > {
        >         err = _mm_strexpand(k="", kernel,("epanechnikov",
        >          "biweight", "gaussian", "epan2"), "gaussian")
        >         if (err) {
        >                 ... err ...
        >         }
        >         else {
        >                 ... k ...
        >         }                
        > }


Conformability

    mm_strexpand(s, list, default, unique, errtxt)
            s: 1 x 1
         list: r x 1 or 1 x c
      default: 1 x 1
       unique: 1 x 1
       errtxt: 1 x 1
       result: 1 x 1.


Diagnostics

    mm_strexpand() aborts with error if list is void (meaning that no match
    is found).


Source code

    mm_strexpand.mata


Author

    Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch


Also see