section r of routines in std.i

Home Manual Packages Global Index Keywords Quick Reference | # functions in std.i - r
random |
                 random(dimension_list)
                 random_seed, seed

         returns an array of random double values with the given
         DIMENSION_LIST (nil for a scalar result), uniformly distributed
         on the interval from 0.0 to 1.0.
         The algorithm is from Press and Teukolsky, Computers in Physics,
         vol. 6, no. 5, Sep/Oct 1992 (ran2).  They offer a reward of $1000
         to anyone who can exhibit a statistical test that this random
         number generator fails in a "non-trivial" way.
         The random_seed call reinitializes the random number sequence;
         SEED should be between 0.0 and 1.0 non-inclusive; if SEED is
         omitted, nil, or out of range, the sequence is reinitialized as
         when Yorick starts.
         The numbers are actually at the centers of 2147483562 equal width
         bins on the interval [0,1].  Although only these 2 billion numbers
         are possible, the period of the generator is roughly 2.3e18.

    builtin function, documented at i0/std.i   line 667
SEE ALSO: | randomize
random_seed |
     random_seed

    builtin function, documented at i0/std.i   line 667
SEE | random
randomize |
                 randomize
                 randomize()

         set the seed for random "randomly" (based on the timer clock
         and the current state of random).  As a function, returns the
         value of the seed passed to random_seed.

    interpreted function, defined at i0/std.i   line 689
SEE ALSO: | random, random_seed
rdline |
                 rdline(f)
              or rdline(f, n, prompt= pstring)

         returns next line from stream F (stdin if F nil).  If N is non-nil,
         returns a string array containing the next N lines of F.  If
         end-of-file occurs, rdline returns nil strings.  If F is nil,
         uses the PSTRING to prompt for input (default "read> ").

    builtin function, documented at i0/std.i   line 1348
SEE ALSO: | read, open, close, bookmark, backup, read_n
re_part |
                 re_part(z)

         returns the real part of its argument.  (Same as double(z).)
         Unlike z.re, works if z is not complex.

    keyword,  defined at i0/std.i   line 651
read |
                 n= read(f, format=fstring, obj1, obj2, ...)
              or n= read(prompt= pstring, format=fstring, obj1, obj2, ...)
     	 or n= sread(source, format=fstring, obj1, obj2, ...)

         reads text from I/O stream F (1st form), or from the keyboard (2nd
         form), or from the string or string array SOURCE (3rd form),
         interprets it according to the optional FSTRING, and uses that
         interpretation to assign values to OBJ1, OBJ2, ...  If the input
         is taken from the keyboard, the optional prompt PSTRING (default
         "read> ") is printed before each line is read.  The Yorick write
         function does not interact with the read function -- writes are
         always to end-of-file, and do not affect the sequence of lines
         returned by read.  The backup (and bookmark) function is the
         only way to change the sequence of lines returned by read.
         There must be one non-supressed conversion specifier (see below)
         in FSTRING for each OBJ to be read; the type of the conversion
         specifier must generally match the type of the OBJ.  That is,
         an integer OBJ requires an integer specifier (d, i, o, u, or x)
         in FSTRING, a real OBJ requires a real specifier (e, f, or g),
         and a string OBJ requires a string specifier (s or []).  An OBJ
         may not be complex, a pointer, a structure instance, or any non-
         array Yorick object.  If FSTRING is not supplied, or if it has
         fewer conversion specifiers than the number of OBJ arguments,
         then Yorick supplies default specifiers ("%ld" for integers,
         "%lg" for reals, and "%s" for strings).  If FSTRING contains more
         specifiers than there are OBJ arguments, the part of FSTRING
         beginning with the first specifier with no OBJ is ignored.
         The OBJ may be scalar or arrays, but the dimensions of every OBJ
         must be identical.  If the OBJ are arrays, Yorick behaves as
         if the read were called in a loop numberof(OBJ1) times, filling
         one array element of each of the OBJ according to FSTRING on
         each pass through the loop.  (Note that this behavior includes
         the case of reading columns of numbers by a single call to read.)
         The return value N is the total number of scalar assignments
         which were made as a result of this call.  (If there were 4
         OBJ arguments, and each was an array with 17 elements, a return
         value of N==35 would mean the following:  The first 8 elements
         of OBJ1, OBJ2, OBJ3, and OBJ4 were read, and the 9th element of
         OBJ1, OBJ2, and OBJ3 was read.)  The read function sets any
         elements of the OBJ which were not read to zero -- hence,
         independent of the returned N, the all of the old data in the
         OBJ arguments is overwritten.
         The read or sread functions continue reading until either:
         (1) all elements of all OBJ have been filled, or (2) end-of-file
         (or end of SOURCE for sread) is reached ("input failure"), or
         (3) part of FSTRING or a conversion specifier supplied by
         default fails to match the source text ("matching failure").
         The FSTRING is composed of a series of "directives" which are
         (1) whitespace -- means to skip any amount of whitespace in the
             source text
         (2) characters other than whitespace and % -- must match the
             characters in the source text exactly, or matching failure
    	 occurs and the read operation stops
         (3) conversion specifiers beginning with % and ending with a
             character specifying the type of conversion -- optionally
    	 skip whitespace, then convert as many characters as
    	 continue to "look like" the conversion type, possibly
    	 producing a matching failure
         The conversion specifier is of the form %*WSC, where:
      is either the character '*' or not present
           A specifier beginning with %* does not correspond to any of
           the OBJ; the converted value will be discarded.
         W is either a positive decimal integer specifying the maximum
           field width (not including any skipped leading whitespace),
           or not present if any number of characters up to end-of-line
           is acceptable.
         S is either one of the characters 'h', 'l', or 'L', or not
           present.  Yorick allows this for compatibility with the C
           library functions, but ignores it.
         C is a character specifying the type of conversion:
           d   - decimal integer
           i   - decimal, octal (leading 0), or hex (leading 0x) integer
           o   - octal integer
           u   - unsigned decimal integer (same as d for Yorick)
           x, X            - hex integer
           e, f, g, E, G   - floating point real
           s   - string of non-whitespace characters
           [xxx]   - (xxx is any sequence of characters) longest string
                     of characters matching those in the list
           [^xxx]  - longest string of characters NOT matching those in
                     the list (this is how you can extend %s to be
    		 delimited by something other than whitespace)
           %   - the ordinary % character; complete conversion
                 specification must be "%%"
         The read function is modeled on the ANSI standard C library
         fscanf and sscanf functions, but differs in several respects:
           (1) Yorick's read cannot handle the %c, %p, or %n conversion
               specifiers in FSTRING.
           (2) Yorick's read never results in a portion of a line
               being read -- any unused part of a line is simply discarded
    	   (end FSTRING with "%[^\n]" if you want to save the trailing
    	   part of an input line).
           (3) As a side effect of (2), there are some differences between
               fscanf and Yorick's read in how whitespace extending across
    	   newlines is handled.

    builtin function, documented at i0/std.i   line 1242
