Package util

Summary

Classes:
Args, BlockRead, ClTable, Comparator, Connectable, Error, FindFirst, MD5, MapBytes, Money, Notification, Notifier, PushBack, SetFields, StringBuff, StringReplacer, Subscription, Time, Timezone

Procedures:
WS, breadthwalk, buildStackTrace, deepcopy, defaultGenChildren, delPrefix, delSuffix, depthwalk, encodeCSV, encodeCsvField, evenResults, findFirst, format_escape, format_int_to_string, format_int_to_words, format_norm, format_numeric_to_string, format_string_to_int, format_unescape, genCSV, genFields, genFieldsOne, genWords, getClassField, getMethod, get_current_time, get_int, get_known_timezone, get_system_timezone, get_utc_timezone, hideAllChars, hideEscapedChars, initRandom, init_time, init_timezone, invertTable, isEscapeSeq, lPad, lTrim, lcp, lcs, listToString, m_add, m_binop, m_col, m_colswap, m_constant, m_copy, m_divide, m_identity, m_inverse, m_linearSolve, m_lupDecomposition, m_lupSolve, m_multiply, m_negative, m_rowswap, m_subtract, m_transpose, m_unaryop, m_write, mapBytes, matchCSet, matchString, matchVar, microseconds, milliseconds, month_to_num, nthResults, oddResults, parseCSV, permuteList, qsort, rPad, replaceStrs, sbal, scanlocus, skipFirst, skipOver, skipTo, sleep, snapshot, stringToList, tabPast, tabSkip, time, weave, ws, zapPrefix, zapSuffix

Global variables:
Time_data_base_year, Time_data_months, Time_data_tzchars, Time_data_unix_base_offset, Time_data_week_days, known_timezones, system_timezone, utc_timezone

Files in package:
args.icn, blockread.icn, cltable.icn, comparator.icn, connectable.icn, error.icn, format.icn, listener.icn, mapbytes.icn, matrix_util.icn, md5.icn, misc_util.icn, money.icn, notification.icn, notifier.icn, pushback.icn, qsort.icn, scan_util.icn, setfields.icn, str_replacer.icn, str_util.icn, stringbuff.icn, time.icn, timezone.icn

Details
Procedures:

WS()

Returns:
skipped over whitespace, if any
Fails:
if no whitespace

Skip whitespace. This is a matching procedure.


breadthwalk(root, getChildren)

Parameters:
root
node of graph to start walk at
getChildren
Generates:
the nodes in sequence that are reachable from the root

Breadth-first walk of a connected graph (nodes are visited exactly once). Note that the graph can be a tree.

The second argument should be a function that, when given a node, generates the links from that node. If omitted, it defaults to:

     procedure defaultGenChildren(node)
        suspend !\node[2]
     end
function that generates a node's children


buildStackTrace(n:0, ce)

Parameters:
n
starting distance from this call
ce
Generates:
the stacktrace from current call back to first in the co-expression

Compute the current stack trace. Starting at level n above the current procedure. Here, n defaults to 0, which will include this procedure in the stack trace. ce defaults to ¤t. This only works with newer versions of Unicon!

co-expr to trace stack in [¤t]


deepcopy(A, cache)

Parameter:
A
- structure to copy
Returns:
a deep copy of any structure, including cyclic ones

deepcopy(A) produces a full copy of the structure A. All structures are handled, including all dags and cycylic graphs.


defaultGenChildren(node)

Parameter:
node
graph node to produce children from
Generates:
child nodes of node

Given node represented by an indexable structure where the 2nd element is a list of links from that node, generate those links. Used as default in breadthwalk() and depthwalk().


delPrefix(s, prefix)

Parameters:
s
String to examine
prefix
Suffix to remove if present
Returns:
s with prefix removed, or s if prefix not found

Strip prefix from string s.


delSuffix(s, suffix)

Parameters:
s
String to examine
suffix
Suffix to remove if present
Returns:
s with suffix removed, or s if suffix not found

Strip suffix from string s.


depthwalk(root, getChildren, visited)

Parameters:
root
node of graph to start walk at
getChildren
function that generates a node's children
visited
Generates:
the nodes in sequence that are reachable from the root

Depth-first walk of a connected graph (nodes are visited exactly once). Note that the graph can be a tree.

