Memory Manipulation
Technical Notes
Overview
Copying Non-Overlapping Blocks
Copying Overlapping Blocks
Comparing Blocks
Converting Character Case in a Block
Initializing a Block
Counting Matching Characters in a Block
Searching for Characters in a Block
Searching for One Block Within Another
Skipping Space Characters in a Block
Reversing the Order of Characters in a Block
This unit contains functions which operate on chunks of memory. For documentation purposes, these chunks are called blocks. This unit includes functions which do the following: copy, compare, and initialize blocks; convert the case of characters within a block; search for characters within a block; search for a sub-block within a block; reverse the order of characters in a block; advance a block pointer past white space characters in a block; and determine the number of characters at the beginning of a block which match (or mismatch) a given set of characters.
Functions which follow the _mem_... naming convention use near blocks in small data models and far blocks in large data models. Each of these _mem_... functions has a far counterpart with an _fmem_... naming convention. The _fmem_... functions are identical to their _mem_... counterparts except that they work on far blocks in small data models. These functions are provided to make it possible to use relative and far heaps in small data models without changing to a large data model. The _mem_... and _fmem_... versions of any given function are unique only in the small data models. Either version of a given function calls the same underlying code in the large data models. Because this is the only distinction between the two types of functions, only the _mem_... functions are described below.
All of the memory manipulation functions are character oriented. Note that the CPU direction flag must be clear before calling any of these functions. (Most C programs never modify the direction flag, but if the direction flag is set, the results are undefined.)
- _mem_ccpy
- Copies the contents of a block to another location, up to a given character or a maximum number of characters.
- _mem_cpy
- Copies the contents of a block to another location.
- _mem_cpye
- Copies the contents of a block to another location and returns the address of the end of the destination block.
- _mem_swab
- Copies the contents of a block to another location after swapping adjacent even and odd numbered bytes.
These functions copy blocks from one location to another when the locations do not overlap; some functions support limited overlap. These functions do not perform bounds checking. The destination block must be large enough to hold the copied characters or data following the destination block will be overwritten.
- _mem_mov
- Copies the contents of a block to another location.
This function copies blocks from one location to another location when the source and destination blocks could overlap. Because this function checks for overlap and compensates for it, it is more involved than its _mem_cpy... counterpart. Overlapping is only supported if the source and destination segments are identical. These functions do not perform bounds checking. The destination block must be large enough to hold the copied characters or data following the destination block will be overwritten.
- _mem_cmp
- Compares one block to another.
- _mem_cmpi
- Compares one block to another, ignoring case.
These functions compare two blocks of memory which are identical in size. The comparison starts with the first character in each block and continues until corresponding characters differ or until all characters have been compared. The result of the comparison is the result of the final character comparison. If all characters are identical, the blocks are "equal". _mem_cmp compares the characters in each block directly; _mem_cmpi compares the characters, ignoring the case of ASCII alphabetic characters.
- _mem_lwr
- Converts uppercase characters in a block to lowercase.
- _mem_upr
- Converts lowercase characters in a block to uppercase.
These functions case-convert all ASCII alphabetic characters in a block. All other characters in the block remain unchanged. Note that IBM PC international characters (codes greater than 128) are not affected by these functions.
- _mem_set
- Sets all characters in a block to a specified character.
This function initializes a block of memory by setting every character in the block to a specified value.
- _mem_cspn
- Determines the number of characters at the beginning of a block which do not match any character in a given character set.
- _mem_spn
- Determines the number of characters at the beginning of a block which match any character in a given character set.
These functions determine the number of characters at the front of a block which match (or mismatch) any character in a given set of characters. Because NULL (0x00) can be a legitimate character in a block, ASCIIZ strings cannot be used to specify character sets. Instead, the character set is identified using a list of characters prefixed with a byte character count, as shown in the following example:
char *charset = "\3abc"+1;
- _mem_chr
- Searches a block for the first occurrence of a character.
- _mem_chri
- Searches a block for the first occurrence of a character, ignoring case.
- _mem_chrn
- Searches a block for the first occurrence of a character which is not the given character.
- _mem_chrni
- Searches a block for the first occurrence of a character which is not the given character, ignoring case.
- _mem_pbrk
- Searches a block for the first occurrence of any character which is in a set of characters.
- _mem_pbrkn
- Searches a block for the first occurrence of any character which is not in a set of characters.
These functions locate particular characters in a block. Some of these functions search for a specified character, some search for a character which does not match a specified character, and some look for a character matching (or mismatching) a set of characters. All of these functions return a pointer to the matching (or mismatching) character. The function names use the following naming convention: "chr" indicates that the function searches for a character; "n" indicates that the function searches for the first character that is not the specified character; and "i" indicates that the case of ASCII characters is ignored.
- _mem_mem
- Searches a block for the first occurrence of the contents of another block.
- _mem_memi
- Searches a block for the first occurrence of another block, ignoring case.
These functions search a block for a sequence of characters which exactly match a sequence of characters in another block. If a match is found, a pointer is returned to the beginning of the matching sequence of characters in the block which is being searched. These functions also indicate whether or not a partial match was found when the end of the search block was encountered; this allows the search to be continued in subsequent blocks.
- _mem_skips
- Skips past all space characters in a block.
- _mem_skipw
- Skips past all whitespace characters in a block.
These functions skip white space characters at the front of a block. The _mem_skips... functions skip space and tab characters; the _mem_skipw... functions skip space, tab, carriage return, and linefeed characters.
- _mem_rev
- Reverses the order of the bytes in a block.
This function reverses the order of the characters in a block. For example, these functions would transform "123456789" to "987654321".