section s of routines in global.i

all functions - s

save


    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 3080

SEE ALSO: openb, createb, updateb, get_vars, add_record, get_addrs, jt, jc,
_read, _write, data_align

save3


    view= save3()  


Save the current 3D viewing transformation and lighting.  
Interpreted function, defined at i/pl3d.i   line 233

SEE ALSO: restore3, rot3, mov3, aim3, light3

scalar


    scalar -- get optional scalar parameter  


  
PROTOTYPE  
  x = scalar(xarg, xdef, lt=, le=, gt=, ge=, type=, arg=, fn=);  
  
ARGUMENTS  
  XARG    argument passed to the function.  
  XDEF    default value for the scalar argument (optional, if not  
          specified, then it is guessed that the caller must supply the  
          argument).  
KEYWORDS  
  GE=     to be valid, XARG must be >= GE (optional, only one of GT or GE  
          can be used).  
  GT=     to be valid, XARG must be >  GT (optional, only one of GT or GE  
          can be used).  
  LE=     to be valid, XARG must be <= LE (optional, only one of LT or LE  
          can be used).  
  LT=     to be valid, XARG must be <  LT (optional, only one of LT or LE  
          can be used).  
  TYPE=   data type of the scalar (optional).  
  FN=     function name for error messages (optional string).  
  ARG=    argument name for error messages (optional string).  
  
DESCRIPTION  
  Check XARG and return a scalar value (i.e., either XARG converted to TYPE  
  if it is not void or XDEF otherwise).  If XARG is not within any specified  
  bound or if it is not a scalar or if it is void (e.g., not specified) and  
  there is no default value XDEF, an error message is written out.  
  
EXAMPLE  
  The following function has 2 scalar arguments X and Y, the 1st one is an  
  integer (of type long) which must be specified and be strictly greater  
  than 22 while the 2nd default to .5 and must be in [0., 1.]:  
    func foo(x,y) {  
        x= scalar(x,     gt=22,        type=long,   fn="foo", arg="X");  
        y= scalar(y, .5, ge=0., le=1., type=double, fn="foo", arg="Y");  
        ...  
    }  
  
WARNING  
  There is no checking of consistency of options.  
  
HISTORY: 29 Sept. 1995 by Eric THIEBAUT.  (Modified slightly by DHM)  
   Interpreted function, defined at i/string.i   line 154

sech


    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 614

SEE ALSO: sinh, cosh, tanh, asinh, acosh, atanh

series_n


    series_n(r, s)  


returns the minimum number n of terms required for the geometric  
series  
   1 + r + r^2 + r^3 + ... + r^n = s  
to reach at least the given value s.  An alternate viewpoint is  
that n is the minimum number of terms required to achieve the  
sum s, with a ratio no larger than r.  
Returns 0 if r<1 and s>1/(1-r), or if s<1.  
The routine makes the most sense for r>1 and s substantially  
greater than 1.  The intended use is to determine the minimum  
number of zones required to span a given thickness t with a given  
minimum zone size z, and maximum taper ratio r (assumed >1 here):  
   n= series_n(r, t/z);  
With this n, you have the option of adjusting r or z downwards  
(using series_r or series_s, respectively) to achieve the final  
desired zoning.  
R or S or both may be arrays, as long as they are conformable.  
Interpreted function, defined at i/series.i   line 127

SEE ALSO: drat_start, drat_stop

streplace


    streplace(string_array, start_end, to_string)  