The second argument should be a function that, when given a node, generates the links from that node. If omitted, it defaults to:

     procedure defaultGenChildren(node)
        suspend !\node[2]
     end

The third argument is used internally and should not be given by the user.

ignore, used internally.


encodeCSV(A, sep)

Parameters:
A
list to put into CSV-formatted string
sep
character used to separate fields (default ',')
Returns:
a CSV-formatted string for the list of fields

Produce a CVS-formatted string from a list of field values


encodeCsvField(field)

Parameter:
s
field to format
Returns:
the field in legal CSV format

Put a single field into legal CSV form.


evenResults(L)

A PDCO that produces only the even results from its argument. <[/p> First argument must be a co-expression.


findFirst(a)

Like find, but accepts a list of strings and finds them by their order of appearance in the subject string. The list of strings is searched in order. To locate the longest substring first, sort the list in reverse order, as in:

     findFirst(::reverse(::sort(a)))
 

Deprecated in favor of the FindFirst class.

List of strings to look for.


format_escape(subject)


 Add escape sequences to the subject.


format_int_to_string(subject, base, p)


 Convert an integer to a string.

 @param base   The desired base of the result.
 @param p      The minimum width of the result, padding with zeroes
 @             if necessary.


format_int_to_words(subject)


 Convert the subject integer into words, eg 231 to "Two Hundred and Thirty-One"


format_norm(n)


format_numeric_to_string(subject, p, f)


 Convert a numeric to a string.

 @param p  The number of decimal places to produce (default 4).
 @param f  A cset of flags.  If c contains {'e'} then the output is
 @         in scientific notation.  If c contains {','} then commas
 @         are introduced into the non-fractional part of the number;
 @         if c contains {'+'} then a leading + is added to positive
 @         numbers.
 @


format_string_to_int(subject, base)


 Convert a string to an integer.
 @param base  The base to use for the conversion (default is 16).


format_unescape(subject)


 Remove escape sequences from the subject.


genCSV(s, sep, spanFlag)

Parameters:
s
CSV string to parse
sep
set of characters (default ',') to separate fields
spanFlag
if non-null, indicates that fields are separated by one or more separators instead of just one
Generates:
the fields in CSV-formatted string s

Generate the fields from a CSV-encoded string. Fails on any field that isn't well-formed:

- fields with doubles quotes or embedded separators must be enclosed in double quotes
- double quotes in fields must be doubled: e.g. to embed "five", use ""five""
- leading and trailing whitespace (blanks and tabs) is stripped unless embedded inside a double-quoted field
- if blank and/or tab are used as separators, they are not considered whitespace
Also, any characters except double quotes and newlines may be used as separators.


genFields(s, cs:' \t\n')

Parameters:
s
String to examine
cs
Generates:
the fields in s that are _separated_ by sequences of one or more characters in cs.


genFieldsOne(s, cs:' \t\n')

Parameters:
s
String to examine
cs
Generates:
the fields in s that are _separated_ by exactly one of the characters in cs (i.e. can have empty fields). Leading characters in cs are treated as separating empty fields.


genWords(s, cs)

Parameters:
s
String to examine
cs
Characters comprising words (default: &letters)
Generates:
the "words" in s. By default, words are defined as sequences of 1 or more letters


getClassField(c, s:string)

Parameters:
c
instance of a class
s
name of field to produce from c
Returns:
field named s

Returns the field named s from the class instance c. The field is not dereferenced and thus can be assigned to.


getMethod(c, s:string)

Parameters:
c
instance of a class
s
name of method to produce from c
Returns:
method named s

Returns the method named s of the class instance c. The method is not dereferenced and thus can be assigned to. Methods of superclasses may be accessed by making s a period delimited list, for example getMethod(foo, "A.b") returns the method b of the superclass of type A that foo inherits from.


get_current_time(z)


 Get the current time as a {Time} object
 @param z an optional {Timezone}.  If omitted, the system timezone is used.


get_int()


 Utility to get next integer


get_known_timezone(id)


 Convert a zone id into a Timezone


get_system_timezone()


get_utc_timezone()


hideAllChars(s)

Parameter:
s
String of characters to hide.
Returns:
string with all characters mapped out of &ascii

Shift all the characters in a string into characters outside of &ascii. This procedure is intended as aid when using hideEscapedChars() by making it easier to construct the third argument, as in:

    s := hideEscapedChars(s, s1, hideAllChars(s1))
 


hideEscapedChars(s, s1:"(", s2, esc:'\\')

Parameters:
s
String to examine
s1
Look for these characters
s2
... and replace with these
esc
Escape character
Returns:
s with characters in s1 hidden by replacing them with corresponding characters in s2

Hide escaped instances of characters. Often, string scanning can be simplified if some characters are 'hidden' whenever they are escaped. (For example, consider running bal() on "(\))".) This procedure can be used to hide/unhide such escaped characters by converting them to other (typically in &cset--&ascii). Unhiding is accomplished by switching the second and third arguments.

The second and third parameters behave as in map(), except that s1 defaults to "(" and s2 defaults to a character string selected from &cset--&ascii. Note that accepting the defaults makes it more challenging to unhide the characters later!

The fourth parameter defaults to a backslash.

Probably doesn't work right when trying to hide escapes...


initRandom()

Returns:
the intial seed

Initialize the random number seed to a 'random' value, so a different random sequence is generated on each run of the program. Meant to be called once, in procedure main(). . Unicon now initializes the seed by default, so this is largely moot.


init_time()


 Initialize global data


init_timezone()


invertTable(tbl)

Returns:
a copy of the inverted table tbl

Invert a table (will lose data unless tbl is a 1-1 mapping).

Table to invert


isEscapeSeq(s, esc:'\\')

Parameters:
s
String to examine
esc
Escape character (defaults to <tt>\</tt>)
Returns:
s if it ends in an odd number of escape characters

Succeed if string s ends in an odd number of escape characters. This is a specialty procedure - it's intended to simplify the task of determining if the 'next' character of the string that has s as a substring is escaped or not. If this procedure succeeds, that 'next' character is escaped and s is returned.

The second parameter defaults to a backslash, the traditional escape character.

This is not a scanning procedure, but is placed in this source file to avoid circular dependencies when building.


lPad(s, n, p)

Parameters:
s
string to pad
n
desired field width. The actual width will be max(*s, n)
p
string to use as padding

Pad a string on the left if it is too short. This method is similar to the function left except that lPad returns the original string if it is longer than the specified field, while left truncates the string to fit in the field.


lTrim(s, cs)

Parameters:
s
String to examine
cs
Characters to strip from beginning of <tt>s</tt>.
Returns:
s with prefix of characters in cs stripped

Trim all characters in cs from the left edge of s. Same parameters and defaults as trim(s,cs).


lcp(s1, s2)

Returns:
longest common prefix of s1 and s2

Given two strings, produces the longest prefix they share in common.


lcs(s1, s2)

Returns:
longest common suffix of s1 and s2

Given two strings, produces the longest suffix they share in common.


listToString(a, sep:"\n")

Parameters:
a
list to join elements from into a string
sep
character to join elements on (defaults to newline)

Convert a list of strings into a single string. <[turns string formed by joining elements in a.


m_add(M1, M2)

Parameters:
M1
first matrix
M2
second matrix
Returns:
M1+M2


m_binop(M1, M1, op)

Parameters:
M1
first matrix
M2
second matrix
op
binary operation to invoke
Returns:
M1 op M2, with op defaulting to proc("+",2)

Generic binary operation across two matrices.


m_col(M, a)

Parameters:
M
matrix
a
column to return from M
Returns:
column a of M


m_colswap(M, a, b)

Parameters:
M
matrix
a
first column to swap
b
second column to swap

Swaps columns a and b of M


m_constant(m, n, x:0)

Parameters:
m
number of rows
n
number of columns
x
initial value of every element
Returns:
a m x n matrix with x everywhere


m_copy(M)

Parameter:
M
a matrix
Returns:
a copy of matrix M


m_divide(M1, M2, addfun, subfun, mulfun, divfun, addident, mulident, invertMetric)

Returns:
a matrix X such that M2*X = M1

Additional optional arguments allow you to customize the operation by overriding various functions and constants used internally.


m_identity(m, n, zero:0, one:1)

Parameters:
m
number of rows
n
number of columns
zero
(optional) can be used in place of 0.0
one
(optional) can be used in place of 1.0
Returns:
mXn identify matrix

Creates a m x n matrix with ones on the diagonal and zeros everywhere else


m_inverse(M, addfun, subfun, mulfun, divfun, addident, mulident, invertMetric)

Returns:
the (multiplicative) inverse of M

Additional optional arguments allow you to customize the operation by overriding various functions and constants used internally.


m_linearSolve(A, b, addfun, subfun, mulfun, divfun, addident, mulident, invertMetric)

Returns:
the solution x to A*x = b

Additional optional arguments allow you to customize the operation by overriding various functions and constants used internally.


m_lupDecomposition(M, subfcn, mulfcn, divfcn, invertMetric, addident:0, mulident:1)

Returns:
the LUP decomposition of M, fails if M is singular

The result is returned as a list [L, U, p] of matrices such that P*M = L*U, and p is a list representing the permutation to create P.

Additional optional arguments allow you to customize the operation by overriding various functions and constants used internally.


m_lupSolve(L, U, p, b, addfun, subfun, mulfun, divfun, addident:0)

Returns:
the solution x to A*x = b where the LUP decomposition of A is [L,U,p]

Additional optional arguments allow you to customize the operation by overriding various functions and constants used internally.


m_multiply(M1, M2, addident:0, addfcn, mulfcn)

Parameters:
M1
first matrix
M2
second matrix
addident
(optional) additive identify replacement
addfcn
(optional) addition operation replacement
mulfcn
(optional) multiplication operation replacement
Returns:
M1*M2


m_negative(M)

Parameter:
M
matrix
Returns:
-M


m_rowswap(M, a, b)

Parameters:
M
matrix
a
first row to swap
b
second row to swap

Swaps rows a and b of M


m_subtract(M1, M2)

Parameters:
M1
first matrix
M2
second matrix
Returns:
M1-M2


m_transpose(M)

Parameter:
M
matrix
Returns:
the transpose of M


m_unaryop(M, op)

Parameters:
M
matrix
op
unary operation to invoke
Returns:
op M, with op defaulting to proc("-",1)

Generic unary operation across a matrix.


m_write(args)

Output matrices.

A file argument changes output of subsequent arguments to that file (default is &output). String arguments are output as they appear. Matrices are output one row per line of output followed by a blank line.

Matrices and output files


mapBytes(s, in, out)

Parameters:
s
String to re-arrange
in
Input byte order, e.g. "1234"
out
Output byte order, e.g.: "4321"

Deprecated in favor of the MapBytes class

Do byte reorderings efficiently. Assumes that the length of string s is a multiple of the length of in. If this isn't the case, the remaining characters in s are appended unmapped.

The default action is the identity mapping

To work, in and out must be the same length.


matchCSet()

Generates:
matched substrings

Tabmatch a Unicon cset This is a matching procedure.


matchString()

Generates:
matched substrings

Tabmatch a Unicon string This is a matching procedure.


matchVar()

Returns:
matched Unicon variable name

Tabmatch past a Unicon variable name. This is a matching procedure.


microseconds()


milliseconds()


 Return the current time of day from the system clock, in milliseconds.


month_to_num(s)


 Convert a month string to an month number, eg "feb"->2


nthResults(L)

Parameters:
n
(first coexpression in L) produce every nth result
sq
(second coexpression in L) sequence to produce results from
Generates:
every nth result from sq

A PDCO that wraps a result sequence sq and produces every nth result. n defaults to 1.

first arg is n, second is sq.


oddResults(L)

A PDCO that produces only the odd results from its argument. <[/p> First argument must be a co-expression


parseCSV(s, sep, spanFlag)

Parameters:
s
CSV string to parse
sep
set of characters (default ',') to separate fields
spanFlag
if non-null, indicates that fields are separated by one or more separators instead of just one
Returns:
a list of the fields in the string s

Produce a list of the fields from a CSV-formatted string.


permuteList(L)

Generates:
all permutations of the elements in list L

List to permute


qsort(l, comparator, first, last)


 The classic quick sort procedure.


rPad(s, n, p)

Parameters:
s
string to pad
n
desired field width. The actual width will be max(*s, n)
p
string to use as padding

Pad a string on the right if it is too short. This method is similar to the function right except that rPad returns the original string if it is longer than the specified field, while right truncates the string to fit in the field.


replaceStrs(s, tbl)

Parameters:
s
String to examine
tbl
Table of replacement strings. Keys are substrings to locate, entries are corresponding replacements
Returns:
copy of s with replaced substrings

Given a string and a table of strings (keys and entries), replaces occurrences of the table key values with the corresponding entry values. Finds longest sequence matching a key value.

replaceStrs is most useful in simple cases where you have only a few replacements to make on comparatively short text. For large numbers of replacements across a lot of text, the StringReplacer class is likely to faster.


sbal(keyStrings)

Parameter:
keyStrings
table of start->stop pairs
Generates:
matching substrings

Match strings the same way bal() matches characters. The input table is a tagged set of strings to match. The key is the start string while the value is the end string. This makes sure the start and stop strings are balanced w.r.t each other.

For example, given the table:


     t := table()
     t["begin"] := "end"

then the code:

     if match("begin") then
        clause := sbal(t)

assigns to clause the substring from begin through the matching end. (Assuming, of course, that there are no conflicts along the way...)

This is an unoptimized preliminary version that may contain bugs.


scanlocus(prefix:"", n:8)

Parameters:
prefix
Precedes any output (default is "")
n
Returns:
an empty string, corresponding to a move(0)

Similar to snapshot(), but displays only a portion of very long scan subjects. This is a (trivially) matching procedure.

amount of &subject to show (default is 80)


skipFirst(L)

Parameters:
n
(first coexpression in L) produce results after first n results
sq
(second coexpression in L) sequence to produce results from
Generates:
all results after the first n from sq

A PDCO that wraps a result sequence sq and produces all results after the first n results. n defaults to 0.

first arg is n, second is sq.


skipOver(n)

Parameter:
n
number of characters to move over in subject string

Skip over n characters in subject string. This is similar to move(), but doesn't construct a substring.


skipTo(p)

Parameter:
p
position to jump to in subject string

Skip to a position in the subject string. This is similar to tab(), but doesn't construct a substring.


sleep(n)


 Sleep for n milliseconds.  This is for backward compatibility;
 use the built-in function delay() instead.


snapshot(prefix:"")

Returns:
an empty string, corresponding to a move(0)

Produce a 'snapshot' of string scanning showing the current scanning position. This is a (trivially) matching procedure.

Precedes any output (default is "")


stringToList(s, sep:'\n')

Parameters:
s
string to convert into list of strings
sep
character to break string on (defaults to newline)
Returns:
list of strings from s

Convert of string with (possibly) embedded separators into a list.


tabPast(cs)

Generates:
matched substrings

Tabmatch past the next unescaped character in cs Fails if no such unescaped character exists. This is a matching procedure.

cset of characters to tab past.


tabSkip(s)

Returns:
tabbed over portion, omitting skipped substring

Produce everything up to a substring and skip past that substring. This is a matching procedure. On success, the scanning position is left after the substring.

substring to tab up to and skip over


time(L)

Returns:
the time in milliseconds to execute its argument.

A PDCO that can be used to time expressions. (Only accurate to the millisecond level.)

Examples:

   write(" [",time { writes("fib(",n,") = ",fib(n)) }, "ms]" )

   write(" [", time { {every 1 to limit do {
                      f := fib(n)
                      }
                  writes("fib(",n,") = ",f, " run ",limit," times.")
                 }   # Note extra braces for compound expression!
               }
        , "ms]")

First arg is expression to time


weave(L)

Parameter:
L
- arbitrary number of co-expressions
Generates:
results from all the co-expressions in L by interleaving

A PDCO that interleaves results from its arguments. For example, the following code produces a (very fast) 'spinner':

   every writes(weave{!|"-\\|/", !|"\b"})

Expressions whose results are to be woven together


ws()

Returns:
skipped over whitespace, if any

Matches 0 or more whitespace characters (Cannot fail) This is a matching procedure.


zapPrefix(s, prefix)

Parameters:
s
String to examine
prefix
Prefix to find and remove
Returns:
the suffix on a successful match
Fails:
if prefix does not match

Does string s start with prefix?


zapSuffix(s, suffix)

Parameters:
s
String to examine
suffix
Suffix to find and remove
Returns:
the prefix on a successful match
Fails:
if suffix does not match

Does string s end in suffix?


Global variables:
Time_data_base_year

Time_data_months -- Constant data for time functions

Time_data_tzchars

Time_data_unix_base_offset

Time_data_week_days

known_timezones

system_timezone

utc_timezone


This page produced by UniDoc on 2021/04/15 @ 23:59:54.