String Manipulation
Technical Notes
Overview
Determining String Lengths
Finding the Terminating NULL of a String
Copying Strings
Concatenating Strings
Comparing Strings
Converting Character Case in a String
Setting Characters in a String
Reversing the Characters in a String
Skipping Space Characters in a String
Aligning Strings
Removing Trailing Space Characters from a String
Counting the Number of Matching Characters in a String
Searching for Characters in a String
Locating Path Elements in a String
Tokenizing a String
This unit consists of functions which do the following: determine the length of strings; copy, concatenate, and compare strings; convert the case of characters in strings; search for characters in strings; search for sub-strings in strings; tokenize strings, and justify strings. This unit also includes functions which return a pointer to the end of a string, determine the number of characters in a string which match (or mismatch) characters in a specified character set, set the characters in a string to a specified character, reverse all the characters in a string, and return a pointer past any whitespace at the beginning of a string.
These functions operate on ASCIIZ strings (arrays of characters terminated with a NULL (0x00) character).
Functions which follow the _str_... naming convention operate on near strings in small data models and far strings in large data models. Each of these _str_... functions has a far counterpart with a _fstr_... naming convention. The _fstr_... functions are identical to their _str_... counterparts except that they work on far strings in both large and small data models. These functions are provided to make it possible to manipulate strings on relative and far heaps in small data models without changing to a large data model. The _str_... and _fstr_... 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 _str_... functions are described below.
The CPU direction flag must be clear before calling any of these functions. (Most C programs never modify the direction flag.)
- _str_len
- Returns the length of a string.
This function returns the length of a string. The terminating NULL character is never counted in the returned string length.
- _str_end
- Returns a pointer to the end of a string.
This function returns a pointer to the terminating NULL of a string.
- _str_cpy
- Copies a string to another location.
- _str_cpye
- Copies a string to another location and returns a pointer to the end of the copy.
- _str_ncpy
- Copies a portion of a string to another location.
These functions copy strings from one location to another. The buffer receiving the copy must be large enough to hold it or data following the buffer will be overwritten. _str_cpy is used to copy an entire string including the terminating NULL. _str_ncpy copies a specified number of characters from the beginning of a string. The copy is NULL terminated. _str_cpye copies an entire string returning a pointer to the terminating NULL of the copy.
- _str_cat
- Appends one string to the end of another.
- _str_cate
- Appends one string to the end of another, returning a pointer to the end of the modified string.
- _str_ncat
- Appends a portion of one string to the end of another.
- _str_ncate
- Appends a portion of one string to the end of another, returning a pointer to the end of the modified string.
These functions append one string to the end of another string. There must be sufficient room for the target string to grow or data following that string will be overwritten. _str_cat appends an entire string to a target string. _str_ncat appends a specified number of characters from one string to a target string. A terminating NULL is placed at the end of the modified target string in both cases. _str_cate and _str_ncate are the same as _str_cat and _str_ncat except that they return a pointer to the end of the modified target string.
- _str_cmp
- Compares one string against another.
- _str_cmpi
- Compares one string against another, ignoring case.
- _str_ncmp
- Compares a portion of one string to a portion of another.
- _str_ncmpi
- Compares a portion of one string to a portion of another, ignoring case.
These functions compare strings by comparing corresponding string characters until differing characters are found or until the terminating NULL of one of the strings is reached. The result of the comparison depends on the relationship of the differing characters. For example, if the differing characters were "N" and "c," the second string would be greater than the first string since the value of "c" (99) is greater than the value of "N" (78). If no differing characters are found, the strings are equal. _str_cmp and _str_cmpi compare entire strings with and without case sensitivity. _str_ncmp and _str_ncmpi compare a specified number of string characters with and without case sensitivity.
- _str_lwr
- Converts uppercase characters in a string to lowercase.
- _str_upr
- Converts lowercase letters in a string to uppercase.
These functions convert the case of ASCII characters in a string. Any character other than an ASCII alpha character remains unaffected by these functions.
- _str_set
- Sets all characters in a string to a specified character.
- _str_nset
- Sets the first n characters of a string to a specified character.
These functions set all or some characters in a string to a specified character. The terminating NULL remains unaffected.
- _str_rev
- Reverses the order of the characters in a string.
This function reverses all the characters in a string, leaving the terminating NULL at the end of the modified string.
- _str_skips
- Skips past space characters in a string.
- _str_skipw
- Skips past whitespace characters in a string.
These functions skip whitespace characters at the front of a string. Each function skips a different set of whitespace characters.
- _str_center
- Centers a string within a buffer.
- _str_left
- Left justifies a string within a buffer.
- _str_right
- Right justifies a string within a buffer.
These functions left, center, or right justify a string within a specified string buffer. The alignment is performed using a specified pad character.
_str_center pads a string on the left and right with an equal number of specified pad characters. If an odd number of pad characters is required, the additional character is padded on the right.
_str_left left justifies a string within a buffer by padding on the right with a specified pad character.
_str_right right justifies a string within a buffer by padding on the left with a specified pad character.
- _str_trims
- Removes space characters from the end of a string.
- _str_trimw
- Removes whitespace characters from the end of a string.
These functions trim whitespace characters from the end of a string. Each function trims a different set of whitespace characters.
- _str_cspn
- Determines the number of characters at the beginning of a string which do not match any character in a given character set.
- _str_spn
- Determines the number of characters at the beginning of a string which match any character in a given character set.
These functions compute the size of the front of a string where all the characters match (or mismatch) characters in a given character set. The counting stops at the first mismatching (or matching) character or the terminating NULL of the string, whichever comes first.
- _str_chr
- Searches a string for the first occurrence of a character.
- _str_chri
- Searches a string for the first occurrence of a character, ignoring case.
- _str_chrn
- Searches a string for the first occurrence of a character which is not the given character.
- _str_chrni
- Searches a string for the first occurrence of a character which is not the given character, ignoring case.
- _str_pbrk
- Searches a string for the first occurrence of any character which is in a set of characters.
- _str_pbrkn
- Searches a string for the first occurrence of any character which is not in a set of characters.
- _str_rchr
- Searches a string for the last occurrence of a character.
- _str_rchri
- Searches a string for the last occurrence of a character, ignoring case.
- _str_rchrn
- Searches a string for the last occurrence of a character which is not the given character.
- _str_rchrni
- Searches a string for the last occurrence of a character which is not the given character, ignoring case.
These functions locate specified characters in a string. The functions come in two varieties: those which search for a specified character and those which search for a character that does not match a specified character. Also, some of these functions search from the beginning of the string and some search from the end. Some functions ignore ASCII character case while searching, and some look for a match (or mismatch) from another string of characters. All of these functions return pointers to the matching (or mismatching) characters in the string. The naming convention for these functions is as follows: "chr" indicates that the function searches for a character, "pbrk" indicates that the function searches for any character in a specified character set, "r" indicates reverse searching, "n" indicates not the specified character or character set, and "i" indicates ignoring of ASCII character case.
Searching for a Substring in a String
- _str_str
- Searches a string for the first occurrence of a substring.
- _str_stri
- Searches a string for the first occurrence of a substring, ignoring case.
These functions locate a substring within a string with and without case sensitivity. If the substring is found, a pointer is returned to the beginning of the substring in the string being searched.
- _str_drive
- Locates a drive specifier substring in a pathname string.
- _str_drvpath
- Locates a drive specifier and path substring in a pathname string.
- _str_ext
- Locates a filename extension substring in a string.
- _str_fname
- Locates a filename substring in a string.
- _str_fnamext
- Locates a filename/extension substring in a string.
- _str_path
- Locates a path substring in a string.
These functions locate and size elements in path/filename strings. Paths may be NULL, partial, or full paths including a drive specifier, path, filename, and extension. Each function returns a pointer to the start of the appropriate element and the length of that element. If the element being searched for is not present, a length of zero is returned and the returned string pointer indicates the expected position of the element in the string. Some of these functions require paths without filenames to be in internal path string format (see the File/Directory technical notes for an explanation of the internal path string format).
- _str_toks
- Initializes a string for subsequent tokenization by _str_tok.
- _str_tok
- Breaks a string into tokens by matching characters in the string with a set of delimiting characters.
These functions tokenize strings. They consider the input string to be a sequence of zero or more tokens with each token separated by one or more delimiting characters. The initializing function, _str_toks, accepts a pointer to the string of tokens. Subsequent calls to the tokenizing function, _str_tok, search the string for the next character which matches a specified set of delimiters. If a delimiter is found, it is replaced with a NULL character to mark the end of a token and a pointer is returned to the beginning of the token. Each subsequent call to _str_tok delimits and points to the next token in the string. Note that the original string is broken into tokens and is destroyed by _str_tok. _str_toks does not modify the string in any way.