functions in std.i - s

             save, file, var1, var2, ...  
             restore, file, var1, var2, ...  
 
     saves the variables VAR1, VAR2, etc. in the binary file FILE,  
     or restores them from that file.  
     The VARi may be either non-record or record data in the case that  
     FILE contains records.  
     If one of the VARi does not already exist in FILE, it is created  
     by the save command; after add_record, save adds or stores VARi to  
     the current record.  See add_record for more.  The VARi may be  
     structure definitions (for the save command) to declare data  
     structures for the file.  This is necessary only in the case that  
     a record variable is a pointer -- all of the potential data types  
     of pointees must be known.  No data structures may be declared  
     using the save command after the first record has been added.  
     If no VARi are present, save saves all array variables, and  
     restore restores every non-record variable in the file if there  
     is no current record, and every variable in the current record if  
     there is one.  

builtin function, documented at i0/std.i   line 2178  

             sech(x)  
             csch(x)  
 
     returns the hyperbolic secant (1/cosh) or cosecant (1/sinh) of  
     its argument, without overflowing for large x.  

interpreted function, defined at i0/std.i   line 567  

             set_blocksize, file, blocksize  
 
     sets smallest cache block size for FILE to BLOCKSIZE.  BLOCKSIZE  
     is rounded to the next larger number of the form 4096*2^n if  
     necessary; cache blocks for this file will be multiples of  
     BLOCKSIZE bytes long.  The default BLOCKSIZE is 0x4000 (16 KB).  

builtin function, documented at i0/std.i   line 2328  

             set_filesize, file, filesize  
 
     sets the new family member threshhold for FILE to FILESIZE.  
     Whenever a new record is added (see add_record), if the current file  
     in the FILE family has at least one record and the new record would  
     cause the current file to exceed FILESIZE bytes, a new family  
     member will be created to hold the new record.  
     The default FILESIZE is 0x400000 (4 MB).  

builtin function, documented at i0/std.i   line 2337  

             set_idler, idler_function  
 
     sets the idler function to IDLER_FUNCTION.  Instead of waiting  
     for keyboard input when all its tasks are finished, the interpreter  
     will invoke IDLER_FUNCTION with no arguments.  The idler function  
     is normally invoked only once, so input from the keyboard resumes  
     after one call to the idler.  Of course, an idler is free to call  
     set_idler again before it returns, which will have the effect of  
     calling that function in a loop.  

builtin function, documented at i0/std.i   line 2618  

             set_path, "dir1:dir2:dir3:..."  
          or set_path  
 
     sets the include file search path to the specified list of  
     directories.  The specified directories are searched left to  
     right for include files specified as relative file names in  
     #include directives, or to the include or require functions.  
     If the argument is omitted, restores the default search path,  
     ".:~/Yorick:Y_LAUNCH/include:Y_SITE/include:Y_SITE/contrib",  
     where y_site is the main Yorick directory for this site.  
     The Y_LAUNCH directory is the directory which contains the  
     executable; this directory is omitted if it is the same as  
     Y_SITE.  
     Only the "end user" should ever call set_path, and then only in  
     his or her custom.i file, for the purpose of placing a more  
     elaborate set of personal directories containing Yorick procedures.  
     For example, if someone else maintains Yorick code you use, you  
     might put their ~/Yorick on your include path.  

builtin function, documented at i0/std.i   line 219  

             set_primitives, file, prims  
 
     Return the primitive data types for FILE as an array of 32  
     integers.  Versions for particular machines are defined in  
     prmtyp.i, and can be accessed using functions like  
     sun_primitives or i86_primitives.  See __xdr for a complete  
     list.  The format is:  
     [size, align, order] repeated 6 times for char, short, int,  
       long, float, and double, except that char align is always 1,  
       so result(2) is the structure alignment (see struct_align).  
     [sign_address,  exponent_address, exponent_bits,  
      mantissa_address, mantissa_bits,  
      mantissa_normalization, exponent_bias] repeated twice for  
       float and double.  See the comment at the top of prmtyp.i  
       for an explanation of these fields.  
     the total number of items is thus 3*6+7*2=32.  

interpreted function, defined at i0/std.i   line 2074  

 set_site  
 
  

builtin function, documented at i0/std.i   line 242  

             set_vars, file, names  
          or set_vars, file, nonrec_names, rec_names  
 
     Change the names of the variables in FILE to NAMES.  If the  
     file has record variables, you can use the second form to change  
     the record variable names.  Either of the two lists may be nil  
     to leave those names unchanged, but if either is not nil, it must  
     be a 1D array of strings whose length exactly matches the number  
     of that type of variable actually present in the file.  