SEE ALSO: | rdline, write, open, close, bookmark, backup, save, restore, read_n
read_clog |
                 file= read_clog(file, clog_name)

         raw routine to set the binary data structure of FILE according
         to the text description in the Contents Log file CLOG_NAME.

    builtin function, documented at i0/std.i   line 1747
read_n |
                 read_n, f, n0, n1, n2, ...

         grabs the next numbers N0, N1, N2, ... from file F, skipping over
         any whitespace, comma, semicolon, or colon delimited tokens which
         are not numbers.  (Actually, only the first and last characters of
         the token have to look like a number -- 4xxx3 would be read as 4.)
         ***WARNING*** at most ten Ns are allowed
         The Ns can be arrays, provided all have the same dimensions.

    interpreted function, defined at i0/std.i   line 1358
SEE ALSO: | read, rdline
recover_file |
                 recover_file, filename
              or recover_file, filename, clogfile

         writes the descriptive information at the end of a corrupted
         binary file FILENAME from its Contents Log file CLOGFILE, which
         is FILENAME+"L" by default.

    interpreted function, defined at i0/std.i   line 1753
remove |
     remove

    builtin function, documented at i0/std.i   line 1234
SEE | rename
rename |
                 rename, old_filename, new_filename
                 remove filename

         rename or remove a file.

    builtin function, documented at i0/std.i   line 1234
SEE ALSO: | open, close, openb
require |
     require

    builtin function, documented at i0/std.i   line 1483
SEE | include
reshape |
                 reshape, reference, address, type, dimension_list
              or reshape, reference, type, dimension_list
              or reshape, reference

         The REFERENCE must be an unadorned variable, not an expression;
         reshape sets this variable to an LValue at the specified ADDRESS
         with the specified TYPE and DIMENSION_LIST.  (See the array
         function documentation for acceptable DIMENSION_LIST formats.)
         If ADDRESS is an integer (e.g.- a long), the programmer is
         responsible for assuring that the data at ADDRESS is valid.
         If ADDRESS is a (Yorick) pointer, Yorick will assure that the
         data pointed to will not be discarded, and the reshape will
         fail if TYPE and DIMENSION_LIST extend beyond the pointee
         bounds.  In the second form, ADDRESS is taken to be &REFERENCE;
         that is, the TYPE and DIMENSION_LIST of the variable are changed
         without doing any type conversion.  In the third form, REFERENCE
         is set to nil ([]).  (Simple redefinition will not work on a
         variable defined using reshape.)
         WARNING: There are almost no situations for which reshape is
           the correct operation.  See reform in Y_SITE/i/string.i.

    builtin function, documented at i0/std.i   line 264
SEE ALSO: | array, dimsof, numberof, is_array, eq_nocopy
restore |
     restore

    builtin function, documented at i0/std.i   line 2178
SEE | save
rmdir |
     rmdir

    builtin function, documented at i0/std.i   line 1571
SEE | mkdir