replaces the part(s) START_END of STRING_ARRAY by TO_STRING.  
The leading dimension of START_END must be a multiple of 2,  
while any trailing dimensions must be conformable with the  
dimensions of STRING_ARRAY.  The TO_STRING must be conformable  
with STRING_ARRAY if the leading dimension of START_END is 2.  
An element of START_END may represent "no match" (for example,  
when end 2, then  
TO_STRING must have a leading dimension conformable with n  
(that is, of length either 1 or n).  In this case, streplace  
performs multiple replacements within each string.  In order  
for multiple replacements to be meaningful, the START_END  
must be disjoint and sorted, as returned by strfind or  
strgrep with a repeat count, or by strword.  In other words,  
the first dimension of START_END should be non-decreasing,  
except where end  "Goodbye, world!"  
streplace(s,[0,5,7,7], ["Goodbye","cruel "])  
  -->  "Goodbye, cruel world!"  
streplace(s,[0,5,7,7,12,13], ["Goodbye","cruel ","?"])  
  -->  "Goodbye, cruel world?"  
streplace(s,[0,5,0,-1,12,13], ["Goodbye","cruel ","?"])  
  -->  "Goodbye, world?"  
streplace([s,s],[0,5], ["Goodbye", "Good bye"])  
  -->  ["Goodbye, world!", "Good bye, world!"]  
streplace([s,s],[0,5,7,7], [["Goodbye","cruel "], ["Good bye",""]])  
  -->  ["Goodbye, cruel world!", "Good bye, world!"]  
Builtin function, documented at i0/std.i   line 1858

SEE ALSO: string, strfind, strgrep, strword, strpart

strfind


    strfind(pat, string_array)  
 or strfind(pat, string_array, off)  


finds pattern PAT in STRING_ARRAY.  Optional OFF is an integer  
array conformable with STRING_ARRAY or 0-origin offset(s) within  
the string(s) at which to begin the search(es).  The return value  
is a [start,end] offset pair specifying the beginning and end  
of the first match, or [0,-1] if none, with trailing dimensions  
the same as the dimensions of STRING_ARRAY.  This return value  
is suitable as an input to the strpart or streplace functions.  
The strfind function is the simpler string pattern matcher:  
strfind - just finds a literal pattern (possibly case insensitive)  
strgrep - matches a pattern containing complex regular expressions  
Additionally, the strglob function does filename wildcard matching.  
Keywords:  
n=  (default 1) returns list of first n matches, so leading  
    dimension of result will be 2*n  
case=  (default 1) zero for case-insensitive search  
back=  (default 0) non-zero for backwards search  
        If back!=0 and n>1, the last match is listed as the  
        last start-end pair, so the output pairs still appear  
        in increasing order, and the first few may be 0,-1  
        to indicate no match.  
Examples:  
s = ["one two three", "four five six"]  
strfind("o",s)  -->  [[0,1], [1,2]]  
strfind(" t",s)  -->   [[3,5], [13,-1]]  
strfind(" t",s,n=2)  -->   [[3,5,7,9], [13,-1,13,-1]]  
strfind("e",s,n=2,back=1)  -->   [[11,12,12,13], [0,-1,8,9]]  
Builtin function, documented at i0/std.i   line 1662

SEE ALSO: string, strglob, strgrep, strword, strpart, streplace

strglob


    strglob(pat, string_array)  
 or strglob(pat, string_array, off)  


 test if pattern PAT matches STRING_ARRAY.  Optional OFF is an integer  
 array conformable with STRING_ARRAY or 0-origin offset(s) within  
 the string(s) at which to begin the search(es).  The return value  
 is an int with the same dimensions as STRING_ARRAY, 1 for a match,  
 and 0 for no match.  
 PAT can contain UNIX shell wildcard or "globbing" characters:  
matches any number of characters  
 ?   matches any single character  
 [abcd]  matches any single character in the list, which may  
         contain ranges such as [a-z0-9A-Z]  
 \c  matches the character c (useful for c= a special character)  
     (note that this is "\\c" in a yorick string)  
 The strglob function is mostly intended for matching lists of  
 file names.  Note, in particular, that unlike strfind or strgrep,  
 the entire string must match PAT.  
 Keywords:  
 case=  (default 1) zero for case-insensitive search  
 path=  (default 0) 1 bit set means / must be matched by /  
                    2 bit set means leading . must be matched by .  
 esc=   (default 1) zero means \ is not treated as an escape  
 The underlying compiled routine is based on the BSD fnmatch  
 function, contributed by Guido van Rossum.  
 Examples:  
 return all files in current directory with .pdb extension:  
   d=lsdir("."); d(where(strglob("*.pdb", d)));  
 return all subdirectories of the form "hackNN", case insensitive:  
   d=lsdir(".",1);  
   d(where(strglob("hack[0-9][0-9]", d, case=0)));  
 Builtin function, documented at i0/std.i   line 1622

SEE ALSO: string, strfind, strgrep, strword, strpart, streplace

strgrep


    strgrep(pat, string_array)  
 or strgrep(pat, string_array, off)  


finds pattern PAT in STRING_ARRAY.  Optional OFF is an integer  
array conformable with STRING_ARRAY or 0-origin offset(s) within  
the string(s) at which to begin the search(es).  The return value  
is a [start,end] offset pair specifying the beginning and end  
of the first match, or [0,-1] if none, with trailing dimensions  
the same as the dimensions of STRING_ARRAY.  This return value  
is suitable as an input to the strpart or streplace functions.  
The underlying compiled routine is based on the regexp package  
written by Henry Spencer (copyright University of Toronto 1986),  
slightly modified for yorick.  
PAT is a regular expression, simliar to the UNIX grep utility.  
Every "regular expression" syntax is slightly different; here is  
the syntax supported by strgrep:  
The following characters in PAT have special meanings:  
'[' followed by any sequence of characters followed by ']' is a  
    "range", which matches any single one of those characters  
    '^' first means to match any character NOT one in the sequence  
    '-' in such a sequence indicates a range of characters  
      (e.g.- "[A-Za-z0-9_]" matches any alphanumeric character  
       or underscore, while "[^A-Za-z0-9_]" matches anything else)  
    to include ']' in the sequence, place it first,  
    to include '-' in the sequence, place it first or last  
      (or first after a leading '^' in either case)  
    Note that the following special characters lose their special  
    meanings inside a range.  
'.' matches any single character  
'^' matches the beginning of the string (but no characters)  
'$' matches the end of the string (but no characters)  
    (that is, ^ and $ serve to anchor a search so that it will  
     only find a match at the beginning or end of the string)  
'\' (that is, a single backslash, which can only be entered  
     into a yorick string by a double backslash "\\")  
    followed by any single character eliminates any special  
    meaning for that character, for example "\\." matches  
    period, rather than any single character (its special meaning)  