builtin function, documented at i0/std.i   line 2363  

             sgi64_primitives, file  
 
     sets FILE primitive data types to be native to 64-bit SGI workstations.  

interpreted function, defined at i0/std.i   line 1995  

             show, f  
          or show, f, pat  
          or show, f, 1  
 
     prints a summary of the variables contained in binary file F.  
     If there are too many variables, use the second form to select  
     only those variables whose first few characters match PAT.  
     In the third form, continues the previous show command where it  
     left off -- this may be necessary for files with large numbers of  
     variables.  
     The variables are printed in alphabetical order down the columns.  
     The print function can be used to obtain other information about F.  

interpreted function, defined at i0/std.i   line 1695  

             sign(x)  
 
     returns algebraic sign of it argument, or closest point on the  
     unit circle for complex x.  Guaranteed that x==sign(x)*abs(x).  
     sign(0)==+1.  

builtin function, documented at i0/std.i   line 638  

             sin(x)  
             cos(x)  
             tan(x)  
 
     returns the sine, cosine, or tangent of its argument,  
     which is in radians.  

builtin function, documented at i0/std.i   line 518  

             sinh(x)  
             cosh(x)  
             tanh(x)  
 
     returns the hyperbolic sine, cosine, or tangent of its argument.  

builtin function, documented at i0/std.i   line 557  

             sizeof(object)  
 
     returns the size of the object in bytes, or 0 for non-array objects.  
     sizeof(structure_definition) returns the number of bytes per instance.  
     sizeof(binary_file) returns the file size in bytes.  

builtin function, documented at i0/std.i   line 385  

             sort(x)  
          or sort(x, which)  
 
     returns an array of longs with dimsof(X) containing index values  
     such that X(sort(X)) is a monotonically increasing array.  X can  
     contain integer, real, or string values.  If X has more than one  
     dimension, WHICH determines the dimension to be sorted.  The  
     default WHICH is 1, corresponding to the first dimension of X.  
     WHICH can be non-positive to count dimensions from the end of X;  
     in particular a WHICH of 0 will sort the final dimension of X.  
     WARNING: The sort function is non-deterministic if some of the  
              values of X are equal, because the Quick Sort algorithm  
	      involves a random selection of a partition element.  
     For information on sorting with multiple keys (and on making  
     sort deterministic), type the following:  
        #include "msort.i"  
        help, msort  

builtin function, documented at i0/std.i   line 998  

             span(start, stop, n)  
          or span(start, stop, n, which)  
 
     returns array of N doubles equally spaced from START to STOP.  
     The START and STOP arguments may themselves be arrays, as long as  
     they are conformable.  In this case, the result will have one  
     dimension of length N in addition to dimsof(START, STOP).  
     By default, the result will be N-by-dimsof(START, STOP), but  
     if WHICH is specified, the new one of length N will be the  
     WHICHth.  WHICH may be non-positive to position the new  
     dimension relative to the end of dimsof(START, STOP); in  
     particular WHICH of 0 produces a result with dimensions  
     dimsof(START, STOP)-by-N.  

builtin function, documented at i0/std.i   line 902  

             spanl(start, stop, n)  
          or spanl(start, stop, n, which)  
 
     similar to the span function, but the result array have N points  
     spaced at equal ratios from START to STOP (that is, equally  
     spaced logarithmically).  See span for discussion of WHICH argument.  
     START and STOP must have the same algebraic sign for this to make  
     any sense.  

interpreted function, defined at i0/std.i   line 918  

             sqrt(x)  
 
     returns the square root of its argument.  

builtin function, documented at i0/std.i   line 605  

 sread  
 
builtin function, documented at i0/std.i   line 1242  

             strlen(string_array)  
 
     returns an long array with dimsof(STRING_ARRAY) containing the  
     lengths of the strings.  The null string (0) is considered to  
     have length 0, just like "".  

builtin function, documented at i0/std.i   line 1095  

             strmatch(string_array, pattern)  
          or strmatch(string_array, pattern, case_fold)  
 
     returns an int array with dimsof(STRING_ARRAY) with 0 where  
     PATTERN was not found in STRING_ARRAY and 1 where it was found.  
     If CASE_FOLD is specified and non-0, the pattern match is  
     insensitive to case, that is, an upper case letter will match  
     the same lower case letter and vice-versa.  

builtin function, documented at i0/std.i   line 1121  

             strpart(string_array, m:n)  
 
      returns another string array with the same dimensions as  
      STRING_ARRAY which consists of characters M through N of  
      the original strings.  M and N are 1-origin indices; if  
      M is omitted, the default is 1; if N is omitted, the default  
      is the end of the string.  If M or N is non-positive, it is  
      interpreted as an index relative to the end of the string,  
      with 0 being the last character, -1 next to last, etc.  
      Finally, the returned string will be shorter than N-M+1  
      characters if the original doesn't have an Mth or Nth  
      character, with "" (note that this is otherwise impossible)  
      if neither an Mth nor an Nth character exists.  A 0  
      is returned for any string which was 0 on input.  

