Next Previous Contents

2. std.ct

This section describes functions from file std.ct.

2.1 BatchMode

[y] = BatchMode()
 BatchMode() returns 1 if this Tela process is in batch mode
   (command line switch -b), otherwise 0.
See also: SilentMode, VerboseMode, UsingReadline.

2.2 CheckReadOnlyMode

[;y] = CheckReadOnlyMode(;x)
 CheckReadOnlyMode() returns 1 if this Tela process checks that function
   input arguments are not modified by the function. The check is done by
   default, but if it causes problems (bugs in Tela) you can turn it off
   using CheckReadOnlyMode(off).
   CheckReadOnlyMode returns the old mode setting.
See also: SilentMode, BatchMode, VerboseMode.
   Error codes:
   1: Argument not integer 

2.3 DebugQueryMode

[;y] = DebugQueryMode(;x)
 DebugQueryMode() returns 1 if the debug query mode
   has been set, otherwise 0.
   DebugQueryMode(on) and DebugQueryMode(off) change
   the current setting.

   If debug query mode is on, the program will ask whether
   the user wants to enter debug mode if control-C is
   pressed (INT signal sent). Otherwise the program simply
   stops on pressing control-C.
   Error codes:
   1: Argument not integer 

2.4 GetInstructionData

[Ninstructions,Noperations] = GetInstructionData(p,mnemo)
 [Ninstr,Nops] = GetInstructionData(p,"mnemonic") returns
   the number of specific instructions executed when p=perf() was
   gathered, and the number of (floating point) operations associated
   with the instruction.
   The mnemonic must be a string, and it may be any of the names
   that appear in the disasm(f) listing. In addition, mnemonic may
   be "flop", which includes all instructions that may perform floating
   point arithmetic, or it may be "*", which includes all instructions.
   Error codes:
   -1: Bad first argument, must be obtained from perf()
   -2: Second arg not a string
   -3: Second arg not a recognized string
   

2.5 HeavisideTheta

[y] = HeavisideTheta(x)
 y = HeavisideTheta(x) returns 1 if x>=0 and 0 if x<0.
   x must be real. If x is array, the operation is applied componentwise.
See also: sign.
   Error codes:
   -1: Complex or nonnumeric input argument 

2.6 Im

[y] = Im(x)
 y = Im(x) takes the imaginary part of a complex quantity x.
   If x is real or integer, the result is zero.
   If x is an array, the operation is applied componentwise.
See also: Re, conj, arg.
   Error codes:
   -1: Nonnumeric input argument 

2.7 Re

[y] = Re(x)
 y = Re(x) takes the real part of a complex quantity x.
   If x is real or integer, it is returned as such.
   If x is an array, the operation is applied componentwise.
See also: Im, conj, arg.
   Error codes:
   -1: Nonnumeric input argument 

2.8 SilentMode

[y] = SilentMode()
 SilentMode() returns 1 if this Tela process is in silent mode
   (command line switch -s), otherwise 0.
See also: BatchMode, VerboseMode, CheckReadOnlyMode.

2.9 UsingReadline

[y] = UsingReadline()
 UsingReadline() returns 1 if this Tela was compiled
   to use the GNU readline library, otherwise 0.
See also: BatchMode, SilentMode, VerboseMode.

2.10 VerboseMode

[;y] = VerboseMode(;x)
 VerboseMode() returns 1 if this Tela process is in verbose mode
   (command line switch -v), otherwise 0.
   VerboseMode(on) and VerboseMode(off) set the verbose mode on
   and off, respectively. They return the old mode setting.
See also: SilentMode, BatchMode.
   Error codes:
   1: Argument not integer 

2.11 abs2

[y] = abs2(x)
 y = abs2(x) computes the square of the absolute value of x.
   If x is real or integer, the result is just the square of x.
   If x is complex, the result is equal to x*conj(x), except that
   the latter would produce a complex result with zero or tiny
   (because of possible roundoff error) imaginary part.
   If x is an array, the operation is applied componentwise.
   Error codes:
   -1: Nonnumeric input argument 

2.12 acos

[y] = acos(x)
 y = acos(x) computes the arc cosine of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.13 all

[y] = all(x)
 all(x) returns 1 if all elements of x are nonzero,
   and 0 otherwise.
   x must be an integer array or scalar.

   Conditional statements (if, while, for, until) assume
   implicit all, for example saying
       if (A > 0) ...
   is equivalent of saying
       if (all(A > 0)) ... ,
   thus you will need all less frequently than you need any.
   
See also: any.
   Error codes:
   1: Argument not integer or IntArray 

2.14 any

[y] = any(x)
 any(x) returns 1 if at least one element of x is nonzero,
   and 0 otherwise.
   x must be a integer array or scalar.

   Conditional statements (if, while, for, until) default
   to implicit all, thus you sometimes need to use any
   with these statements.
   
See also: all.
   Error codes:
   1: Argument not integer or IntArray 

2.15 arg

[phi] = arg(z)
 arg(z) returns the argument of a complex quantity
   (in radians). The result is between -pi and pi.
   If z is a complex array, the operation is applied
   componentwise.
See also: Re, Im, conj.
   Error codes:
   -1: Argument has undefined value
   1: Nonnumeric argument 

2.16 asin

