Maths v0606

From EuWiki

The library make available some tools which it internally uses. They are mainly concerned with decoding Windows message parameters and defining series, but may have much more general use though.

Contents 1 Low level operations 2 Series 2.1 Defining series 2.1.1 The positive integer series 2.1.2 General arithmetic series 2.1.3 General series 2.2 Queries on series 2.3 Changing the parameters 3 Other functions

Low level operations

w32hi_word(atom data)

Returns bits 16..31 of data as an unsigned 16-bit word. data must fit into a machine integer, otherwise and_bits() will generate an error.

w32lo_word(atom data)

Returns bits 0..15 of data as an unsigned 16-bit word. data must fit into a machine integer, otherwise and_bits() will generate an error.

w32signed_word(atom data)

Returns bits 0..15 of data as a signed 16-bit word. data must fit into a machine integer, otherwise and_bits() will generate an error.

w32pack_word(integer lo_16,integer high_16)

Returns a 32-bit unsigned integer, with high_16 as high word and low_16 as low word.

w32shortint(atom data)

Currently a synonym for w32signed_word(), although this may not be true in earlier versions of the library.

w32or_all(sequence flags)

Performs a bitwise OR of the elements of flags, and returns the result. flags is expected to be a sequence of atoms all of which fit into a machine integer. However:

• if flags is an arom, it is returned unchanged;
• if flags is {}, 0 is returned;
• if flags is a sequence of length 1, w32or_all is applied to its only element.

w32get_bits(atom data)

Returns a sequence made of the powers of 2 that data is the sum of. data must fit into a machine integer, and interpreted as such. The powers are returned in increasing order. w32get_bits(0) is {0}.

Series

A series is a process which sequentially generates numbers. It is defined by its initial value and its recurrence rule - the way it produces a new value -. One can ask a series to return its current value without generating the next, or to generate and return its next value.

See the MultiDialog.exw demo program for an example.

This model is implemented by the library as follows.

Defining series

There are three levels of sophistication.

The positive integer series

This is the series which starts by 1 and increments its value by 1: 1,2,3,...

The next_number(object some_name) returns 1 if some_name is not registered as a series yet, and creates the series.

General arithmetic series

You must create the series using define_series(object some_name,sequence parameters). As above, some_name is anything you may think of. parameters is a sequence of pairs {attribute,value}. Attributes of interest at this point are:

• SFirst: second element is the initial value of the series. The default value for the starting point is 1;
• SWrap: second element is either 0 (no wraparound) or anything else to trigger wraparound when the final value is reached;
• SLast: second element is a value which, if reached, causes the series to wrap to its initial value. Default is 0; this is ignored unless the wrap flag is set;
• SIncr: second element is the value by which the series increments. Default increment is 1;

General series

Thislevel enables side effects to occur or general recurrence to be used, possibly with a state that persists between invocations. The same define_series(some_name) procedure must be called. However, you can use two more attributes:

• SRtnId: the second element is a routine_id to be called whenever the current or next value is requected. Default is -1 (none).
• SUserData: the second element is anything the user cares to store between invocations of the routine. Default value is 0.

Whenever a value is queried for the series, the supplied routine is called with the following arguments:

• object pName : The name of the series.
• integer pRequest : Either SCB_CurrentNum or SCB_NextNum which is the type of request that the user is asking for.
• atom pValue : The series' current value.
• integer pHasWrapped : Either 0 (false) or 1 (true) indicating whether or not the series just wrapped around to the start again.
• object pUserData : The user data stored in the series by the last define_series() call to it.

The returned value is recorded if this is a new value and then returned to the user as result of his query.

Queries on series

current_value(some_name)

Returns the current value of the series, or {} if it doesn't exist.

next_number(some_name)

Returns the next value for the series, creating one if it doesn't exist already;

get_series(some_name)

Returns the full definition as a sequence made of:

1. The current value of the series.
2. The amount to increment the series by.
3. Indicator that the series can wrap from last to first.
4. The first value in the series.
5. The last value in the series.
6. The stored routine_id, if any
7. The current user data.

Changing the parameters

If you call define_series() on a series that already exists, you can change any attribute it has using the mechnism shown above. Further, you can change the current value by using a {SValue,new_value} pair inside the parameter sequence.

Other functions

The below are useful functions that didn't sem to fit anywhere else:

w32abs(object x)

Returns the absolute value of x: all the atoms it is comprised of are turned into their absolute values, and the tree structure of x is preserved.

w32iff(atom condition,object if_true,object if_false)

If the first argument is 0, if_false is returned, else if_true.

getRandInt(atom min,atom max)

Uses the cryptographic capabilities of Windows to return a random integer. min and max must fit into machine integers, and the returned value lies between these two bounds included. Because Windows uses various sources to maintain this random number generator, you can't use it like random() to get reproducible output.