Index
Strasheela
Init
GUtils
LUtils
MUtils
Score
SMapping
SDistro
Out
Strasheela
FD_edited
Midi
This functor defines some general utilities

Functor

Import

Export

Define

fun{XOr B1 B2}
Defines exclusive or: XOr returns true if only B1 or B2 are true. XOr returns false if B1 and B2 are both false or both true.
fun{Cases X Clauses}
Cases defines a general conditional similar to an 'if then elseif ...' statement. X is some datum to process dependent on boolean tests. Clauses is a list of test and action functions/methods in the form [Test1#Process1 Test2#Process2 ...]. The first test returning true for X 'fires' its Process and Cases returns the result of {Process X}. If no test returns true for X Cases returns nil.
fun{MakeTypecheck_NotKinded MyTest}
Mozart typechecks like IsRecord block on kinded variables. MakeTypecheck_NotKinded returns a variant of the type test MyTest (a Boolean function) which immediates returns false for kinded variables.


fun{IsEqual X Y}
Test equality with either '==' or System.eq (same value node in the store). E.g., records can be '==' while System.eq returns false and for objects its the other way round.
fun{IsFS X}
IsFS returns true if X is a FS variable (determined or not) and false otherwise. This function is necessary, because the primitive Oz functions FS.var.is and FS.value.is behave differently for determined and undetermined FS variables.
proc{MakeSingletonSet D MyFS}
Expects D (a FD int) and returns a singleton FS which contains only D.
proc{IntsToFS Ds MyFS}
Constraints that Ds (a list of FD ints) are all contained in MyFS (a FS, implicitly declared), but no other integer. This definition is similar to FS.int.match, but Ds must not be in increasing order.
fun{RelationComplement Dir}
Expects a FD relation atom ('<:', '=<:', '>:', '>=:', '=:', or '\\=:') and returns the complement. For example, the complement of '<:' is '>:', of '>=:' is '=<:' and of '=:' is '\\=:'.
proc{ConstrainRelation X Y A}
Constraints the relation between the FD ints X and Y according to A, a FD relation atom ('<:', '=<:', '>:', '>=:', '=:', or '\\=:').


fun{ConstrainRelationR X Y A}
Reified version of BinRelation.
proc{ReifiedDistance X Y Rel Z B}
Simple substitute for FD.reified.distance, which does not propagate enough.
E.g., check {Browse {FD.reified.distance 64 62 '>:' 3}}, which should return 0 and not {FD.int 0#1}.
proc{Percent N NoAll Result}
Expects MyFS (a FS) and returns Ds, a list of FD ints which are all contained in MyFS.
This definition is similar to FS.int.match, but Ds must not be in increasing order. This definiiton is also similar to IntsToFS, but Ds are created by FsToInts. The length of Ds is the cardiality of MyFS, and all elements in Ds are constrained to be pairwise distinct.

Note: blocks until cardiality of MyFS is determined
*/
proc {FsToInts MyFS ?Ds}
Ds = {FD.list {FS.card MyFS} 0#FD.sup}
in
{FS.unionN {Map Ds fun {$ D} {MakeSingletonSet D} end}
MyFS}
{FD.distinct Ds}
end


/** %% Constrains percentage of N (FD int) if NoAll (FD int) indicates 100 percent. Result is implicitly declared a FD int.
Example: {Percent 4 6} = 66
Note the rounding to 66 percent (better do not rely on exact value of Result but constraint it, e.g., by a comparison such as Result >: 50).
fun{Identity X}
The Identity function returns its argument.
fun{Random Max}
Returns a random integer in interval [0, Max-1].


fun{DevRandom }
Returns a random number generated by /dev/random (see man 4 random).
Note: this function is not extremely efficient, but very useful for generating random seeds.
fun{KnuthRandom }
Returns a random number between 0 and 2^64. Implements a linear congruential generator with parameters proposed by Donald Knuth for MMIX (see http://en.wikipedia.org/wiki/Linear_congruential_generator).
proc{SetKnuthRandomSeed Seed}
Sets the seed for KnuthRandom. If Seed is 0 then {GUtils.devRandom} is used.
fun{RandIntoRange Rand Min Max}
Expects a random integer between 0 and {OS.randLimits 0} (e.g., generated by {OS.rand}) and returns a random integer in Min - Max (Min and Max are integers).
fun{RandIntoRange2 Rand Min Max MaxRand}
Expects a random number Rand between 0 and MaxRand and returns a random integer in Min - Max (Min and Max are integers).
fun{RoundDigits F Digits}
Rounds F (a float) to Digits (an int) number of digits after the floating point.

Note: the accuracy of this rounding is subject to float accuracy..
fun{MakeRandomGenerator }
Returns a random number generator (a null-ary function) which returns a pseudo-random integer whenever it is called. Every returned random number generator will always produce the same number sequence: all random values are 'recorded' behind the scene in the top-level space. In other words, the random number generator is deterministic. Such a random generator can be used for a randomised value ordering, and the resulting distribution strategy can still apply recomputation (see SDistro.makeRandomDistributionValue). In such as case, MakeRandomGenerator must be called inside script. The convenient Strasheela solvers in SDistro do that implicitly.
Only a single instance of a random number generator can be used at a time. This instance can be (re)-initialised with SetRandomGeneratorSeed.
proc{SetRandomGeneratorSeed Seed}
Sets the seed for the random number generator used by MakeRandomGenerator (which internally uses OS.rand). If Seed is 0, the seed will be generated from the current time.
NOTE: calling SetRandomGeneratorSeed will corrupt any random number generator previously created with MakeRandomGenerator. Either call {SetRandomGeneratorSeed 0} only once after starting Mozart (so a 'random' seed is used), or re-feed your code calling MakeRandomGenerator after using SetRandomGeneratorSeed (e.g., re-call your solver).
fun{Log X Base}
Returns the logarithm to the base Base of X. X and Base must be floats and a float is returned.
fun{Mod_Float X1 X2}
Similar to the mod operation, but arguments and return value are floats.
fun{IsDivisible X Y}
Returns a Boolean value whether X is divisible by Y. X and Y are ints.
fun{RatioToFloat Nom#Denom}
Expects a ratio spec Nom#Denom and returns the corresponding float.
fun{IsRatio X}
Returns true if X is a pair of ints Nom#Denom.
fun{RecursiveRatio X#Y}
Expects a ratio X#Y and returns Y#X.
fun{PrimeFactors X}
Expects an int X and returns its prime factors (a list of ints in ascending order). Note: only primes up to 23 are tested, larger prime numbers are simply ignored.
proc{ToProc X Res}
Function ToProc transforms a method to a procedure. The argument X represents the method and its interface. X may be an atom (representing a method with no argument), or a record (e.g. representing a method with multiple arguments). For convenience, X may also be a procedure, which will be returned unchanged.

The returned procedure expects one, two or three arguments. The first argument is always the object to which the method is passed. If X is an atom, this is the only argument. E.g. {ToProc test} returns the procedure proc {$ O} {O test} end.

If the returned procedure expects more than only one argument, the last argument of the procedure is always the value at feature 1 of the method record. In Strasheela, the first method feature is usually defined as the return value of the method. If the method expects only that argument, the procedure returned expects two arguments. E.g. {ToProc isTest(x)} results in the procedure proc {$ O Result} {O test(Result)} end.

If the method defines multiple arguments, all other arguments are collected in a record in the second argument of the procedure. E.g. {ToProc isTest(x test:MyTest)} results in the procedure proc {$ O Args Result} {O test(Result test:Args.test)} end. Note that this example was simplified, as all arguments in Arg are optional. If Args.test is not given above, then the procedure is proc {$ O Args Result} {O test(Result test:MyTest)} end. However, the argument specifier at feature 1 always only a "dymmy value" that indicates the return value as in the example above.
proc{ToFun X Res}
Transforms an atom -- representing the label of a unary method -- into a unary function which expects as argument the object the method shall be send to. For convenience, X may also be a procedure, which will be returned unchanged.
fun{Procs2Proc Procs}
Returns a single unary procedure which applies all elements in Procs -- a list of unary procedures -- to its argument (example application: transforms a list of unary compositional rules into a single rule).
fun{ExtendedScriptToScript MyExtendedScript Args}
Convenience function for parameterised CSP scripts. An extended script is a binary procedure, i.e., a script where the first argument is a record of arguments expected by the script and the second argument is the script root variable.
ExtendedScriptToScript expects an extended script plus its Args, and returns a plain script (i.e. a unary procedure).
proc{ApplySelected Procs I}
The Ith element in Procs is applied. Procs is list of null-ary procedures. I is a FD integer, the domain of I is implicitly reduced to 1#{Length Procs}.
This is quasi a selection constraint, however, there are no constraint propagators created by ApplySelected. Instead, ApplySelected uses the deep-guard combinator Combinator.'or', i.e. a backtracking-free disjunction. ApplySelected suspends until a decision is made elsewhere (e.g. by determining I or by ruling out the cause of the application of all but one procedure in Procs).

See also Pattern.transformDisj
proc{EncodeRatio X Y Factor Q}
Q encodes X/Y by an integer as X/Y * Factor. Possible values for X/Y depend on Factor, e.g., 1/3 can not truely be represented if Factor=2. Factor should be an determined integer. For example, if Factor=12 then Q can represent 1/6 (Q=2), 1/4 (Q=3) etc.
fun{TimeVString }
SelectArg is a tool, e.g., to define functions with quasi optional values. SelectArg returns the value at Feature in record Spec, if Spec has this feature. Otherwise the value at Feature in the record Defaults is returned. Defaults must have this record.
!! Often the buildin Adjoin is a better solution: {Adjoin Defaults Args} = EffectiveArgs
*/
!!?? Shall I remove this?
fun {SelectArg Feature Spec Default}
if {HasFeature Spec Feature}
then Spec.Feature
else Default
end
end




/** % Returns a VS of the current time in the form
'hour:min:sec, day-month-year'.
fun{TimeForFileName }
Returns a VS of the current time in the form
day-month-year_hour-min-sec.

This format does not contain any characters that might be problematic in a file name.
proc{GetCounterAndIncr X}
Return an integer and as a side effect increment the integer for the next access.
proc{ResetCounter }
Resets the counter for GetCounterAndIncr.
proc{UnarySkip X}
proc{BinarySkip X Y}
fun{TakeFeatures R MyFeats}
Fun R (a record) and MyFeats (a list of symbols -- potential features in R). TakeFeatures returns a record which consists in all features and their values of MyFeats contained in R.


proc{RecursiveAdjoin R1 R2 Result}
Like Adjoin, but nested records are processed recursively.
R1 and R2 must have the same nesting for recursive processing, otherwise R2 features are taken (like Adjoin).
NB: lists and pairs are treated as elementary values, only 'normal' records are processed recursively.
fun{KeepList R Fs}
Opposite of Record.subtractList: returns a record like R, but only keeps the features Fs. Fs can contain features not present in R, but these will then be skipped.


fun{ModuleLink UrlVs}
ModuleLink is like Module.link except that multiple calls of ModuleLink share the same module manager (and don't create new managers as Module.link does). For instance, when ModuleLink links multiple functors which refer to a stateful datum in some functor, then all refer to the same datum instance. By constrast, linking with Module.link results into multiple stateful datum instances.
!! On second though, ModuleLink seems to solve a non-existing problem. ModuleLink is an attempt to avoids problems in case some functor is linked more then once in the OPI. Actually, this should happen only in two cases: either you want to create two module instances (with independent stateful data) or you want to reload a functor (e.g. after compilation) without restarting the whole program. In both cases, Module.link does the right thing. So, why did I ever need ModuleLink???
-> A buffer with this ModuleLink can be re-fed multiple times without problems. A call to Module.link should not be re-fed...


fun{ModuleApply UFs}
ModuleApply is like Moduel.apply expect that it always uses the same module manager (cf. ModuleLink).


fun{TimeSpend P}
Returns the time (in msecs) the application of P (a null-ary procedure) took.
proc{Assert B MyException}
If B is false, then MyException is raised.
proc{WarnGUI VS}
Opens a warning dialog which displays VS.
proc{InfoGUI VS}
Opens a warning dialog which displays VS.


proc{ErrorGUI VS}
Opens an error dialog which displays VS.


End