Category : C++ Source Code
Archive   : WLIB.ZIP
Filename : WMISC.DOC

 
Output of file : WMISC.DOC contained in archive : WLIB.ZIP
Miscellaneous library documentation

October 11, 1989
February 20, 1991
May 15, 1992 (minor update)
October 20, 1992 (minor update)
January 27, 1993 (minor update)

copyright (c) 1992, 1993 by Paul Wheaton

Note that this documentation does not cover all of the features of the
provided in this library. For that, you will have to look at the header files.

The Wheaton Libraries are shareware. Anyone may use the libraries provided
that they do not change them. If you want to change them or if you want
phone support from me, you must pay $50. This in the hope that the hundreds
of vendors that are creating their own string libraries can go with just
one - I'm pretty tired of getting a library in that seems like it will be
pretty cool, just to find out that it uses the same identifiers as
something else and there are then link conflicts.

To make these libraries available, you need to include and link
with WLIB.LIB.

Miscellaneous
1 Type definitions
2 Constants
2.1 Type limits
2.2 Boolean
2.3 Position indicator (Left, Right and Center)
3 Functions
3.01 Abs()
3.02 Max()
3.03 Min()
3.04 InRange()
3.05 Delay()
3.06 Sound()
3.07 Beep()
3.08 Randomize()
3.09 Random()
3.10 DebugPause()
3.11 CopyArray()
3.12 CopyString()
3.13 ClearStruct()
3.14 ClearArray()
3.15 Rounding functions
3.16 ToUpper() ToLower()
3.17 PigeonHole()
3.18 SystemTick()
3.19 CRC()
4 Loop handling
4.1 Loop
4.2 For


1 Type definitions

Using these types allow programmer control over the consistency of what
they describe from environment to environment. In K&R C (or pre-ANSI C),
the definitions where that "int" could be a 32 bit integer on some
systems and a 16 bit integer on others, whatever seemed more "natural"
for the computer. Now, the ANSI standard supports the old K&R style but
have added that although some computers like 32 bit values better, they
are required to accept the use of 16 bit values. The compiler may
actually manipulate the 16 bit value in a 32 bit data area provided that
the program is treated as though it's a 16 bit area.

Number
Type of bits Sign?
------- ------- -----
Bool 8 No Use only one bit for True or False
Byte 8 No
SByte 8 Yes
Word 16 No
SWord 16 Yes
Long 32 No
SLong 32 Yes

2 Constants

2.1 Type limits

These limits are for the scalar types defined in section 1. Of course,
anything that isn't signed has a minimum of 0. The max constants are:
MaxByte, MaxSByte, MaxWord, MaxSWord, MaxLong and MaxSLong. The min
constants are: MinSByte, MinSWord and MinSLong.

2.2 Boolean

Of course, there's True and False. There's also Yes, No, On and Off.

2.3 Position indicator (Left, Right and Center)

The constants Left, Right and Center are recognized by several
different functions as parameters. Display and JustText are two
that come to mind. In the case of Display, if you pass Center in
the X parameter, the String (that is also passed) will be placed
such that it is centered on that row of the window. These numbers
may be stored as large negative values (type SWord), so be careful
that you don't try to assign them to incompatible types.

3 Functions

3.01 Abs()

Prototype: [num type] Abs([num type])

Overloaded so that you don't need a different function for every
type. Pass any numeric type that will hold a negative number and it
will return the same type.

3.02 Max()

Prototype: [num type] Max([num type],[num type])

Overloaded function that takes two arguments of the same type and
returns the larger value as the same type.

3.03 Min()

Prototype: [num type] Min([num type],[num type])

Overloaded function that takes two arguments of the same type and
returns the smaller value as the same type.

3.04 InRange()

Prototype: Bool InRange([num type] Val, [num type] Low, [num type] High)

Overloaded function that takes three arguments of the same type and
returns True if the first number is in the range of the other two,
inclusively.

3.05 Delay()

Prototype: void Delay(long MilliSecs)

Delay this process for the number of milliseconds passed. A value
passed of 1000 means delay for one second. Note that on
multi-tasking systems, the operating system will turn the CPU time
over to something else for this period of time.

3.06 Sound()

Prototype: void Sound(float Pitch, int MilliSecs)

For values to plug into Pitch, see page 147 of "The Peter Norton
Programmer's Guide to the IBM PC". If you don't want to bother to
look there and don't know what "pitch" or frequency is, then let's
just say that higher numbers play higher notes. MilliSecs is how
long the sound lasts. This function won't come back until it's done
making its noise.

3.07 Beep()

Prototype: void Beep(int Num=1)

For those that are not familiar with default parameters, let me
point out that you may call this function without any paramters
(Beep();) and there will be one beep. You also have the option of
calling it with one parameter and specify the number of beeps that
you want. "Beep(4);" will play 4 beeps.

3.08 Randomize()

Prototype: void Randomize()

Initializes the random number generator.

3.09 Random()

Prototype: int Random(int Max)

