functions in utils.i -

 __strlower  
 

 __strupper  
 

 __swap  
 

 __unref  
 

             __xopen_get_compress(compress, filename, for_reading)  
 
     Private function called by xopen.  

             is_integer(x)  
 
     returns true if array X if of integer type.  

             is_integer(x)  
 
     returns true if array X if of integer type.  

             is_integer_scalar(x)  
 
     Check whether or not X is an integer scalar.  

             is_matrix(x)  
 
     returns true if array X is a matrix (i.e. a 2D array).  

             is_numerical(x)  
 
     returns true if array X if of numerical type.  

             is_real(x)  
 
     returns true if array X if of real type (i.e. double or float).  

             is_scalar(x)  
 
     returns true if X is a scalar.  

             is_vector(x)  
 
     returns true if array X is a vector (i.e. a 1D array).  

 _protect_file_name_list  
 

             protect_file_name(path)  
 
     Protect special characters in PATH (apostrophes, quotes, $, *, ?, [,  
     etc) by backslashes to avoid them being interpreted by the shell, for  
     instance when using the system() builtin function.  

             _stat_worker(x)  
 
     Private routine used by stat, returns vector of double's:  
        [min(X), max(X), avg(X), std(X)]  
     where std(X) is the standard deviation of X.  

             local _strlower, _strupper;  
 
     Private arrays to convert char to upper/lowercase letters.  

 _strupper  
 

             dump_text, file, text;  
 
     Dump every  elements of string array  TEXT as individual  lines into a  
     text file.  FILE can be a file name or a text stream.  
     If the file is specified by  its name, keywords COMPRESS, LEVEL can be  
     used to specify  a compression method (see xopen).   The default value  
     of COMPRESS is  "auto" (i.e., method guessed on the  basis of the file  
     extension).  
     If the file  is specified by its name, keyword PRESERVE  can be set to  
     true to avoid overwriting an existing file.  
       

             eval, code;  
 
       -or- eval(code);         
     Evaluates CODE given as a string or as an array of strings (considered  
     as  different lines  in the  script).  Since  CODE can  be dynamically  
     build,   this  routine   allows  the   execution  of   virtually  (see  
     hints/restrictions below)  any Yorick's code  (e.g. dynamic definition  
     of  structures,  of functions,  etc.).   For  instance, the  following  
     statement defines a new structure:  
       eval, "struct NewStruct {string a; long b; float c, d;}";  
     Since  the script  gets evaluated  at the  scope level  of  the "eval"  
     routine some local variables of the  "eval" routine may be used in the  
     script:  
       "eval_tmp"    contains  the  name of  the temporary script  file and  
                     must not be changed by the script;  
       "eval_debug"  contains the value of  the keyword DEBUG and  must not  
                     be changed by the script;  
       "eval_code"   contains the value of the argument CODE;  
       "eval_result" is  returned by  "eval", its  contents may  be defined  
                     into the script to provide a returned value.  
     Note: impredictible  results may  occur if CODE  changes the  value of  
     symbols "eval_tmp" and "eval_debug".  
     Keyword TMP  can be  used to  specify the file  name of  the temporary  
     script.  The default file name is:  
       "$YORICK_EVAL_TMP"      if environment variable "YORICK_EVAL_TMP" is  
                               set;  
       "/tmp/$USER-eval_tmp.i" if environment variable "USER" set;  
       "~/.eval_tmp.i"         otherwise.  
     If  keyword DEBUG  is true  (non-zero and  non-nil), the  name  of the  
     temporary file is printed out and the file is not removed.  

             expand_file_name(path)  
 
     Expand leading "~" in file name PATH which must be an array of  
     strings (or a scalar string).  

             get_file_name(obj)  
 
     If OBJ is a stream, returns the path name of the file associated with  
     the stream.  Otherwise if OBJ is an array of strings, expand leading  
     "~" in the elements of OBJ.  
       

             grow_dimlist, dimlist, next_argument  
 
     builds a dimension  list DIMLIST, as used in  the array function.  Use  
     like  this (all  extra arguments  in your  function are  considered as  
     dimensions or dimension lists):  
       func your_function(arg1, arg2, etc, ..)  
       {  
         dimlist = [0];  
         while (more_args()) grow_dimlist, dimlist, next_arg();  
         ...  
       }  
     After    this,   DIMLIST   will    be   an    array   of    the   form  
     [ndims, dim1, dim2,...], compounded from the multiple arguments in the  
     same way as the array function.  Another possibility is to define your  
     function as:  
       func your_function(arg1, arg2, etc, dimlist, ..)  
       {  
         while (more_args()) grow_dimlist, dimlist, next_arg();  
         ...  
       }  
     But in this  latter case, if no DIMLIST  arguments given, DIMLIST will  
     be [] instead of [0], which  will act the same in most situations.  If  
     that possibility is unacceptible, you may add  
       if (is_void(dimlist)) dimlist= [0];  
     before/after the while loop.  

             guess_compression, filename;  
 
       -or- guess_compression(filename)    
     Guess  which compression  program was  used to  produce  file FILENAME  
     according to first  bytes of this file.  When  called as a subroutine,  
     the file name is printed out  with the name of the compression program  
     if any.  If called as a function, the result is an integer:  
       1 - if file compressed with "gzip";  
       2 - if file compressed with "bzip2";  
       3 - if file compressed with "compress";  
       4 - if file compressed with "pack";  
       0 - otherwise.  

             load_text(file)  
 
     Returns all lines of text file as a vector of strings.  Returns nil if  
     there are no lines to read.  FILE can be a file name or a text stream.  
     In the latter case, the lines not yet read get returned.  
     By  default,  if  the file  is  specified  by  its  name, it  will  be  
     automatically decompressed if its  compressed; it is possible to force  
     another  behaviour by  specifying a  value different  from  "auto" for  
     keyword COMPRESS (see xopen).  
       

             map(f, input)  
 
     Map scalar function F onto array/list argument INPUT to mimics  
     element-wise unary operation.  

             pdb_list, file;  
 
       -or- pdb_list(file)  
     Lists contents of PDB binary file.  FILE can be either a file name or  
     a binary stream.  
       

             pdb_restore_all, file;  
 
     Restore all non-record variables of a PDB file.  FILE can be either a  
     file name or a binary stream.   
       

 protect_file_name  
 

             pwd  
 
       -or- pwd()  
     Prints out (subroutine form) or returns (function form) full path  
     of current working directory.  

             read_ascii(file_or_name)  
 
     Reads ascii numeric  data in columns from text  file.  FILE_OR_NAME is  
     the name of the  file or an already open file stream.  The result is a  
     NCOLUMNS-by-NLINES array of doubles.  
     Data are  read as double values  arranged in columns  separated by any  
     number of  spaces or tabs.  Comments  starting with a "#"  or an FILEy  
     other character  which is not part of  a number are ignored  up to the  
     end-of-line.  Blank lines  are ignored.  The first non-blank/commented  
     line  gives the  number of  values per  column, for  subsequent lines.  
     Subsequent lines  must have  the same number  of columns --  blanks in  
     columns are  not permitted, use  0.0 instead.  However,  minimal error  
     checking  is performed,  and if  the data  is not  really  in columns,  
     read_ascii  can silently  fail to  interpret  your file  as you  would  
     scanning it by eye.  
       
     The  read operation will  be much  faster if  the number  of commented  
     lines is  relatively small.   Blank lines cost  nothing, while  a line  
     containing just a "#" is expensive.  
     If the  file is specified by its  name, it may be  compressed in which  
     case it get automatically decompressed while reading (see xopen).  

             reform(x, dimlist, ...);  
 
       -or- reform(x);  
     returns array X reshaped according to dimension list DIMLIST.  Without  
     DIMLIST, discards all dimensions equal to 1.  In most cases, prefer  
     this to reshape.  

             smooth(a)  
 
       -or- smooth(a, level)  
     Returns array A smoothed along its dimensions.  I.e. for a 1D array:  
       smooth(A) = A(pcen)(zcen)  
     for a 2D array:  
       smooth(A) = A(pcen,pcen)(zcen,zcen)  
     ... (up to 6 dimensions).  
     For a greater number of dimensions,  each  direction  is  smoothed and  
     transposed in turn: apart from rounding errors, the result is the same  
     but the computation time is approximately  multiplied  by  3.   If you  
     oftenly smooth arrays with more than 6 dimensions you may  think about  
     modifying the source...  
     Optional argument  LEVEL  (default  1)  set  the  number  of  time the  
     smoothing operation is performed.  
   PROPERTIES OF THE SMOOTHING OPERATOR:  
     (i)   The smoothing operator is linear and symmetric.  For instance,  
           for a vector, A, smooth(A)=S(,+)*A(+) where the matrix S is  
           tridiagonal:  
                    [3 1         ]  
                    [1 2 1       ]  
                    [  1 2 1     ]  
             0.25 * [   \ \ \    ]    where, to improve readability,  
                    [    \ \ \   ]    missing values are all zero.  
                    [     1 2 1  ]  
                    [       1 2 1]  
                    [         1 3]  
           You can, in principle, reverse the smoothing operation with  
           TDsolve along each dimensions of smooth(A).  Note:For a vector  
           A, the operator S-I applied to A (where I is the identity  
           matrix) is the finite difference 2nd derivatives of A (but for  
           the edges).  
     (ii)  The smoothing operator does not change the sum of the element  
           values of its argument, i.e.: sum(smooth(A)) = sum(A).  
     (iii) Only an array with all elements having the same value is  
           invariant by the smoothing operator.  In fact "slopes" along  
           dimensions of A are almost invariant, only the values along the  
           edges are changed.  
     The symmetry of the smoothing operator is important for the  
     computation of gradients.  For instance, let Y = smooth(X) and DQ_DY  
     be the gradient of a scalar function Q with respect to Y, then the  
     gradient of Q with respect to X is simply: DQ_DX = smooth(DQ_DY)  
   TO DO:  
     By default A is smoothed along all its dimensions, but the list  
     of dimensions to smooth can be specified with keyword WHICH.  As  
     usual, negative dimensions are taken as offset from the last one.  
     If keyword WRAP is true (non-nil and non-zero) a wrapped version  
     of the operator (with same properties but no longer tridiagonal)  
     is applied instead.  This is suitable for periodic arrays (e.g.  
     FFT transformed arrays).  

             spline_zoom(a, fact)  
 
     Return an array obtained by cubic spline interpolation of A with all  
     its dimension multiplied by a factor FACT.  If keyword RGB is true the  
     first dimsion of A is left unchanged.  If keyword RGB is not  
     specified, then it is considered as true if A is a 3 dimensional array  
     of 'char' with its first dimension equal to 3.  
       

             stat, x, ...  
 
     Print out statistics and information for all the arguments. */  

             strcut(str, len)  
 
     Cut input scalar string STR in pieces of length less or equal LEN and  
     return an array of such pieces.  

             strjoin(str)  
 
       -or- strjoin(str, glue)  
     Join strings from array STR into a single long string.  The string GLUE  
     (default "") is used between each pair of element from STR.  

             strlower(s)  
 
       -or- strtolower(s)  
     Convert a string or an array of strings S to lower case letters.  

 strtolower  
 

 strtoupper  
 

             strupper(s)  
 
       -or- strtoupper(s)  
     Convert a string or an array of strings S to upper case letters.  

             swap, a, b;  
 
     Exchanges  the contents  of variables  A and  B without  requiring any  
     temporary copy.  

             timer_start;  
 
       -or- timer_elapsed;  
       -or- timer_elapsed, count;  
       -or- timer_elapsed()  
       -or- timer_elapsed(count)  
     The  subroutine  timer_start (re)starts  the  timer  and the  function  
     timer_elapsed   computes  the   elapsed  time   since  last   call  to  
     timer_start.  If COUNT is given, the elapsed time is divided by COUNT.  
     When  called as  a subroutine,  timer_elapsed prints  out  the elapsed  
     time; when  called as a  function, it returns  [CPU,SYSTEM,WALL], with  
     all three  times measured in seconds.   The two functions  make use of  
     external variable _timer_stamp to memorize the initiale times.  
     For instance:  
       timer_start;  
       ...             // some code to be profiled  
       timer_elapsed;  
       ...             // some more code to be profiled  
       timer_elapsed;  // prints out _total_ elapsed time  

             undersample(a, nsub)  
 
     Returns  array A  with all  (some)  dimensions divided  by NSUB.   The  
     dimensions of interest must be a multiple of NSUB.  
     Keyword  WHICH can  be used  to  specify the  dimension(s) to  shrink.  
     Values  in  WHICH  less  or  equal  zero are  counted  from  the  last  
     dimension.  By default, all dimensions of A get undersampled.  
     Keyword OP can  be used to specify the range operator  to apply to the  
     sets of NSUB adjacent values along the considered dimensions:  
       OP=sum   to sum the values  
       OP=avg   to average values  
       OP=min   to keep the smallest value  
       OP=max   to keep the largest value  
     By default,  the median is  taken (WARNING: with the  median operator,  
     the result depends in which order the dimensions of A are considered).  

             unref(x)  
 
     returns X, destroying X in the process (useful to deal with temporary  
     big arrays).  Written after Yorick's FAQ.  

             xopen(filename)  
 
       -or- xopen(filename, filemode)  
     Opens the file FILENAME according to FILEMODE (both are strings).  The  
     return value is an IOStream (or just stream for short).  When the last  
     reference to this return value is discarded, the file will be closed.  
     The file can also be  explicitly closed with the close function (which  
     see).  The  FILEMODE (default  "r" -- open  an existing text  file for  
     reading) determines whether  the file is to be  opened in read, write,  
     or update mode,  and whether writes are restricted  to the end-of-file  
     (append mode).  FILEMODE also determines whether the file is opened as  
     a text  file or  as a  binary file.  FILEMODE  can have  the following  
     values, which are the same as for the ANSI standard fopen function:  
         "r"   - read only  
         "w"   - write only, random access, existing file overwritten  
         "a"   - write only, forced to end-of-file, existing file preserved  
         "r+"  - read/write, random access, existing file preserved  
         "w+"  - read/write, random access, existing file overwritten  
         "a+"  - read/write, reads random access, writes forced to  
                 end-of-file, existing file preserved  
         "rb"  "wb"  "ab"  "r+b"  "rb+"  "w+b"  "wb+"  "a+b"  "ab+"  
                 without b means text file, with b means binary file  
       
     Keyword COMPRESS can be used  to specify compression method for a text  
     file open for reading (FILEMODE="r") or writing (FILEMODE="w") only --  
     (de)compression  is unsupported in  append mode  or for  binary files.  
     The value of keyword COMPRESS can be a scalar string or an integer:  
          "auto"     - guess compression according to first bytes of file  
                       in read  mode, or according to file extension in   
                       write mode: ".gz" for gzip, ".bz2" for bzip2 and  
                       ".Z" for compress.  
       0  "none"     - no (de)compression  
       1  "gzip"     - use gzip to (de)compress  
       2  "bzip2"    - use bzip2 to (de)compress  
       3  "compress" - use compress to (de)compress  
       4  "pack"     - use pack to (de)compress  
     The default  value for COMPRESS is  "auto" in read mode  and "none" in  
     write mode.  Note that "gzip", "bzip2", "pack" and "compress" commands  
     must  exists in  your  $PATH for  compressing  with the  corresponding  
     methods.  Decompression of files compressed with "pack" and "compress"  
     is  done  by  "gzip".   If  keyword  COMPRESS  is  explicitely  0,  no  
     decompression  is ever  applied;  if keyword  COMPRESS is  explicitely  
     non-zero, the  file must have been compressed.   The compression level  
     for gzip  and bzip2  can be  specified as an  integer value  thanks to  
     keyword LEVEL.  
         
     Keyword PRIMS  can be used  to specify primitives data  type different  
     than  the native  ones for  binary files  (PRIMS is  ignored  for text  
     files).  PRIMS can  be a scalar string (i.e.,  "alpha", "mac", "sun3",  
     "cray", "macl", "sun", "dec",  "pc", "vax", "vaxg", "i86", "sgi64", or  
     "xdr") or  a 32-element  vector of long's  as taken  by set_primitives  
     (which see).  
     When a binary file is created, it is possible to avoid the creation of  
     the log-file FILENAME+"L" by setting keyword NOLOG to true.  
     Keyword PRESERVE can  be set to true to  avoid overwriting an existing  
     file when FILENAME is open for writing (i.e. with a "w" in FILEMODE).  
       
   BUGS:  
     If (de)compression is used, FILENAME must not contain any double quote  
     character (").