Miscellaneous Functions

clear

Discard the contents of a variable.

Syntax

clear
clear(v1, v2, ...)
clear('-functions')

Description

Without argument, clear discards the contents of all the local variables, including input arguments. With string input arguments, clear(v1,v2,...) discards the contents of the enumerated variables. Note that the variables are specified by strings; clear is a normal function which evaluates its arguments.

clear is usually not necessary, because local variables are automatically discarded when the function returns. It may be useful if a large variable is used only at the beginning of a function, or at the command-line interface.

clear('-functions') or clear('-f') removes the definition of all functions. It can be used only from the command-line interface, not in a function.

Example

a = 2;
b = 3;
clear('a');
a
  Undefined variable 'a'
b
  3

See also

variable assignment

dumpvar

Dump the value of an expression as an affectation to a variable.

Syntax

dumpvar(value)
dumpvar(name,value)
dumpvar(fd,name,value)
str = dumpvar(value)
str = dumpvar(name,value)

Description

dumpvar(fd,name,value) writes to the channel fd (the standard output by default) a string which would set the variable name to value, if it was evaluated by LME. If name is omitted, only the textual representation of value is written.

With an output argument, dumpvar stores result into a string and produces no output.

Examples

dumpvar(2+3)
  5
a = 6; dumpvar('a', a)
  a = 6;
s = 'abc'; dumpvar('string', s)
  string = 'abc';

See also

fprintf

error

Display an error message and abort the current computation.

Syntax

error(str)

Description

error(str) displays string str as an error message, and a user error is thrown. Unless the error is catched by a try block, the computation is aborted.

Example

error('Invalid argument.')
Invalid argument.

See also

warning, try

eval

Evaluate the content of a string as an expression or statements.

Syntax

x = eval(str_expression)
eval(str_statement)

Description

If eval has output argument(s), the input argument is evaluated as an expression whose result(s) is returned. Without output arguments, the input argument is evaluated as statement(s).

Examples

eval('1+2')
  3
a = eval('1+2')
  a = 3
eval('a=2+3')
  a = 5

See also

feval

exist

Existence of a function or variable.

Syntax

b = exist(name)
b = exist(name, type)

Description

exist returns true if its argument is the name of an existing function or variable, or false otherwise. A second argument can restrict the lookup to builtin functions ('builtin'), user functions ('function'), or variable ('variable').

Examples

exist('sin')
  true
exist('cos', 'function')
  false

feval

Function evaluation.

Syntax

(argout1,...) = feval(fun,argin1,...)

Description

(y1,y2,...)=feval(fun,x1,x2,...) evaluates function fun given with input arguments x1, x2, etc. Output arguments are assigned to y1, y2, etc. Function fun is specified either by its name as a string or by an inline function.

Examples

y = feval('sin', 3:5)
  y =
    0.1411 -0.7568 -0.9589
y = feval(inline('sin(2*x)'), 3:5)
  y =
    -0.2794 0.9894 -0.544

See also

eval, apply, inline, operator @

help

Help about an LME function.

Syntax

help functionname
help('operator')
help

Description

help functionname displays a help message about function whose name is functionname. help('operator') displays a help message about an operator. help without argument displays a message about the help command itself.

For user functions, help uses the first comment which immediately follows the function header. The comment may be a continuous set of lines beginning with % or //, or a single block of lines delimited with /* and */. Alternatively for user functions, or for built-in or extension functions, the help text is found in files with suffix ".hlp" in the same folders as libraries.

Examples

Help about function sin:

help sin
Sine.

SYNTAX
y = sin(x)
...

Help about operator +:

help('+')
Addition.

SYNTAX
x + y
M1 + M2
...

Source code of function dctmtx with its help comment block:

