scScript Str Package

Strings in scScript are immutable, they are all hashed and centrally stashed. Each unique string is stored only once and all copies are the exact same string. The str package provides functions to handle these strings.

Functions:
Print S = Str.Print("%ld\n", Val)(L);	Does C-style printf to a new Str and returns it. First out arg, if given, will get the StrLen (bytes). scScript Ints are LONG, use %ld, %lx, etc. Both %f and %lf will work. (Str.Print uses libffi to call into libc... may crash if bad args!)
Write S = Str.Write(U, V, W...)(L);	Writes out concatenation of all in args to a new Str and returns it. First out arg, if given, will get the StrLen (bytes). Write accepts any valid value, turns it into a descriptive string!
Writeln S = Str.Writeln(U, V, W...)(L);	Same as Str.Write, but adds an extra \n at the end.
ReadN E = Str.ReadN(S, B, F)(N);	Reads number N (Int or Flt) from str S at byte pos B (0-based). Returns E (EndPos of N) if successful, or 0. Can read +/-, Decimal, Octal, and Hex. Can read Flt in regular or exponential form (Decimal/Hex only). F defaults to #Sep, use #NoSep to read without separators. Note: ***
Form S = Str.Form(U, V, W...)(L); S = Str.Form(U, N, V, W...)(L);	Form and return a Str from multiple copies of arg strings. In args can be numbers and strings, nothing else. Each N means concatenate N copies of each subsequent string. New N resets for next strings. First out arg, if given, will get StrLen (bytes).
FTime S = Str.FTime(FStr, T, F)(L);	Creates and returns the formatted time string (like strftime in C). FStr if given, specs the format, defaults to "%x %X" Date+Time. T, if given, specifies the time (ticks), defaults to now! F, if given, specifies #Zulu or #Local (default) time. First out arg, if given, will get the StrLen (bytes).
Del S = Str.Del(S1, B, E, F)(L)	Creates and returns a copy of S1 str with the specified range deleted. S1 as well as B (Begin) and E (End) args are required. Value of -1 for E, means go to the end. F, if given, combines flags: defaults to #Pos + #Byte. First out arg, if given, will get the StrLen (bytes). Note: +++
Sub S = Str.Sub(S1, B, E, F)(L);	Creates and returns a subset of the specified S1 string. S1 as well as B (Begin) and E (End) in args are required. Value of -1 for E, means go to the end. F, if given, combines flags: defaults to #Pos + #Byte. First out arg, if given, will get the StrLen (bytes). Note: +++
Adjust S = Str.Adjust(S1, F)(L);	Creates and returns a copy of S1 str with indicated adjustments. F can ask for: #Low, #Up, or #Cap to change the case (word by word), #Root to replace accented (Latin) chars with their root version, #Lig to expand ligatures to their base letters. First out arg, if given, will get the StrLen (bytes).
BLen X = Str.BLen(S);	Returns the byte len of S str, or -1 if not a str.
CLen X = Str.CLen(S);	Returns the char len of S str, or -1 if not a str.
BPos X = Str.BPos(S, CPos) (BLen, BStart);	Returns byte pos (BStart) of nth char (CPos is 0 based). BLen will get byte len of char and BStart gets its start position. Returns -1, BLen of 0, and BStart of -1 for bad CPos. (BStart out arg is superfluous as the same value is returned.)
CPos X = Str.CPos(S, BPos) (BLen, BStart);	Returns char pos of nth byte (BPos is 0 based). BLen will get byte len of char and BStart gets its start position. Returns -1, BLen of 0, and BStart of -1 for bad BPos. (BStart out arg is necessary because BPos may be mid-UTF-8 char!)
Find X = Str.Find(DataS, S, BFrom, F) (BStart, BEnd);	Returns 1 if it finds S (Str) within DataS (Str), 0 otherwise. Searches DataS starting at BFrom (0 by default). Accepts #Insen/#Sen + #Smart/#Exact + #UniDir/#Dir for F. Sets BStart/BEnd to start/end of matching sub-string in DataS. BEnd (like E above) will be AFTER last matching byte, so EXCLUSIVE. (Note: Because of #Smart, Match in DataS may be shorter/longer than S!)

Defs:
Unit flags	#Byte or #Char
Count flags	#Pos or #Len
Local Flags	#Zulu or #Local
Number Flags	#Sep (default) to accept thousands separator, #NoSep if not. (Uses decimal and separator char defined in sc Params!)
Adjust Flags	#Low, #Up, or #Cap to capitalize. (Default is no case change) #Root to replace accented chars with their roots. #Lig to expand known ligatures to their base chars. (Flags on different lines can be \| or + together.) #Norm (#Low \| #Root \| #Lig) is shortcut flag for normalizing. #Norm turns Löwe Straße to lowe strasse for easier search/lookup.
Find Flags	#InSen (default) or #Sen for case comparison. #Smart (default) or #Exact for handling Unicode accents. #UniDir (default) or #BiDir for matching accents to root. Note: ### (Flags on different lines can be \| or + together.)

***: Numbers in data very often use a comma as thousands separator, such as 1,256,853. The default #Sep flag will read and ignore the comma Sep chars. Different locales have slightly different rules, so the system requires a minimum of 2 digit separation. It also uses the Dec and Sep chars defined in sc params. But data can sometimes use commas as delimiters between individual numbers, such as 12,4582,13449. In that case #NoSep will view the comma as a break, so Str.ReadN will read three separate numbers, 12, 4582, and 13449. This info also applies to Ed.ScanN, which reads numbers from scEmacs buffers instead of strings.

+++ Specifying a range, for Sub and Del, can be done using #Pos, as in from position X to Y, or by #Len, as in start at X and go L steps. In both cases, the steps can be #Byte or #Char. These will yield very different results for multi-byte UTF-8 chars. In the case of #Byte units, if the count falls in the middle of a UTF-8 char, Del will adjust to minimize the segment while Sub will adjust to maximize.

Str.Del from #Pos 8 to 10 (assuming #Char) will remove the chars at position 8 and 9. This will be equivalent to starting at 8 with a #Len of 2.

###: Str.Find will match accented chars against their unadorned (root) version in its default #Smart mode. But will require an exact match (adjusting for case) if #Exact is specified. If #Smart is set, under the default #UniDir flag, accented chars in S will only match accented chars in DataS, but root chars in S will match their accented version in DataS. With the #BiDir flag, accented chars in S can also match their root versions in DataS. (#UniDir and #BiDir flags are ignored if not #Smart.)