Returns a random integer in the range of 0..Max-1.

3.10 DebugPause()

Prototype: void DebugPause(ConstantStringMessage)

Displays the string onto the screen rather sloppily and pauses for a
second or two. Since this function uses a macro, the string
parameter MUST be a string constant.

DebugPause("xxx entering loop"); // valid call
DebugPause(SomeString_AnyStringType); // invalid call

3.11 CopyArray()

Prototype: void* CopyArray(DestArray,SourceArray)

The functions CopyArray, CopyString, ClearStruct and ClearArray all
expect straight parameters without any extra pointers or
referencing. Since these functions are macros, the first (or only)
parameter must be something that sizeof will work on effectively.

If SourceArray is smaller than DestArray, a bunch of garbage will be
in the end of DestArray. If SourceArray is bigger than DestArray,
only a subset will be copied. Note that this is just a bitwise copy
and does not care what the types of either array are.

static int A1[5]={1,2,3,4,5};
int A2[3];
CopyArray(A2,A1); // A2 now contains the first 3 elements of A1
int *A3=A2;
CopyArray(A3,A1); // unpredictable results!!!
// sizeof a pointer probably isn't what is desired

3.12 CopyString()

Prototype: void CopyString(Dest,Source)

Just like CopyArray, cept it will stop if it finds a null character
and make sure that there's a null character copied over. Note that
this is for strings of type char* only!

3.13 ClearStruct()

Prototype: void ClearStruct(S)

Fills the struct with zeros.

struct
{
long A,B,C,D,E,F;
} S;
ClearStruct(S);

3.14 ClearArray()

Prototype: ClearArray(A)

Fills the array with zeros.

float F[20];
ClearArray(F);

3.15 Rounding functions

Prototypes: long Round(double Val)
long RoundUp(double Val)
long RoundDown(double Val)
long RoundOut(double Val)
long RoundIn(double Val)

Initial value .2 .7 -.2 -.7

Round() 0 1 0 -1
RoundUp() 1 1 0 0
RoundDown() 0 0 -1 -1
RoundOut() 1 1 -1 -1
RoundIn() 0 0 0 0

3.16 ToUpper() ToLower()

Prototypes: char ToUpper(char C)
char ToLower(char C)

If a lower case char is passed to ToUpper() it will be converted to
an upper case char. Any other characters passed in will be
unchanged. ToLower() works the same way except that upper case
chars are converted to lower case.

3.17 PigeonHole()

Prototype: void PigeonHole(long TotQuan, int ArrayLen, int A[]);

This function will take TotQuan and spread it as evenly as possible
over the array A. Example:

If you pass 13 in for TotQuan and 5 in for ArrayLen, A will have
the values 3, 2, 3, 2, 3.

3.18 SystemTick()

Prototype: Long SystemTick()

This function will return the current system tick. On a PC
compatible machine (running any OS) you will get about 18 ticks per
second.

3.19 CRC()

Prototypes: Word CRC(void* P,Long Size)
Word CRC(const Char* S)

The functions will return a 16 bit CRC (commonly known as a CRC16)
based on the data given. For the first function, pass a pointer to
anywhere in memory and then the number of bytes you want to be
included in the CRC calculation. The second function performs a CRC
on a null terminated string (does not include the null terminator).

A CRC is like an advanced checksum. It is used for integrity
checking and encryption. For more info, see the book
"C Programmer's Guide to Serial Communications" pp 533 - 550.

4 Loop handling

These loop handling macros are enhanced forms of existing loop
handling constructs.

4.1 Loop

Sets up an infinite loop. Generally, stopping the loop is with a
"return".

// program to keep on beeping until computer is reset
Loop
{
Beep();
}

4.2 For

This loop construct replaces the most common use of "for" in C
programming: A variable starts at zero, is incremented with each
iteration and stops just before reaching the stop value. This macro
is a simpler, more readable, less error prone loop construct.
Replace

int I;
for(I=0;I<15;I++)
Beep();

with

int I;
For(I,15)
Beep();

Note that in the "for" version, "I" is referenced three times, there
are two semicolon delimiters, an assignment operator with an
initialization value, a comparison operator, an increment operator,
a stop value and is 17 characters long. In the "For" version there
is one comma delimiter, one reference to "I", the stop value and is
9 characters long. Whenever there's a bug in a piece of code that
has a "for" loop like the one above, the first thing I check is how
many iterations there were. What would go through my mind in the
above example is: "All three parts have an 'I', not a 'l', 'i' or '1'.
The comparison operator is '<' not '<=' or '>'. 'I' is initialized
to '0' not 'O' or '1'. 'I' is incremented properly. Semicolons
were used, not commas or colons." Now that I've used the "For"
macro for a while, I'm used to seeing the above example and thinking
"It did iterate 15 times." There's only two things to check: The
proper variable was used and the right stop value was used.



  3 Responses to “Category : C++ Source Code
Archive   : WLIB.ZIP
Filename : WMISC.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/