builtin function, documented at i0/std.i   line 1132  

             strtok(string_array, delimiters)  
          or strtok(string_array)  
 
     strips the first token off of each string in STRING_ARRAY.  
     A token is delimited by any of the characters in the string  
     DELIMITERS.  If DELIMITERS is blank, nil, or not given, the  
     default DELIMITERS is " \t\n" (blanks, tabs, or newlines).  
     The result is a string array ts with dimensions  
     2-by-dimsof(STRING_ARRAY); ts(1,) is the first token, and  
     ts(2,) is the remainder of the string (the character which  
     terminated the first token will be in neither of these parts).  
     The ts(2,) part will be 0 (i.e.- the null string) if no more  
     characters remain after ts(1,); the ts(1,) part will be 0 if  
     no token was present.  A STRING_ARRAY element may be 0, in  
     which case (0, 0) is returned for that element.  

builtin function, documented at i0/std.i   line 1103  

             struct_align, file, alignment  
 
     in binary file FILE, align new struct members which are themselves  
     struct instances to begin at a byte address which is a multiple of  
     ALIGNMENT.  (This affects members declared explicitly by add_member,  
     as well as implicitly by save or add_variable.)  If ALIGNMENT is <=0,  
     returns to the default for this machine.  The struct alignment is in  
     addition to the alignment implied by the most restrictively aligned  
     member of the struct.  Most machines want ALIGNMENT of 1.  

builtin function, documented at i0/std.i   line 2509  

             structof(object)  
 
     returns the data type of OBJECT, or nil for non-array OBJECTs.  
     Use typeof(object) to get the ASCII name of a the data type.  

builtin function, documented at i0/std.i   line 329  

             sum(x)  
 
     returns the scalar sum of all elements of its array argument.  

builtin function, documented at i0/std.i   line 730  

             sun3_primitives, file  
 
     sets FILE primitive data types to be native to Sun-2 or Sun-3.  

interpreted function, defined at i0/std.i   line 1971  

             sun_primitives, file  
 
     sets FILE primitive data types to be native to Sun, HP, IBM, etc.  

interpreted function, defined at i0/std.i   line 1963  

 swrite  
 
builtin function, documented at i0/std.i   line 1373  

             symbol_def(func_name)(arglist)  
          or symbol_def(var_name)  
 
     invokes the function FUNC_NAME with the specified ARGLIST,  
     returning the return value.  ARGLIST may be zero or more arguments.  
     In fact, symbol_def("fname")(arg1, arg2, arg3) is equivalent to  
     fname(arg1, arg2, arg3), so that "fname" can be the name of any  
     variable for which the latter syntax is meaningful -- interpreted  
     function, built-in function, or array.  
     Without an argument list, symbol_def("varname") is equivalent to  
     varname, which allows you to get the value of a variable whose name  
     you must compute.  
     DO NOT OVERUSE THIS FUNCTION.  It works around a specific deficiency  
     of the Yorick language -- the lack of pointers to functions -- and  
     should be used for such purposes as hook lists (see openb).  

builtin function, documented at i0/std.i   line 2808  

             symbol_set, var_name, value  
 
     is equivalent to the redefinition  
          varname= value  
     except that var_name="varname" is a string which must be computed.  
     DO NOT OVERUSE THIS FUNCTION.  It works around a specific deficiency  
     of the Yorick language -- the lack of pointers to functions, streams,  
     bookmarks, and other special non-array data types.  

builtin function, documented at i0/std.i   line 2829  

             system, "shell command line"  
 
     Passes the command line string to a shell for execution.  
     If the string is constant, you may use the special syntax:  
         $shell command line  
     (A long command line may be continued by ending the line with \  
     as usual.)  The system function syntax allows Yorick to compute  
     parts of the command line string, while the simple $ escape  
     syntax does not.  In either case, the only way to get output  
     back from such a command is to redirect it to a file, then  
     read the file.  Note that Yorick does not regain control  
     until the subordinate shell finishes.  (Yorick will get control  
     back if the command line backgrounds the job.)  
     WARNING: If Yorick has grown to a large size, this may crash  
     your operating system, since the underlying POSIX fork function  
     first copies all of the running Yorick process before the exec  
     function can start the shell.  See Y_SITE/sysafe.i for a fix.  

builtin function, documented at i0/std.i   line 191