Menu

scScript Sys Package

Sys provides utility and misc functions for scScript. These are essential when you need them, but not important enough for inclusion in the sc package.

Functions:
GetArgs
X = Sys.GetArgs()(IArr, IC, OArr, OC);

(Call with OUT args!!!)		 Returns TotalCount (OutCount<<8 + InCount) of args for caller.
  • Stores array of all in args (for caller) in IArr.
  • Stores count of all in args in IC.
  • Stores array of all out args in OArr. (Elts are out args!)
  • Stores count of all out args in OC.
Print
X = Sys.Print("%ld", V);		 Does C-style printf to *Output* and returns total bytes written.
scScript Ints are LONG, use %ld, %lx, etc. Both %f and %lf will work.
(Sys.Print uses libffi to call into libc... will crash with bad args!)
Error
Sys.Error("Script is unhappy!");		 Exits the script with specified error str or default msg if none.
Does NOT return a value to the script!
User can change the script and recompile/rerun.
Exit
Sys.Exit("Script is done!");		 Exits the script normally with the specified str or default msg.
Does not return a value to the script!
Script exits normally, can be run again.
Abort
Sys.Abort("Script had problem!");		 Exits the script with the specified error str or default msg.
Does not return a value to the script!
Goes directly into low-level debugger, cannot continue!
Debug
X = Sys.Debug(M);		 Prints M to stdout and drops into low-level debugger (raises SIGINT).
User can "Continue" from debugger to resume operation.
Returns int 1 to script.
Pause
X = Sys.Pause(M);		 Prints M to stdout, Pauses the running script.
User can resume execution with M-x script-resume command.
Returns int 1 to script (when resumed).
gc
X = Sys.GC();		 Does a full Mark/Sweep Garbage Collection.
Will return byte-count of freed memory blocks.
GC will also dispose of empty slabs, but does not report that size.
Reverse
X = Sys.Reverse(Val);
X = Sys.Reverse(Val, S);
X = Sys.Reverse(Val, S, E);		 Reverses Str/Arr/Dict Val. Returns reversed Val or 0.
S is optional 0-based Start index and E is optional End (0 means all).
Arr and Dict are reversed in place, but creates and returns new Str!
S is INCLUSIVE, but E is EXCLUSIVE (one past last). NOTE +++
Copy
X = Sys.Copy(Val);
X = Sys.Copy(Val, S);
X = Sys.Copy(Val, S, E);		 Copies and returns a new Str/Arr/Dict Val, returns 0 for other types.
S is optional 0-based Start index and E is optional End (0 means all).
Returned value is the copy, Val itself is unchanged.
S is INCLUSIVE, but E is EXCLUSIVE (one past last). NOTE ***
SeedRand
X = Sys.SeedRand(V);		 Initializes seed for random number generator and returns it.
Use consistent V for most reproducible pseudo-random sequence.
If no V arg or 0, will use time(NULL) OS call and return that value.
Rand
X = Sys.Rand();
X = Sys.Rand(V);
X = Sys.Rand(N, M);		 Returns positive random number generated from seed.
Args, if given, must be positive, all int or all flt.
  • If called with no in arg or with V == 1, returns positive 32-bit int.
  • If called with V == 2, returns positive 64-bit int.
  • If called with flt V arg, returns flt from 0.0 up to 1.0.
  • If called with int N to M, returns int from N to (not including) M.
  • If called with flt N to M, returns flt from N to (not including) M.
Time
T = Sys.Time(Flag)(BRT);		 Returns Int number of seconds since start of Unix epoch.
BRT, if given, will get a new #Type_FExt struct for broken down time.
Optional Flag is Sys.#Zulu (global) or Sys.#Local (default) for BRT.
BRTime
Sys.BRtime(BRT, F1, F2...)(V1, V2);		 Returns Int 1.
Places flagged (F1, F2, etc.) values in corresponding variables (V1, V2, etc.).
Each In flag must have a matching Out var.
Flags range from Sys.#Sec to Sys.#IsDST.
Unlike C, #Year is actual year (not 1900-based) and #Mon is 1 for Jan!
Ticks
Tk = Sys.Ticks();		 Returns clock (processor) ticks (Int) since re-boot.
(This system value rolls over quite often as up to 1E7 tks/sec!)
Secs
X = Sys.Secs(Tk);		 Returns elapsed time in secs (Flt) using T (time Ticks) since event.
(Tk is usually TKEnd - TKStart)

Defs:
Time flags #Zulu, #Local
BRTime flags #Type_Unknown, #Type_Int, #Type_Flt, #Type_Str, #Type_Arr, #Type_Dict,
#Sec, #Min, #Hour, #MDay (day of month), #Mon, #Year,
#WDay (day of week), #YDay (day of year), #IsDST (Daylight Savings)

+++ Sys.Reverse will return Int 0 for all Val types other than Str/Arr/Dict. It will return the original Str/Arr/Dict (or Int 0) if S and E specify a non-existent range (E is trimmed to size if too large).

Note:   Sys.Reverse will alter Arrays and Dicts in place, but strings are immutable, so only the return string is reversed!

Given A = Array(); A[0] = "Zero"; A[1] = "One"; will create an array with 2 strings at index 0 and 1, plus 6 empty slots at index 2 to 7. Therefore Sys.Reverse on this array (without S and E args) will yield an array with 6 empty initial slots, "One" in A[6], and "Zero" in A[7]. But Sys.Reverse(A, 0, 1) can be used to reverse the two initial (populated) slots. (B = ["Zero", "One"]; does not have this problem, as B will only have 2 slots.)

Sys.Reverse will reverse pair order in dicts. This will only manifest in MapK (not even MapI) iteration order as normal Dict.Key access (and hash array indexing) is independent of pair ordering. But Sys.Reverse(MyArr) will actually change MyArr[I] access, because Reverse will re-arrange array contents. Worse, as noted above, Sys.Reverse(MyStr) appears to do nothing! Strings are immutable and cannot be changed in place. So NewStr = Sys.Reverse(MyStr); is required to get a reversed string.

S and E refer to the nth (0-based) array elt and pair dict. In the case of strings, they indicate the nth character, not the nth byte, as a string can have multi-byte UTF-8 characters.

*** Sys.Copy will only work on Str/Arr/Dict and will return Int 0 for all other types. It will also return Int 0 if S and E specify a non-existent range. A copy of the full string is the full string itself, the system will not allow copies of the same exact string.