[y] = asin(x)
 y = asin(x) computes the arc sine of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.17 atan

[y] = atan(x)
 y = atan(x) computes the arc tangent of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.
See also: atan2.

2.18 atan2

[z] = atan2(y,x)
 z = atan2(y,x) computes the arcus tangent of y/x using the signs
   of both arguments to determine the quadrant of the return value.
   The input argument must be integer or real scalars and the
   return value is real. They can also be real arrays; in this case
   both must be arrays of the same length.
See also: atan.
   Error codes:
   -1: Bad input argument
   -2: Input arrays must be of same length

2.19 autoglobal

[] = autoglobal(...)
 autoglobal("sym1","sym2",...) sets the 'autoglobal' attribute
   to given symbols. The symbols are then globally accessible
   from inside packages and functions without need to explicitly
   declaring them global. Constants such as pi carry the autoglobal
   attribute automatically, but with this function it is possible
   for the user to define more autoglobal symbols.

   Warning: This function is for experts only. It is not advisable
   to say autoglobal("x"), for instance, because many existing code
   may then break down.
See also: hide.
   Error codes:
   1: Argument not a string 

2.20 autosource

[] = autosource(fn...)
 autosource("file.t","name1","name2",...) tags symbols
   name1, name2,... such that the command source("file.t")
   is effectively executed when any of the symbols name
   is used. This is load-on-demand.
See also: source.
   Error codes:
   1: Argument not a string 

2.21 avoid_constructors

[] = avoid_constructors(flag)
 avoid_constructors(on) affects the operation
   of subsequent t2ct function calls.
   When this flag is on, the generated C-tela (C++)
   code avoids constructing class objects on the stack
   but instead declares these objects as pointers and
   initializes them using the 'new' operator.
   This mode compiles on ATT Cfront versions that do not
   support goto statements in blocks having constructors.

   However, in some rare cases avoid_constructors(on)
   is known to produce incorrect code. The default is
   avoid_constructors(off).
See also: t2ct.
   Error codes:
   1: Argument not an integer

2.22 cd

[] = cd(fn)
 cd("pathname") will change the current directory to "pathname".
   cd("") will change to home directory.
   cd("~/my/dir") will change to directory "my/dir" in the
   home directory.
See also: getenv.
   Error codes:
   1: Input argument not a string
   2: Directory not found
   3: This system does not support cd 

2.23 ceil

[y] = ceil(x)
 ceil(x) returns the smallest integer which is larger than x.
   x must be integer or real scalar or array. If it is an array,
   the operation is applied componentwise.
See also: floor.
   Error codes:
   -1: Complex or nonnumeric input argument 

2.24 clear

[] = clear(...)
 clear() removes all variables that are visible from
   the whos() function from the workspace. Function definitions
   are not cleared. Variables in loaded packages are also not affected.

   clear("var1","var2",...) removes only the specified variables.
   If a string is not a variable name, no warning is given.
See also: whos, hide, unhide.
   Error codes:
   1: Bad argument, not a string

2.25 conj

[y] = conj(x)
 y = conj(x) computes the complex conjugate of x.
   Real and integer arguments are returned as such.
   If x is an array, the operation is applied componentwise.
See also: Re, Im, arg.

2.26 cos

[y] = cos(x)
 y = cos(x) computes the cosine function of x.
   If x is complex, the result is complex, otherwise real.
   The argument must be in radians.
   If x is an array, the operation is applied componentwise.

2.27 cosh

[y] = cosh(x)
 y = cosh(x) computes the hyperbolic cosine function of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.28 cot

[y] = cot(x)
 y = cot(x) is the cotangent function
   cot(x) = 1/tan(x) = cos(x)/sin(x). 

2.29 cputime

[t] = cputime(;p)
 cputime() returns the CPU time in seconds used by the current
   tela session. cputime(p) returns CPU time from performance data
   array p, previously obtained from perf().
See also: tic, toc, perf.
   Error codes:
   -1: Bad argument, must be obtained from perf() 

2.30 csc

[y] = csc(x)
 y = csc(x) is the cosecant function
   csc(x) = 1/sin(x). 

2.31 cumprod

[y] = cumprod(x)
 y = cumprod(x) forms an array of partial products
   y = #(x[1],x[1]*x[2],...,prod(x[1:n]),...).
   The result y has the same size and type as x. Unlike
   prod, cumprod does not try to avoid integer overflows.
   The array x is logically flattened, to apply
   along a specified dimension use map(cumsum,...).
   If x is scalar, it is returned as such.
See also: prod, cumsum, map.
   Error codes:
   -1: Nonnumeric input arg 

2.32 cumsum

[y] = cumsum(x)
 y = cumsum(x) forms an array of partial sums
   y = #(x[1],x[1]+x[2],...,sum(x[1:n]),...).
   The result y has the same size and type as x.
   The array x is logically flattened, to apply
   along a specified dimension use map(cumsum,...).
   If x is scalar, it is returned as such.
See also: sum, cumprod, map.
   Error codes:
   -1: Nonnumeric input arg 

2.33 diag