'(' followed by a regular expression followed by ')' matches the  
    regular expression, creating a sub-pattern, which is a type  
    of atom (see below)  
'|' means "or"; it separates branches in a regular expression  
'*' after an atom matches 0 or more matches of the atom  
'+' after an atom matches 1 or more matches of the atom  
'?' after an atom matches 0 or 1 matches of the atom  
The definitions of "atom", "branch", and "regular expression" are:  
A "regular expression" (which is what PAT is) consists of zero  
or more "branches" separated by '|'; it matches anything that  
matches one of the branches.  
A "branch" consists of zero or more "pieces", concatenated; it  
matches a match for the first followed by a match for the second,  
etc.  
A "piece" is an "atom", optionally followed by '*', '+', or '?';  
it matches the atom, or zero or more repetitions of the atom, as  
specified by the optional suffix.  
Finally, an "atom" is an ordinary single character, or a  
'\'-escaped single character (matching that character), or  
one of the special characters '.', '^', or '$', or a  
[]-delimited range (matching any single character in the range),  
or a sub-pattern enclosed in () (matching the sub-pattern).  
A maximum of nine sub-patterns is allowed in PAT; these are  
numbered 1 through 9, in order of their opening '(' in PAT.  
This recursive definition of regular expressions often leads to  
ambiguities, both subtle and glaring.  Here is Henry Spencer's  
synopsis of how his routines behave:  
-------------------------------------------------------------------  
If a regular expression could match two different parts of the  
input string, it will match the one which begins earliest.  If both  
begin in the same place but match different lengths, or match the  
same length in different ways, life gets messier, as follows.  
In general, the possibilities in a list of branches are considered  
in left-to-right order, the possibilities for `*', `+', and `?' are  
considered longest-first, nested constructs are considered from the  
outermost in, and concatenated constructs are considered leftmost-  
first.  The match that will be chosen is the one that uses the  
earliest possibility in the first choice that has to be made.  If  
there is more than one choice, the next will be made in the same  
manner (earliest possibility) subject to the decision on the first  
choice.  And so forth.  
For example, `(ab|a)b*c' could match `abc' in one of two ways. The  
first choice is between `ab' and `a'; since `ab' is earlier, and  
does lead to a successful overall match, it is chosen. Since the  
`b' is already spoken for, the `b*' must match its last possibility  
-the empty string- since it must respect the earlier choice.  
In the particular case where no `|'s are present and there is only  
one `*', `+', or `?', the net effect is that the longest possible  
match will be chosen.  So `ab*', presented with `xabbbby', will  
match `abbbb'.  Note that if `ab*' is tried against `xabyabbbz', it  
will match `ab' just after `x', due to the begins-earliest rule.  
(In effect, the decision on where to start the match is the first  
choice to be made, hence subsequent choices must respect it even if  
this leads them to less-preferred alternatives.)  
-------------------------------------------------------------------  
When PAT contains parenthesized sub-patterns, strgrep returns  
the [start,end] of the entire match by default, but you can  
also get the [start,end] of any or all of the sub-patterns  
using the sub= keyword (see below).  
If PAT does not contain any regular expression constructs, you  
should use the strfind function instead of strgrep.  The strglob  
function, if appropriate, will also be faster than strgrep.  
Keywords:  
n=  (default 1) returns list of first n matches, so leading  
    dimension of result will be 2*n  
sub=[n1,n2,...] is a list of the sub-pattern [start,end] pairs  
    to be returned.  Thus 0 is the whole PAT, 1 is the first  
    parenthesized sub-pattern, and so on.  The leading  
    dimension of the result will be 2*numberof(sub)*n.  The  
    sequence n1,n2,... must strictly increase: n1 [0,13]  