function T = dctmtx(n)
/*
Discrete cosine transform matrix.

SYNTAX
T = dctmtx(n)

DESCRIPTION
dctmtx(n) returns an n-by-n square matrix T such that
Y=T*y is the discrete cosine transform of the columns
of y. The inverse transform is given by y=T'*Y, and
the 2-d transform, applied to an n-by-n square matrix
M, is T*M*T'.

SEE ALSO
fft, fft2
*/
	T = [repmat(1/sqrt(n),1,n); ...
		sqrt(2/n)*cos(pi/(2*n)*repmat(1:2:2*n,n-1,1)...
			.*repmat((1:n-1)',1,n))];

See also

which

info

Information about LME.

Syntax

info
info builtin
info functions
info methods
info variables
info libraries
info usedlibraries

Description

info displays the language version.

info builtin displays the list of built-in functions and operators.

info functions displays the list of user-defined functions.

info methods displays the list of methods.

info variables displays the list of variables with their type and size.

info libraries displays the list of all loaded libraries.

info usedlibraries displays the list of libraries available in the current context.

Only the first character of the argument is meaningful; info b is equivalent to info buitin.

Examples

info
  LME 1.3
info b
  abs
  acos
  acosh
  (etc.)
info v
  ans (1x1 complex)

See also

which

inline

Creation of inline function.

Syntax

fun = inline(funstr)
fun = inline(expr)
fun = inline(expr, arg1, ...)

Description

Inline function are LME objects which can be evaluated to give a result as a function of their input arguments. Contrary to functions declared with the function keyword, inline functions can be assigned to variables, passed as arguments, and built dynamically. Evaluating them with feval is faster than using eval with a string, because they are compiled only once to an intermediate code. They can also be used as the argument of functions such as fzero and fmin.

inline(funstr) returns an inline function whose source code is funstr. Input argument funstr follows the same syntax as a plain function. The function name is ignored.

inline(expr) returns an inline function with one implicit input argument and one result. The input argument expr is a string which evaluates to the result. The implicit input argument of the inline function is a symbol made of a single lower-case letter different from i and j, such as x or t, which is found in expr. If several such symbols are found, the one closer to x in alphabetical order is picked.

inline(expr,arg1,...) returns an inline function with one result and the specified arguments arg1 etc. These arguments are also given as strings.

Examples

A simple expression, evaluated at x=1 and x=2:

fun = inline('cos(x)*exp(-x)');
y = feval(fun, 2)
  y =
    -5.6319e-2
y = feval(fun, 5)
  y =
    1.9113e-3

A function of x and y:

fun = inline('exp(-x^2-y^2)', 'x', 'y');

A function with two output arguments (the string is broken in three lines to have a nice program layout):

fun = inline(['function (a,b)=f(v);',...
              'a=mean(v);',...
              'b=prod(v)^(1/length(v));']);
(am, gm) = feval(fun, 1:10)
  am =
    5.5
  gm =
    4.5287

See also

function, operator @, feval, eval

lasterr

Last error message.

Syntax

s = lasterr

Description

lasterr returns a string which describes the last error. It can be used in the catch part of the try construct.

See also

try, error

nargin

Number of input arguments.

Syntax

n = nargin
n = nargin(fun)

Description

Calling a function with less arguments than what the function expects is permitted. In this case, the trailing variables are not defined. The function may use the nargin function to know how many arguments were passed by the caller to avoid accessing the undefined variables.

Note that if you want to have an optional argument before the end of the list, you have to interpret the meaning of the variables yourself. LME always sets the nargin first arguments.

With one argument, nargin(fun) returns the (maximum) number of input arguments a function accepts. fun may be the name of a built-in or user function, or an inline function. Functions with a variable number of input arguments (such as fprintf) give -1.

Examples

A function with a default value (pi) for its second argument:

function x = multiplyByScalar(a,k)
if nargin < 2                 % multiplyByScalar(x)
  k = pi;                        % same as multiplyByScalar(x,pi)
end
x = k * a;

A function with a default value (standard output) for its first argument. Note how you have to interpret the arguments.

function fprintstars(fd,n)
if nargin == 1                   % fprintstars(n) to standard output
  fprintf(repmat('*',1,fd));     % n is actually stored in fd
else
  fprintf(fd, repmat('*',1,n));
end

Number of input arguments of function plus (usually written "+"):

nargin('plus')
  2

See also

nargout, varargin

nargout

Number of output arguments.

Syntax

n = nargout
n = nargout(fun)

Description

A function may be called with between 0 and the number of output arguments listed in the function definition. The function can use nargout to check whether some output arguments are not used, so that it can avoid computing them or do something else.

With one argument, nargout(fun) returns the (maximum) number of output arguments a function can provide. fun may be the name of a built-in or user function, or an inline function. Functions with a variable number of output arguments (such as feval) give -1.

Example

A function which prints nicely its result when it is not assigned or used in an expression:

function y = multiplyByTwo(x)
if nargout > 0
  y = 2 * x;
else
  fprintf('The double of %f is %f\n', x, 2*x);
end

Maximum number of output arguments of svd:

nargout('svd')
  3

See also

nargin, varargout, function

varargin

Remaining input arguments.

Syntax

function ... = fun(..., varargin)
l = varargin

Description

varargin is a special variable which may be used to collect input arguments. In the function declaration, it must be used as the last (or unique) input argument. When the function is called with more arguments than what can be assigned to the other arguments, remaining ones are collected in a list and assigned to varargin. In the body of the function, varargin is a normal variable. Its elements may be accessed with the brace notation varargin{i}. nargin is always the total number of arguments passed to the function by the caller.

Example

Here is a function which accepts any number of square matrices and builds a block-diagonal matrix:

function M = blockdiag(varargin)
  M = [];
  for block = varargin
    // block takes the value of each input argument
    (m, n) = size(block);
    M(end+1:end+m,end+1:end+n) = block;
  end

In the call below, varargin contains the list {ones(3),2*ones(2),3}.

blockdiag(ones(3),2*ones(2),3)
     1     1     1     0     0     0
     1     1     1     0     0     0
     1     1     1     0     0     0
     0     0     0     2     2     0
     0     0     0     2     2     0
     0     0     0     0     0     3

See also

nargin, varargout, function

varargout

Remaining output arguments.

Syntax

function (..., varargout) = fun(...)
varargout = ...

Description

varargout is a special variable which may be used to dispatch output arguments. In the function declaration, it must be used as the last (or unique) output argument. When the function is called with more output arguments than what can be obtained from the other arguments, remaining ones are extracted from the list varargout. In the body of the function, varargout is a normal variable. Its value can be set globally with the brace notation {...} or element by element with varargout{i}. nargout may be used to know how many output arguments to produce.

Example

Here is a function which differentiates a vector of values as many times as there are output arguments:

function varargout = multidiff(v)
  for i = 1:nargout
    v = diff(v);
    varargout{i} = v;
  end

In the call below, [1,3,7,2,5,3,1,8] is differentiated four times.

(v1, v2, v3, v4) = multidiff([1,3,7,2,5,3,1,8])
v1 =
     2     4    -5     3    -2    -2     7
v2 =
     2    -9     8    -5     0     9
v3 =
   -11    17   -13     5     9
v4 =
    28   -30    18     4

See also

nargout, varargin, function

warning

Write a warning to the standard error channel.

Syntax

warning(msg)

Description

warning(msg) displays the string msg. It should be used to notify the user about potential problems, not as a general-purpose display function.

Example

warning('Doesn\'t converge.');

See also

error, disp

which

Library where a function is defined.

Syntax

fullname = which(name)

Description

which(name) returns an indication of where function name is defined. If name is a user function or a method prefixed with its class and two colons, the result is name prefixed with the library name and a slash. If name is a built-in function, it's prefixed with (builtin). If it is a variable, it is prefixed with (var). If name is neither a function nor a variable, which returns the empty string.

Examples

which cross
  stdlib/cross
which polynom::plus
  classes/polynom::plus
which sin
  (builtin)/sin
x = 2;
which x
  (var)/x

See also

info


Copyright 1998-2001, Calerga.

All rights reserved.