[y] = diag(x; offset)
 diag(V, K) (V is a vector) returns a square diagonal matrix, with
   vector V on the main diagonal (K == 0, default), the K-th super
   diagonal (K > 0) or the K-th sub-diagonal (K < 0).

   diag(M, K) (M is a matrix) returns the main diagonal (K == 0,
   default), the K-th super diagonal (K > 0), or the K-th sub-diagonal
   (K < 0) of M as a vector.  M need not necessarily be square.

   Error codes:
   -1: Input array X (arg 1) not vector or matrix
   -2: Expecting offset K (arg 2) to be integral
   -3: Internal error
    1: Requested diagonal out of range

2.34 disasm

[] = disasm(fn)
 disasm(f) produces disassembly listing of function f.
   Error codes:
   1: Argument not a Tela function 

2.35 error

[] = error(;msg)
 error("message") writes message and returns to the
   Tela main level.
   error() uses a default message.
See also: exit.
   Error codes:
   -1: Argument not a string

2.36 eval

[] = eval(s)
 eval("string") executes string as a Tela command, as it had been
   typed from the keyboard.
   The evaluation is done in global context. The symbols appearing
   in the string refer to the global ones.
See also: evalexpr.
   Error codes:
   1: Argument not a string 

2.37 evalexpr

[y] = evalexpr(s)
 y = evalexpr("expression") executes string as a Tela command,
   returning its value in y.
   The evaluation is done in global context. The symbols appearing
   in the string refer to the global ones.
See also: eval.
   Error codes:
   1: Argument not a string 

2.38 exit

[] = exit(;rv)
 exit() stops Tela, returning zero (success) exit code
   to the calling process.

   exit(n) returns exit code n instead of zero.
   n must be an int scalar.

   Function quit is a synonym for exit.
See also: error.
Error codes:
   1: expecting integer scalar for EXIT_CODE (arg 1).

2.39 exp

[y] = exp(x)
 y = exp(x) computes the exponent function of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.40 find

[y] = find(x)
 I=find(V) returns the index vector I=(i) for which
   V[i] is nonzero. V must be an integer array. The length
   of I is equal to the number of nonzeros in V.
   If V is multidimensional, it is used in flattened form.

   Example: If V=#(1,-2.3,4,5,-8.2), find(V < 0) returns
   #(2, 5).
   
See also: any, all, flatten.
   Error codes:
   1: Argument not integer vector 

2.41 flatten