strgrep("(Hello|Goodbye), *([a-z]*|[A-Z]*)!", s, sub=[1,2])  
  --> [0,5,7,12]  
strgrep("(Hello|Goodbye), *([a-z]*|[A-Z]*)!", s, sub=[0,2])  
  --> [0,13,7,12]  
strgrep("(Hello|Goodbye), *(([A-Z]*)|([a-z]*))!", s, sub=[0,2,3,4])  
  --> [0,13,7,12,13,-1,7,12]  
 Builtin function, documented at i0/std.i   line 1698

SEE ALSO: string, strglob, strfind, strword, strpart, streplace

strlen


    strlen(string_array)  


returns an long array with dimsof(STRING_ARRAY) containing the  
lengths of the strings.  Both string(0) and "" have length 0.  
Builtin function, documented at i0/std.i   line 1378

SEE ALSO: string, strchar, strcase, strpart, strfind, strword

strmatch


    strmatch(string_array, pattern)  
 or strmatch(string_array, pattern, case_fold)  
 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.  
(Consider using strfind directly.)  
Interpreted function, defined at i0/std.i   line 1840

SEE ALSO: string, strfind, strpart, strlen

strpart


    strpart(string_array, m:n)  
 or strpart(string_array, start_end)  
 or strpart, string_array, start_end  


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.  
In the second form, START_END is an array of [start,end] indices.  
A single pair [start,end] is equivalent to the range start+1:end,  
that is, start is the index of the character immediately before  
the substring (which is to say start is the number of characters  
skipped at the beginning of the string).  If endlength, or if the original string  
is string(0), strpart returns string(0); otherwise, if end==start,  
strpart returns "".  
However, the START_END array may have any additional dimensions  
(beyond the leading dimension of length 2) which are conformable  
with the dimensions of the STRING_ARRAY.  The result will be a  
string array with dimensions dimsof(STRING_ARRAY,START_END(1,..)).  
Furthermore, the leading dimension of START_END may have any  
even length, say 2*n, in which case the leading dimension of  
the result will be n.  For example,  
  strpart(a, [s1,e1,s2,e2,s3,e3,s4,e4])  
is equivalent to (or shorthand for)  
  strpart(a(-,..), [[s1,e1],[s2,e2],[s3,e3],[s4,e4]])(1,..)  
In the third form, called a subroutine, strpart operates on  
STRING_ARRAY in place.  In this case START_END must have  
leading dimension of length 2, although it may have trailing  
dimensions as usual.  
Examples:  
strpart("Hello, world!", 4:6) --> "lo,"  
strpart("Hello, world!", [3,6]) --> "lo,"  
  -it may help to think of [start,end] as the 0-origin offset  
   of a "cursor" between the characters of the string  
strpart("Hello, world!", [3,3]) --> ""  
strpart("Hello, world!", [3,2]) --> string(0)  
strpart("Hello, world!", [3,20]) --> string(0)  
strpart("Hello, world!", [3,6,7,9]) --> ["lo,","wo"]  
strpart(["one","two"], [[1,2],[0,1]]) --> ["n","t"]  
strpart(["one","two"], [1,2,0,1]) --> [["n","o"],["w","t"]]  
 Builtin function, documented at i0/std.i   line 1406

SEE ALSO: string, strcase, strlen, strfind, strword

strtok


    strtok(string_array, delim)  
 or strtok(string_array)  
 or strtok(string_array, delim, n)  


strips the first token off of each string in STRING_ARRAY.  
A token is delimited by any of the characters in the string  
DELIM.  If DELIM is blank, nil, or not given, the  
default DELIM 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.  
With yorick-1.6, strtok has been extended to accept multiple  
delimiter sets DELIM for successive words, and a repeat count  
N for the final DELIM set.  The operation is the same as for  
strword, except that the N<=0 special cases are illegal, and  
if DELIM consists of only a single set, N=2 is the default  
rather than N=1.  The dimensions of the return value are thus  
min(2,numberof(DELIM)+N-1)-by-dimsof(STRING_ARRAY).  
Interpreted function, defined at i0/std.i   line 1589

SEE ALSO: string, strword, strmatch, strpart, strlen

strtolower


    strtolower -- convert a string to lower case letters  


  
SYNOPSIS: s2 = strtolower(s)  
  
HISTORY: October 10, 1995 by Eric THIEBAUT.  
  DHM modified for yorick-1.6 23/Jan/05  
  
********** DEPRECATED **************  
  new code should use strcase directly  
  
   Interpreted function, defined at i/string.i   line 95