NSPR Reference: Chapter 19 BitMaps
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 19 BitMaps

This chapter describes the bitmap type and the functions for manipulating the bitmap type.

Bitmap Type
Bitmap Functions and Macros
Logarithmic Functions and Macros

## Bitmap Type

The `prbitmap_t` type represents a bitmap structure.

#### prbitmap_t

Represents a bitmap.

##### syntax

    #include <prbit.h>

    typedef unsigned long prbitmap_t;

##### description

Use `prbitmap_t` as an array to define a bitmap.

## Bitmap Functions and Macros

The API defined for bitmaps is consistent across all platforms. The bitmap macros are:

`PR_TEST_BIT``
` `PR_SET_BIT``
` `PR_CLEAR_BIT```

Logarithmic functions and macros are also defined in the bitmap API, but are not limited to use with bitmaps. See Logarithmic Functions and Macros.

#### PR_TEST_BIT

Tests a bit within a bitmap array.

##### Syntax

    #include <prbit.h>

    PRIntn PR_TEST_BIT (
       prbitmap_t *_map,
       PRInt32 _bit);

##### Parameter

The macro has these parameters:

_map | Address of the bitmap containing the bit to be tested.
`_bit` | The relative position within the bitmap of the bit to be tested.

##### Returns

Non-zero if the bit is on, otherwise zero.

##### Description

This macro tests the bit at the specified relative position within the specified bitmap. The macro evaluates to `TRUE` (non-zero) if the bit is set. If the bit is clear, the macro evaluates to zero.

#### PR_SET_BIT

Sets a bit within a bitmap array.

##### Syntax

    #include <prbit.h>

    void PR_SET_BIT (
       prbitmap_t *_map,
       PRInt32 _bit);

##### Parameter

The macro has these parameters:

`_map` | Address of the bitmap containing the bit to be set.
`_bit` | The relative position within the bitmap of the bit to be set.

##### Returns

Nothing.

##### Description

This macro sets the bit at the specified relative position in the specified bitmap to one.

#### PR_CLEAR_BIT

Clears a bit within a bitmap array.

##### Syntax

    #include <prbit.h>

    void PR_CLEAR_BIT (
       prbitmap_t *_map,
       PRInt32 _bit);

##### Parameter

The macro has these parameters:

`_map` | Address of the bitmap containing the bit to be cleared.
`_bit` | The relative position within the bitmap of the bit to be cleared.

##### Returns

Nothing.

##### Description

This macro sets the bit at the specified relative position in the specified bitmap to zero.

## Logarithmic Functions and Macros

The bitmap files also define these logarithmic functions and macros, that need not be used specifically with bitmaps:

`PR_CeilingLog2``
` `PR_FloorLog2``
` `PR_CEILING_LOG2``
` `PR_FLOOR_LOG2```

#### PR_CeilingLog2

Returns the ceiling of log2 of a number.

##### Syntax

    #include <prbit.h>

    PRIntn PR_CeilingLog2 (PRUint32 i);

##### Parameter

The function has this parameter:

`i` | An unsigned 32-bit number.

##### Returns

Ceiling of log2 of `i`.

##### Description

This function takes the log2 of the specified 32-bit integer, and returns the smallest integer that is greater than or equal to it. This is the same as the C operation `Ceil(Log2(i));`

##### Example

    PRIntn j = PR_CeilingLog2( 32 ); /* After execution, j == 5 */

#### PR_FloorLog2

Returns the floor of log2 of a number.

##### Syntax

    #include <prbit.h>

    PRIntn PR_FloorLog2 (PRUint32 i);

##### Parameter

The function has this parameter:

`i` | An unsigned 32-bit number.

##### Returns

Floor of log2 of `i`.

##### Description

This function takes the log2 of the specified 32-bit integer, and returns the largest integer that is less than or equal to it. This is the same as the C operation `Floor(Log2(i));`

#### PR_CEILING_LOG2

Returns ceiling of log2 of a number in a variable.

##### Syntax

    #include <prbit.h>

    void PR_CEILING_LOG2 (
       PRUint32 _log,
       PRUint32 i);

##### Parameter

The macro has these parameters:

`_log` | A variable that will contain the result of the operation.
`i` | An unsigned 32-bit number.

##### Returns

Nothing.

##### Description

This macro takes the log2 of the specified 32-bit integer, and finds the smallest integer that is greater than or equal to it. The result is bound to the variable `_log`. The parameters must be variables of the proper type predefined by the caller.

#### PR_FLOOR_LOG2

Returns floor of log2 of a number in a variable.

##### Syntax

    #include <prbit.h>

    void PR_FLOOR_LOG2 (
       PRUint32 _log,
       PRUint32 i);

##### Parameter

The macro has these parameters:

`_log` | A variable that will contain the result of the operation.
`i` | An unsigned 32-bit number.

##### Returns

Nothing.

##### Description

This macro takes the log2 of the specified 32-bit integer, and finds the largest integer that is less than or equal to it. The result is bound to the variable `_log`. The parameters must be variables of the proper type predefined by the caller.

Previous Contents Next

Last Updated May 18, 2001