[y] = flatten(;x)
 flatten(x) returns the array x flattened to a vector.
   If x is not an array, it is returned as is.

   Example: flatten(#(1,2; 3,4)) returns #(1,2,3,4).
   
   x = flatten() flattens x "in place". This is much faster
   (it works in constant time) than to do x = flatten(x),
   since no data movement is involved. 

2.42 flip

[y] = flip(x;d)
 flip(A) reverses the first dimension of array A.
   flip(A,d) reverses the d'th dimension. For example,
   flip(#(1,6,2; 7,9,2.3),2) returns #(2,6,1; 2.3,9,7).
   If A is non-array it is returned as such, regardless of d.
See also: transpose.
   Error codes:
   -1: Second argument not an integer scalar
   -2: Second argument out of range 

2.43 floor

[y] = floor(x)
 floor(x) returns the largest integer which is smaller than x.
   x must be integer or real scalar or array. If it is an array,
   the operation is applied componentwise.
See also: ceil.
   Error codes:
   -1: Complex or nonnumeric input argument 

2.44 gaussrand

[x] = gaussrand(...)
 gaussrand() returns a Gaussian-distributed random real.
   The distribution function is f(x) = (1/(2*pi))*exp(-0.5*x^2)
   so that the mean is zero and the standard deviation is unity.
   gaussrand(N) returns a vector of length N,
   gaussrand(N,M) returns a matrix of size N x M, etc.
   Example: To test gaussrand, plot it together with the distribution
   function, as follows:

   N=50000; x=-4:0.1:4; y=(N/(2*pi))*exp(-0.5*x^2);
   hold(on); hist(gaussrand(N),20,-4,4); plot(x,y); hold(off);
See also: rand, srand.
   Error codes:
   -1: Tried to create too high rank array
   -2: Argument not an integer
   -3: Non-positive integer argument

2.45 getenv

[y] = getenv(varname)
 getenv("envvar") returns the value of environment variable
   "envvar", or VOID if such variable is not defined in
   the UNIX environment.

   For example, getenv("LOGNAME") returns the login name of
   the owner of the Tela prcess.
   (If Unix functions are not available, getenv will always
   return VOID.)
See also: putenv, getpid, cd.
   Error codes:
   -1: Argument not a string
   

2.46 getpid

[y] = getpid()
 getpid() returns the process ID of the Tela process.
   This can be used e.g. to generate unique temporary
   file names. If Unix functions are not available,
   getpid() returns 0. 

2.47 help

[] = help(;fn)
 help(function-name) or help("help-item") displays the help information
   associated with a given function or a given help item. On command line
   you may use the abbreviation

      ?help-item
   or
      help help-item

   These forms are translated to help("help-item") before parsing.

   First tries:
   help operators
   help special
   help if
   help for
   help function
   ...
   
   Error codes:
   1: Item not found
   2: Cannot open help file 

2.48 herm

[B] = herm(A; P)
 herm(A) is the same as conj(transpose(A)).
   herm(A,P) is the same as conj(transpose(A,P)).
   You can abbreviate "herm(A)" as "A'".
See also: transpose, flip, conj.
   Error codes:
   -1: Permutation argument not integer array
   -2: Permutation argument of bad rank or size
   -3: Permutation argument contains invalid integers 

2.49 hide

[] = hide(...)
 hide("sym-name",...) sets the 'hidden' attribute to
   specified symbols.
See also: whos, unhide, autoglobal.
   Error codes:
   1: Argument not a string
   2: Argument does not name a symbol
   

2.50 info

[] = info()
 info() shows information about various class sizes for this Tela implementation.
   It also prints the total counts of Tnode, Tprg and Tobject objects at the moment. 

2.51 input_string

[s] = input_string(;prompt)
 input_string() waits for an input line from the keyboard
   and returns it as a string. The newline is not included
   in the result.
   If the string is enclosed in double quotes, they are removed.

   input_string("prompt") displays prompt first.
   Error codes:
   -1: EOF encountered. 

2.52 isCfunction

[y] = isCfunction(x)
 isCfunction(x) returns 1 if x is a C-tela function.
   and 0 otherwise.
See also: isfunction, isTfunction.

2.53 isTfunction

[y] = isTfunction(x)
 isTfunction(x) returns 1 if x is a function written in Tela
   and 0 otherwise.
See also: isfunction, isCfunction.

2.54 isarray

[y] = isarray(x)
 isarray(x) returns 1 if x is an array and 0 if it is not.
See also: isscalar, isvector, ismatrix.

2.55 ischar

[y] = ischar(x)
 ischar(x) returns 1 if x is a character and 0 otherwise.
See also: isstring, isstr.

2.56 iscomplex

[y] = iscomplex(x)
 iscomplex(x) returns 1 if x is a complex array or scalar,
   and 0 if it is real or integer or a nonnumeric object.
See also: isreal, isfloat, isint.

2.57 isdefined

[y] = isdefined(x)
 isdefined(x) returns 1 if x is not undefined and 0 if
   it is undefined. Optional function arguments are undefined
   if not assigned by the caller; isdefined can be used
   inside the function to test whether this is the case.
See also: isundefined.

2.58 isfinite

[y] = isfinite(x)
 isfinite(x) returns 1 if x is a finite number and 0 otherwise.
   If x is array, the operation is applied componentwise.
   If x is non-numeric it is considered not finite.
   Integer and consequently strings and chars are always finite. 

2.59 isfloat

[y] = isfloat(x)
 isfloat(x) returns 1 if x is a floating point array
   or scalar, and 0 otherwise. Notice the difference between
   isfloat and isreal. isreal(x) is 1 for integer objects,
   while isfloat(x) is 0.
See also: isreal, isint, iscomplex.

2.60 isfunction

[y] = isfunction(x)
 isfunction(x) returns 1 if x is a function
   (Tela-function, C-tela function or intrinsic function)
   and 0 otherwise.
See also: isCfunction, isTfunction.

2.61 isint

[y] = isint(x)
 isint(x) returns 1 if x is integer scalar or array
   and 0 if it is not.
See also: isreal, isfloat, iscomplex.

2.62 islist

[y] = islist(x)
 islist(x) returns 1 if x is a heterogenous collection and 0 otherwise. 

2.63 ismatrix

[y] = ismatrix(x)
 ismatrix(x) returns 1 if x is a matrix (2D array)
   and 0 if it is not.
See also: isscalar, isvector, isarray.

2.64 isreal

[y] = isreal(x)
 isreal(x) returns 1 if x is numerical non-complex
   array or scalar, and 0 otherwise.
See also: isfloat, isint, iscomplex.

2.65 isscalar

[y] = isscalar(x)
 isscalar(x) returns 1 if x is scalar and 0 if it is not.
See also: isvector, ismatrix, isarray.

2.66 isstr

[y] = isstr(x)
 isstr(x) returns 1 if x is a character or string
   and 0 otherwise.
See also: isstring, ischar.

2.67 isstring

[y] = isstring(x)
 isstring(x) returns 1 if x is a string and 0 otherwise.
See also: ischar, isstr.

2.68 isundefined

[y] = isundefined(x)
 isundefined(x) returns 1 if x is not undefined and 0 if
   it is undefined. Optional function arguments are undefined
   if not assigned by the caller; isdefined can be used
   inside the function to test whether this is the case.
See also: isdefined.

2.69 isvector

[y] = isvector(x)
 isvector(x) returns 1 if x is a vector and 0 if it is not.
See also: isscalar, ismatrix, isarray.

2.70 isvoid

[y] = isvoid(x)
 isvoid(x) returns 1 if x is a void value and 0 otherwise. 

2.71 length

[L] = length(x)
 length(x) returns the total number of elements in array x.
   If x is scalar, length(x) is 1. If x is undefined, an error
   results. Notice that if x is e.g. a matrix, its length is
   equal to the product of the row and column dimensions,
   which is different from e.g. the Matlab convention.
See also: size, rank.
   Error codes:
   -1: Argument has undefined value 

2.72 limit

[y] = limit(x,a,b)
 limit(x,a,b) limits x to the range [a,b].
   x may be an integer or real array or scalar,
   the a and b arguments must be integer or real
   scalars. The result type is integer only
   if all x,a,b are integers, otherwise it is real.
   limit(x,a,b) is equivalent to min(b,max(x,a)).

   Notice: limit is builtin function in >=1.23
   version. Before 1.23 it was a t-file function.

   (Usually a<=b, if a>b then limit(x,a,b) has the
   value of b but this behavior should not be trusted.)
   Error codes:
   -1: First arg not int or real
   -2: Second arg not int or real scalar
   -3: Third arg not int or real scalar

2.73 log

[y] = log(x)
 y = log(x) computes the natural logarithm of x.
   If x is complex, the result is complex. If x is real or
   integer, but negative, the result is complex (purely
   imaginary). If x is real or integer and non-negative,
   the result is real.
   If x is an array, the operation is applied componentwise.
   If some of the components are negative, all components
   of the result are complex. 

2.74 map

[B] = map(fn,A,darg)
 [B] = map(fn,A,d) maps function fn along d'th dimension
   in array A. Fn is a functional argument. It must return a scalar
   or a vector when called with one vector argument. The type and length
   of the returned value must not change from call to call.

   For example, map(mean,A,1) computes the columnwise means
   of matrix A, returning a vector. map(sort,A,2) sorts all rows
   of matrix A in ascending order. Notice than many standard
   functions, including mean, have a builtin mapping capabability;
   using map in these cases is unnecessary.
See also: mapmin, mapmax, flip.
   Error codes:
   -1: First arg not a function
   -2: Second arg not a numerical array
   -3: Third arg not an integer scalar
   -4: Third arg (the dimension) out of range
   -5: First arg (function) did not return a numerical object
   -6: First arg (function) unexpectedly changed its return type
   -7: First arg is an intrinsic function; it is no good
   -8: Function returned rank>1 array when first called

2.75 mapmax

[y;P] = mapmax(x;d)
 mapmax(x,d) finds maximum along d'th dimension in array x.
   The result is an array with rank one less than rank(x).
   The array may not be complex.
   [M,p] = mapmax(x,d) returns the maximum positions p along with
   the maximums m. The array p is of the same shape as M, but is
   integer-valued.

   mapmax(x) is a flattened form which returns a scalar result.
   It is equivalent to max(x). [M,p] = mapmax(x) also works.

   Using mapmax is faster than using map and max together.
   In the latter case you would also have to define another function:
       function y=max1(x) {y=max(x)}
   because being intrinsic function, max can not be passed
   to map directly. 
   
See also: mapmin, map, limit.
   Error codes:
   -1: First arg not a numerical array
   -2: Second arg not an integer scalar
   -3: Second arg (the dimension) out of range
   -4: First arg is complex 

2.76 mapmin

[y;P] = mapmin(x;d)
 mapmin(x,d) finds minimum along d'th dimension in array x.
   The result is an array with rank one less than rank(x).
   The array x may not be complex.
   [m,p] = mapmin(x,d) returns the minimum positions p along with
   the minimum values m. The array p is of the same shape as m,
   but is integer-valued.

   mapmin(x) is a flattened form which returns a scalar result.
   It is equivalent to min(x). [m,p] = mapmin(x) also works.

   Using mapmin is faster than using map and min together.
   In the latter case you would also have to define another function:
       function y=min1(x) {y=min(x)}
   because being intrinsic function, min can not be passed
   to map directly. 
   
See also: mapmax, map, limit.
   Error codes:
   -1: First arg not a numerical array
   -2: Second arg not an integer scalar
   -3: Second arg (the dimension) out of range
   -4: First arg is complex 

2.77 meminuse

[m] = meminuse()
 meminuse() returns the size of the current Tela process
   in bytes. The result is a real number.

   Implementation: It uses the getrusage function if it is available
   and if it seems to be working properly. Otherwise it calls sbrk(0),
   which should return the data segment size in bytes. On Cray UNICOS
   it multiplies the sbrk(0) value by 8 (Cray is a word machine).
   If sbrk is not available, it returns always 0.
   - Surprisingly, many Unix systems have the getrusage function but
   the relevant field in struct rusage is always returned as zero.
   In this case the sbrk method is used.
   - On some machines the result is unreliable.

   If Tela has been compiled with TELASPECIFIC_NEWDELETE defined,
   Tela's own new/delete operators are in use. In this case meminuse
   will report the memory asked from the OS with malloc from C++ code
   only. Any use of malloc from C code (GNU readline library, HDF library ...)
   will thus not be included, as also not the data segment and stack size.
   The result can nevertheless be a useful measure of the user memory.
   You can tell if TELASPECIFIC_NEWDELETE is on by looking at the output
   of the info() function.
See also: info.

2.78 menu

[result] = menu(title...)
 choice = menu("title","choice1","choice2",...) displays
   a menu of choices and returns the number entered by
   the user.
See also: smenu.
   Error codes:
   -1: Less than two input args 

2.79 ones

[y] = ones(...)
 ones(n,m...) returns an integer array with all elements
   equal to 1 of size n x m x ... .

   ones(V) where V is an integer vector, and thus
   ones(size(A)), works also.
See also: rand, eye.
   
   Error codes:
   -1: Input argument not an integer or IntVector
   -2: Rank of requested tensor array exceeds MAXRANK
   -3: Non-positive input argument
   -4: Negative input argument
   -5: Integer array rank not 1
   

2.80 pause

[] = pause(;seconds)
 pause() will wait for a keypress on keyboard.
   pause(n) will pause for n seconds and then continue.
   The argument n may be integer or real.

   Note: some systems implicitly round a real argument
   to nearest whole number.
   Error codes:
   1: Argument not a real scalar
   2: Argument is negative
   3: This system does not support pausing for n seconds 

2.81 perf

[v] = perf()
 perf() returns an array containing all maintained operation
   counters. To measure performance of a code segment, do

   p0=perf(); mycode(); p=perf()-p0;

   Now you can apply various performance-related functions to p:
   for example cputime(p), Mflops(p). 

2.82 prod

[y] = prod(x;d)
 prod(x) multiplies all the elements of x, if x is an array.
   prod(x,d) takes the product along d'th dimension only, returning
   an array of rank one less than rank(x).
   If x is scalar, it is returned as such.
   If I is integer array, prod(I) will be of type real if the product
   would cause integer overflow. In all other cases, including prod(I,d),
   the type of y equals the component type of x.
See also: sum, cumprod.
   Error codes:
   -1: Nonnumeric input arg
   -2: Second argument not an integer
   -3: Second argument (dimension spec) out of range 

2.83 putenv

[] = putenv(varname,value)
 putenv("varname","value") sets an environment variable.
   The environment variables are inherited to Unix system programs
   invoked with system() and run(), as well as new PlotMTV windows.
   For example:
   putenv("MTV_PSFONT1","32");  // set large font
   plot(x,y,"toplabel","Large");
See also: getenv.
   Error codes:
   -1: First argument not a string
   -2: Second argument not a string
   -3: First argument an empty string
   -4: Environment variable name may not contain the '=' character
   -5: Environment variable value may not contain the '=' character
   1: System call failed to set environment variable

2.84 quit

[] = quit(;rv)
 quit() stops Tela, returning zero (success) exit code
   to the calling process.

   quit(n) returns exit code n instead of zero.
   n must be an int scalar.

   Function quit is a synonym for exit.
See also: error.
Error codes:
    1: expecting integer scalar for EXIT_CODE (arg 1).

2.85 rand

[x] = rand(...)
 rand() returns a uniformly distributed random real x, 0<=x<1.
   rand(N) (N positive integer) returns a real random vector of length N.
   rand(N,M) returns a random matrix, and so on.
See also: srand, gaussrand.
   Error codes:
   -1: Tried to create too high rank array
   -2: Argument not an integer
   -3: Non-positive integer argument 

2.86 rank

[y] = rank(x)
 rank(A) returns the number of dimensions of array A.
   The rank of a scalar is 0. The rank of a nonnumeric
   object, including undefined value, is -1. The rank function
   never generates an error.
See also: length, size.

2.87 reshape

[B] = reshape(A...)
 reshape(A,n,m,...) returns the data in array A rearranged
   to have dimensionality n x m x ... . The product of the indices
   must equal the length of A.
   reshape(A,#(n,m...)) works also.

   Example: reshape(#(1,2,3,4,5,6), 2,3) returns
       #(1, 2, 3;
             4, 5, 6)  
   Error codes:
   -1: First argument not an array
   -2: Later argument not an integer
   -3: Product of dimensions does not equal the length of first argument
   -4: Number of input arguments exceeds MAXRANK
   -5: Second arg is array but not integer vector
   

2.88 round

[y] = round(x)
 round(x) returns the nearest integer.
   x must be integer or real scalar or array. If it is an array,
   the operation is applied componentwise.
See also: floor, ceil.
   Error codes:
   -1: Complex or nonnumeric input argument 

2.89 run

[output] = run(cmd; input)
 run("cmd","input") runs operating system (Unix) command
   "cmd", using contents of the second argument string as
   standard input. It returns the standard output of "cmd"
   as a string.

   The form run("cmd") may be used if the command does not
   read standard input. The command is executed by /bin/sh.
See also: system.

   Error codes:
   -1: First argument not a string
   -2: Second argument not a string
   -3: Error with temporary file
   -4: Error with internal pipe
   -5: run not supported: OS does not provide unistd.h nor popen()
   7: wait(2) returned error
   -8: pipe(2) returned error
   -9: cannot fork(2) a child process
   

2.90 sec

[y] = sec(x)
 y = sec(x) is the secant function
   sec(x) = 1/cos(x). 

2.91 showcompiled

[] = showcompiled(filename...)
 showcompiled("filename.ct",f1,f2,...) compiles functions
   f1,f2,... to C-tela code, creating "filename.ct".
   If no suffix is given in "filename", the suffix
   ".ct" will be assumed.
   showcompiled(f1,f2,...) displays on standard output.
See also: t2ct.
   Error codes:
   1: One of the args is not a Tela-function
   2: Cannot open output file
   

2.92 sign

[y] = sign(x)
 y = sign(x) returns 1 if x>0, 0 if x==0, and -1 if x<0.
   x must be real. If x is array, the operation is applied componentwise.
See also: HeavisideTheta.
   Error codes:
   -1: Complex or nonnumeric input argument 

2.93 sin

[y] = sin(x)
 y = sin(x) computes the sine function of x.
   If x is complex, the result is complex, otherwise real.
   The argument must be in radians.
   If x is an array, the operation is applied componentwise.

2.94 sinh

[y] = sinh(x)
 y = sinh(x) computes the hyperbolic sine function of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.95 size

[...] = size(x)
 [n,m,...] = size(A) finds out the dimensions of array A.
   The number of n,m... must not exceed rank(A). If rank(A)==0
   (that is, A is scalar), n=size(A) sets 1 to n.
   V = size(A) assigns the dimension vector [n,m,..] to V.
   If A is scalar, V is set to 1, if A is vector, V becomes
   a one-element vector.
See also: length, rank.
   Error codes:
   -1: No output arguments
   -2: Argument has undefined value
   1: More than one output arg but non-array input arg
   2: Too many output args relative to input arg rank 

2.96 smenu

[result] = smenu(title...)
 choice = smenu("title","choice1","choice2",...) displays
   a menu of choices and returns the "choice" string corresponding
   to the number entered by the user.
See also: menu.
   Error codes:
   -1: Less than two input args 

2.97 sort

[y,I] = sort(abs(z));

Then y=z[I] is the wanted result. This method, when applicable,
is most probably faster than supplying a user-defined comparison
function.

sort() is a rewritten function which should be backward compatible
with the old one. In this Tela version the old sort function is
still available under sort_old().
Error codes:
   1: Internal error
   2: Expecting Tela or CTela function in CMP (arg 2)
   3: CMP signature is not b = CMP(x1, x2)

2.98 sort_old

[y;I] = sort_old(x)
 sort_old is the old sort routine. Use it only if you
   encounter problems with sort(), sort_old will be
   removed in a later version. The new sort() function
   accepts a second input argument (user-defined comparison)
   but is otherwise identical in semantics.
   
   sort_old(x) returns array x sorted in ascending order.
   If x is complex, it is sorted by the real parts.
   If x is not an array, it is returned as is.
   [y,I] = sort_old(x) returns also an index vector I such that
   y == x[I].

   To sort with user-defined comparisons, do the following.
   For example, if you want to sort a complex vector z by
   absolute value as Matlab does, first sort a vector of
   absolute values saving the index information:

   [y,I] = sort_old(abs(z));

   Then y=z[I] is the wanted result.

   If x is multidimensional, it is implicitly flattened.
   Use the map function to get around this problem.

2.99 source

[] = source(fn)
 source("file.t") loads the tela code from given file.
See also: source_silent, autosource, load.
   Error codes:
   1: Operation did not succeed
   2: Argument not a string 

2.100 source_silent

[] = source_silent(fn)
 source_silent("file.t") is similar to source("file.t"),
   but it does not complain if e.g. the file does not exist.
See also: source, autosource, load.
   Error codes:
   1: Argument not a string 

2.101 sqrt

[y] = sqrt(x)
 y = sqrt(x) computes the square root of x.
   If x is complex, the result is complex. If x is real or
   integer, but negative, the result is complex (purely
   imaginary). If x is real or integer and non-negative,
   the result is real.
   If x is an array, the operation is applied componentwise.
   If some of the components are negative, all components
   of the result are complex.

2.102 srand

[] = srand(seed)
 srand(seed) seeds the random number generator.
   The same seed will always produce the same random
   number sequence. The argument must be an integer.
See also: rand.
   Error codes:
   1: Argument not an integer 

2.103 str2num

[y] = str2num(s)
 str2num(s) converts a string to a number.
   The string must represent a scalar. If an error
   occurs, str2num returns a void value.
   Error codes:
   1: Argument not a string 

2.104 streq

[y] = streq(s1,s2)
 streq("string1","string2") returns 1 if the argument
   strings are exactly equal and 0 otherwise. If one of
   the args is not a string, the result is also 0.
See also: strstarteq.

2.105 strmat

[x] = strmat(...)
 strmat("string1","string2",...) makes a string matrix
   ouf of individual strings. The strings need not be same length,
   they are padded with zeros (invisible) if they are not.

   Usage example:
   S = strmat("string1","longer_string");
   s = tostring(S[1,:]);
   after which streq(s,"string1") will return true (1).
   The function tostring is needed to get rid of possible
   extra zeros at the end of the string.
   
See also: strmat2, tostring, streq.
   Error codes:
   -1: Argument not a string

2.106 strmat2

[x] = strmat2(str; sep)
 strmat2("string") creates a string matrix from "string"
   interpreting the newline character as row ending marker.
   strmat2("string",sep) uses separator sep instead of
   newline char; sep may be either character or string.
   If sep is a string, any character that is a member of sep
   is taken to be a separator. If the rows have unequal lengths,
   they are padded with zeros.
See also: strmat.
   Error codes:
   -1: First arg not a string
   -2: Second arg not a char or string
   

2.107 strstarteq

[y] = strstarteq(s1,s2)
 strstarteq("string1","string2") returns 1 if the argument
   strings are equal on the first min(length(s1),length(s2))
   characters and 0 otherwise.
   If one of the the args is not a string, the result is also 0.
See also: streq.

2.108 sum

[y] = sum(x;d)
 sum(x) sums all the elements of x, if x is an array.
   The result type is always the same as the component type
   of x. If x is scalar, it is returned as such.
   sum(x,d) sums only along d'th dimension, returning array
   of rank one less than rank(x).
See also: cumsum, prod, map.
   Error codes:
   -1: Nonnumeric input arg
   -2: Second argument not an integer
   -3: Second argument (dimension spec) out of range 

2.109 system

[] = system(s)
 system("string") executes string as an external
   operating system command.
See also: run.
   Error codes:
   1: Argument not a string 

2.110 t2ct

[] = t2ct(fn)
 t2ct("filename.t") translates t-code to ct-code.
   This makes it possible to compile t-files into
   faster code.

   To compile a t-file "fyle.t", do the following:

   (1) Generate "fyle.ct" by t2ct("fyle.t") from Tela.
   You can also do this from the shell prompt or Makefile by

   tela -sbe 't2ct("fyle.t")'

   (use single quotes around the argument but cannot show it here, sorry).
   
   (2) Compile it using

   telakka -c fyle.ct

   from the shell or the Makefile. (From within Tela,
   you can use the system function, or precede the command
   line by "!" in interactive mode.)

   (3) The resulting object file fyle.o can be linked directly
   to Tela on some systems (e.g. Linux using the DLD library):

   link("fyle.o")

   On systems using the DSO library (SGI, Sun ...) you must first
   make a shared object file:

   ld -o fyle.so -shared fyle.o

   The DSO file can now be linked to Tela:

   link("fyle.so")

   (When using the DLD library you can emulate the previous step
   by ld -o fyle.so -r fyle.o, this makes it possible to write machine-
   independent Makefiles using gmake.)

   (3b) If you do not want dynamic linking, or if your system does
   not support it (e.g. UNICOS), you can always link your stuff in
   a new Tela kernel by simply using the telakka command:

   telakka -o newtela fyle.o

   When you start the binary 'newtela' the functions defined in
   fyle.t are available.
   
See also: avoid_constructors, system.
   Error codes:
   1: Operation did not succeed
   2: Argument not a string
   3: Could not open output file
   

2.111 tan

[y] = tan(x)
 y = tan(x) computes the tangent function of x.
   If x is complex, the result is complex, otherwise real.
   The argument must be in radians.
   If x is an array, the operation is applied componentwise.

2.112 tanh

[y] = tanh(x)
 y = tanh(x) computes the hyperbolic tangent function of x.
   If x is complex, the result is complex, otherwise real.
   If x is an array, the operation is applied componentwise.

2.113 telapath

[currentpath; maxelements] = telapath(;newpath)
 telapath() returns the current Tela path as a string.
   telapath(NEWPATH) sets the Tela search path to NEWPATH and returns
   the *old* search path, and the maximum number of elements in the
   search path, MAXELEMENTS.
  

Error Codes:
   -1: expecting string NEWPATH (arg 1)
    1: too many elements in NEWPATH (arg 1); ignoring trailing elements 

2.114 tic

[] = tic()
 tic() marks the CPU time at which it was invoked.
   To measure CPU time, use tic() and toc().
See also: cputime, toc.
   Example:

      a = rand(100,100); tic(); b=inv(a); toc()

  This would measure the CPU time in inverting a 100x100
  random real matrix. See also: toc. 

2.115 toc

[t] = toc()
 toc() gives the CPU seconds used since the last call to tic().
See also: tic, cputime.

2.116 tostring

[y] = tostring(x)
 tostring(x) converts an integer vector to a string.
   Transfer of characters is stopped if zero element
   is encountered.
   tostring(A) where A is geneeral integer array copies
   A and sets the string flag.
   Error codes:
   -1: Argument not an integer array
   

2.117 transpose

[B] = transpose(A; P)
 B = transpose(A) returns a transpose of array A: B[i,j,k...l] = A[l...k,j,i].
   B = transpose(A,P) where P is integer vector transposes the indices according
   to the permutation defined by P.
   For example if A has rank 3, B = transpose(A,[2,1,3]) causes the assignment
   B[j,i,k] = A[i,j,k] to be carried out. B = transpose(A) would in this case
   correspond to B[k,j,i] = A[i,j,k].

   The second argument is meaningful only if rank(A) is greater than 2.
   
   You can abbreviate "transpose(A)" by "A.'".
See also: herm, flip.
   Error codes:
   -1: Permutation argument not integer array
   -2: Permutation argument of bad rank or size
   -3: Permutation argument contains invalid integers 

2.118 unhide

[] = unhide(...)
 hide("sym-name",...) unsets the 'hidden' attribute to
   specified symbols.
See also: whos, hide.
   Error codes:
   1: Argument not a string
   2: Argument does not name a symbol
   

2.119 version

[x] = version()
 version() returns the Tela version number (real) currently
   in use. 

2.120 where

[y] = where(c,a,b)
 where(c,a,b) returns a where c is nonzero and b where c is zero.
   Usually the arguments are arrays, and if they are, they must be
   of similar dimensions.
   Error codes:
   -1: First argument not integer-valued
   -2: Second arg non-numeric
   -3: Second arg is incompatible array
   -4: Third arg non-numeric
   -5: Third arg incompatible array

2.121 whos

[] = whos(;hidden)
 whos() displays names of variables together with their
   types and values, if short. 'Hidden' symbols are not shown.
   whos("hidden") shows also hidden symbols.
See also: hide, unhide.
   Error codes:
   1: Bad argument
   -1: Cannot open pipe to sort
   


Next Previous Contents