doc/efun/catch

SYNOPSIS
        mixed catch(expr, expr, ...)
        mixed catch(expr, expr, ... ; modifiers)

DESCRIPTION
        Evaluate the expressions. If there is no error, 0 is returned.
        If there is an error, the evaluation of the expressions stops at
        that point, and a string with the error message is returned.

        System error messages start with a leading '*', user-defined
        error values (other than 0) as given to throw() and raise_error() are
        returned as they are.

        If at the time the catch() is encountered less than
        __CATCH_EVAL_COST__ eval ticks are left, a runtime error will be
        thrown from inside the catch() (and thus caught like every other
        error) and the expressions will not be executed. The 'reserve'
        modifier can be used to reserve a different amount of eval ticks.

        The default behaviour of catch() can be changed using modifiers:

          'nolog':   Normally, the caught error will be logged in the
                     error logs for easier debugging. With this
                     modifier, the log is suppressed.

          'publish': Normally, master::runtime_error() is not called
                     for a caught error. This modifier instructs
                     catch() to call it nevertheless.

          'reserve <expr>': The expression has to evaluate to a number
                     greater than 0 and is used to determine the amount
                     of eval ticks to reserve, instead of the default
                     of __CATCH_EVAL_COST__. The minimum required
                     are 2 * __MASTER_EVAL_COST__.
          'limit <expr>': The expression has to evaluate to a number
                     greater than 0 and is used to limit the eval cost
                     for the evaluation of the expression.

        catch() itself is not expensive as far as execution time is
        concerned: it is about the same as a intra-object function call.

        throw() is not very expensive either, but does include the
        internal cleanup of several structures.

        Real runtime errors on the other hand are expensive regardless
        of whether they are caught or not, as they include the generation 
        of the stack backtrace.

        catch() is not really an efun but a compiler directive.

EXAMPLES
        object obj;
        string err;
        if (err = catch(obj = clone_object("/foo/bar/baz")))
           write("Cannot clone object, reason:"+err"+\n");

HISTORY
        LDMud 3.2.9 introduced the 'nolog' catch() as experimental feature.
        LDMud 3.2.10 implemented 'nolog' as official form and added
          'publish'.
        LDMud 3.3.559 moved the check regarding __CATCH_EVAL_COST__ inside
          the catch().
        LDMud 3.3.560 added the 'reserve' modifier.
        LDMud 3.6.7 added the 'limit' modifier.

SEE ALSO
        throw(E), raise_error(E), predefined(D), runtime_error(M)