Book Contents Previous Chapter
This chapter describes a set of Magic Cap utility operations that are defined by class Utilities. Before reading this chapter, you should be familiar with Magic Cap's object runtime.
Magic Cap defines various utility operations that provide a wide variety of features. These utility operations perform functions in many different categories, including system timing, checksum calculation, memory movement and comparison, string manipulation, conversions, and more. For convenience, these utility operations are collected together as intrinsic operations in class Utilities.
Because all the operations of class Utilities are defined as intrinsics, you don't have to create a utilities object in order to use these routines. For example, class Utilities includes ShortRandom, an operation that returns a random number, defined as follows:
intrinsic ShortRandom(): UnsignedShort
Because ShortRandom is an intrinsic operation, there's no implied class parameter when you call it. Here's an example of how to call this operation:
if (ShortRandom() == 1)
{ /* Wow, the random number is 1 */};
For more information on ShortRandom, see this chapter's section Random Numbers, below.
Magic Cap defines class Utilities as a convenient way to group various diverse utility operations. This section describes the operations you might use in your packages.
Magic Cap performs idle-time actions periodically when no other actions are taking place. In general, these periodic idles occur frequently enough to handle any idle-time actions defined by your package. If you want to force Magic Cap to run idle-time actions, you can call PermitIdle.
Magic Cap redraws the screen periodically. In general, these periodic redraws should allow the screen to keep up with any changes you've made in your viewable objects. If you want to redraw more frequently, you can call PermitRedraw to force the screen to be redrawn.
Magic Cap defines a set of operations you can use to calculate and work with 32-bit checksum values. You can use these values to quickly compare large runs of data.
You can call CalcCRC32 to compute a 32-bit checksum of a given run of bytes. Call AccumulateCRC32 to calculate the checksum using a given seed value for the checksum. AccumulateCRC32 is useful if you want to add on to a previously computed checksum.
Magic Cap defines a set of operations of class Utilities that you can use to work with memory in various ways, including comparing and zeroing bytes.
You can call EqualMem if you want to test whether two runs of bytes in memory contain exactly the same data. EqualMem simply returns a boolean value indicating whether the two runs of bytes are identical.
You can call CompareBytes to compare two areas of memory that contain strings. CompareBytes returns values indicating if the strings are equal or, if not, the order of the strings.
Call ZeroMem to set a given range of memory to all zeroes. If you want to set a range of memory to all zeroes and you know the range is an even number of long words, use ZeroLongs instead of ZeroMem.
Magic Cap defines a number of operations that you can use to create hash values from source data. This section describes the hashing operations defined in class Utilities.
You can call HashBytes to create a hash value from given source data. You can indicate how much data to include either by giving the number of bytes or by specifying a particular data value that signals the end of the source data. Call HashPtrLenString if you simply want to create a hash value by specifying the source data and the number of bytes.
Call HashCString to create a hash value using a given C string as source data, or call HashText to create the hash value from a given text object. You can call TextHash if you want to create a short integer (16-bit) hash value from a string instead of the standard 32-bit value.
Class Utilities defines various operations for performing high-level manipulation on text. This section describes the text-related operations available in class Utilities.
You can call TextToInitials to convert a text object to the initials of the words in the text, separated by periods. For example, calling TextToInitials on the text Sleeping in the flowers would return the text S. i. t. f. .
You can call MakeSearchText to convert a text object, especially a name, into a convenient form for searching. If the given text object is a name, MakeSearchText returns the last name. If the given text object contains a comma, MakeSearchText assumes the text is in the form last name, first name and returns the part before the comma.
Magic Cap defines a pair of operations you can use for manipulating names in text objects. You can call FlipNameIfLastFirst to convert a name in the form last name, first name to a name in the form first name last name. Call LastNameIfFirstLast to return the last name from a name in the form first name last name or last name, first name.
Magic Cap defines a set of operations that are used mainly by debugging tools, such as the Inspector. You can use these operations in your packages if you want to get debugging information. Call TypeSize to get the size in bits of a particular field. Call ValueToText to convert a value to a textual version of the value. Call IndexicalToString to convert a given indexical to a textual form.
This section describes a pair of operations provided by Magic Cap for working with random numbers.
You can call ShortRandom to get a random number. The random number returned is a 16-bit integer. Call ReseedRandom to change the random number seed, which ensures that the sequence of random numbers will not be repeated.
This section describes various operations of class Utilities that don't fit into any other category in this chapter.
You can call DelayMilliseconds to make the running actor wait for a given number of milliseconds. If your package performs a lengthy operation, especially using its own actor, you can call CheckAbort periodically to see if the user has tried to stop the operation.
If you are about to perform an action that causes a large amount of memory to be allocated, you can test whether there is enough free memory available by calling PreflightNear before performing the action. When you call PreflightNear, Magic Cap will try to allocate the given amount of memory, then return a boolean result indicating whether the allocation succeeded. If the memory was allocated successfully, it is immediately released.
You can call FillBoxToBox to draw zooming boxes that ramp between the given sizes. When you call FillBoxToBox, you can specify an iterator function that will be called after every box is drawn.
Call InvertBoolean to easily invert a boolean field of a given object.
For more information, see the following topics in Magic Cap Class and Method Reference:
class Utilities
operations and attributes:
AccumulateCRC32 CalcCRC32 CheckAbort CompareBytes DelayMilliseconds EqualMem FillBoxToBox FlipNameIfLastFirst HashBytes HashCString HashPtrLenString HashText IndexicalToString InvertBoolean LastNameIfFirstLast MakeSearchText PermidRedraw PermitIdle PreflightNear ReseedRandom ShortRandom TextHash TextToInitials TypeSize ValueToText ZeroLongs
ZeroMem
Book Contents Previous Chapter