String Functions

String Functions


This section provides the definitions for string handling functions.

ChrCmpI
StrCatN
StrChr
StrChrI
StrCmpN
StrCmpNI
StrCpyN
StrCSpn
StrCSpnI
StrDup
StrFormatByteSize
StrFromTimeInterval
StrIntlEqN
StrIntlEqNI
StrIsIntlEqual
StrNCat
StrNCmp
StrNCmpI
StrNCpy
StrPBrk
StrRChr
StrRStrI
StrSpn
StrStr
StrStrI
StrToInt
StrToIntEx
StrToLong
StrTrim

ChrCmpI

BOOL ChrCmpI(
    TCHAR c1,
    TCHAR c2
    );

Performs a comparison between two characters. The comparison is not case sensitive.

c1
First character to be compared.
c2
Second character to be compared.

StrChr

LPTSTR StrChr(
    LPCTSTR lpStart,
    WORD wMatch
    );

Searches a string for the first occurrence of a character that matches the specified character. The comparison is case sensitive.

lpStart
Address of the string to be searched.
wMatch
Character to be used for comparison.

The comparison assumes lpStart points to the start of a null-terminated string.

StrChrI

LPTSTR StrChrI(
    LPCTSTR lpStart,
    WORD wMatch
    );

Searches a string for the first occurrence of a character that matches the specified character. The comparison is not case sensitive.

lpStart
Address of the string to be searched.
wMatch
Character to be used for comparison.

The comparison assumes lpStart points to the start of a null-terminated string.

StrCmpN

int StrCmpN(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2,
    int nChar
    );   

#define StrNCmp StrCmpN

Compares a specified number of characters of two strings to determine if they are the same. The comparison is case sensitive. The StrNCmp macro differs from this function in name only.

lpStr1
Address of the first string to be compared.
lpStr2
Address of the second string to be compared.
nChar
Number of characters to be compared.

StrCmpNI

int StrCmpNI(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2, 
    int nChar
    );

#define StrNCmpI StrCmpNI

Compares a specified number of characters of two strings to determine if they are the same. The comparison is not case sensitive. The StrNCmpI macro differs from this function in name only.

lpStr1
Address of the first string to be compared.
lpStr2
Address of the second string to be compared.
nChar
Number of characters to be compared.

StrCpyN

LPTSTR StrCpyN(
    LPCTSTR psz1,
    LPCTSTR psz2, 
    int cchMax
    );

#define StrNCpy StrCpyN

Copies a specified number of characters from one string to another. The StrNCpy macro differs from this function in name only.

psz1
Address of the destination string.
psz2
Address of the source string.
cchMax
Number of characters to be copied, including the null.

Example:

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
  //String one
  char buffer_1[] = "ABCDEFG";
  char *lpStr1;
  lpStr1 = buffer_1;

  //String two
  char buffer_2[] = "HIJKLMN";
  char *lpStr2;
  lpStr2 = buffer_2;

  cout  <<  "The function StrCpyN will allow you to copy (n) numbers"
  <<  "\nof characters from the string 2 to string 1."
  <<  "\nString 1 is : "	<< lpStr1
  <<  "\nString 2 is : "	<< lpStr2
  <<  "\nCopy (n) from 2 onto 1" << endl;
cout  <<  StrCpyN(lpStr1,lpStr2,8)
}


OUTPUT:
- - - - - -
The function StrCpyN will allow you to copy (n) numbers
of characters from the string 2 to string 1.
String 1 is : ABCDEFG
String 2 is : HIJKLMN
Copy (n) from 2 onto 1 
HIJKLMN

StrCSpn

int StrCSpn(
    LPCTSTR lpStr,
    LPCTSTR lpSet
    );

Searches for the first occurrence of a substring within a string. The search method is case sensitive, and the NULL terminator is included within the search pattern match.

lpStr
Address of the null-terminated string to be searched.
lpSet
Address of the substring to search for.

StrCSpnI

int StrCSpnI(
    LPCTSTR lpStr,
    LPCTSTR lpSet
    );

Searches for the first occurrence of a substring within a string. The search method is not case sensitive, and the NULL terminator is included within the search pattern match.

lpStr
Address of the null-terminated source string to be searched.
lpSet
Address of the string to search for.

StrDup

LPTSTR StrDup( 
    LPCTSTR lpsz 
    );

Duplicates a string.

lpsz
Address of a constant null-terminated character string.

StrDup will allocate storage the size of the original string. If storage allocation is successful, the original string is copied to the duplicate string.

Example:

#include <windows.h>
#include <string.h>
#include <stdio.h>

void main( void )
{
   char buffer[] = "This is the buffer text";
   char *newstring;
   printf( "Original: %s\n", buffer );
   newstring = StrDup( buffer );
   printf( "Copy:     %s\n", newstring );
   free( newstring );
}

   OUTPUT:
   - - - - - - 
   Original: This is the buffer text
   Copy:     This is the buffer text

Note This function uses LocalAlloc to allocate storage space for the copy of the string. The calling application must free this memory by calling the LocalFree function on the pointer returned by the call to StrDup.

StrFormatByteSize

LPTSTR StrFormatByteSize(
    DWORD dw,
    LPSTR pszBuf, 
    UINT cchBuf
    );

Converts a numeric value into a string that represents the number expressed as a size value in bytes, KB, MB, or GB, depending on the size.

dw
Numeric value to be converted.
pszBuf
Address of the converted string.
cchBuf
Size of pszBuf, in characters.

Example:


       532 -> 532 bytes
      1340 -> 1.3KB
     23506 -> 23.5KB
   2400016 -> 2.4MB
2400000000 -> 2.4GB

StrFromTimeInterval

int StrFromTimeInterval(
    LPSTR pszOut,
    UINT cchMax,
    DWORD dwTimeMS,
    int digits
    );

Converts a given time interval, in milliseconds, to a string.

pszOut
Address of a character buffer that receives the converted string.
cchMax
Size of pszOut, in characters.
dwTimeMS
Time interval in milliseconds.
digits
Minimum number of digits to be converted.

Example:

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
	char TimeString[256];
	char *pszOut;
	pszOut = TimeString;


cout << "The return value from the call to"
	 << "\nthe function StrFromTimeInterval will"
	 << "\nreturn the number of elements in the buffer: " << endl;

cout << "\nThe return from StrFromTimeInterval is " 
     << StrFromTimeInterval(pszOut,30, 34000,30);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is " 
     << StrFromTimeInterval(pszOut,30, 74000,3);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is " 
     << StrFromTimeInterval(pszOut,30, 74000,2);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is " 
     << StrFromTimeInterval(pszOut,30, 74000,1)
     << "\nThe contents of the TimeString Buffer " << pszOut << endl;

}

OUTPUT:
- - - - -
The return value from the call to
the function StrFromTimeInterval will
return the number of elements in the buffer:

The return from StrFromTimeInterval is 7
The contents of the TimeString Buffer  34 sec
The return from StrFromTimeInterval is 13
The contents of the TimeString Buffer  1 min 14 sec
The return from StrFromTimeInterval is 13
The contents of the TimeString Buffer  1 min 10 sec
The return from StrFromTimeInterval is 6
The contents of the TimeString Buffer  1 min

StrIsIntlEqual

BOOL StrIsIntlEqual(
    BOOL fCaseSens, 
    LPCTSTR lpString1, 
    LPCTSTR lpString2,
    int nChar
    );

#define StrIntlEqN(s1, s2, nChar) StrIsIntlEqual(TRUE, s1, s2, nChar)
#define StrIntlEqNI(s1, s2, nChar) StrIsIntlEqual(FALSE, s1, s2, nChar)

Compares a specified number of characters in two strings to determine if they are equal. This function allows you to set the case sensitivity for the search. The StrIntlEqN and StrIntlEqNI macros can be used to call this function. StrIntlEqN performs the comparison with case sensitivity, and StrIntlEqNI performs the comparison without case sensitivity.

fCaseSens
Determines the case sensitivity of the comparison. If this value is nonzero, the comparison is case sensitive. If this value is zero, the comparison is not case sensitive.
lpString1
Address of the first string to be compared.
lpString2
Address of the second string to be compared.
nChar
Number of characters to compare.

StrNCat

LPTSTR StrNCat(
    LPTSTR front,
    LPCTSTR back,
    int cchMax
    );

#define StrCatN StrNCat

Copies and appends a specified number of characters from one string onto the end of another string. The StrCatN macro differs from this function in name only.

front
Address of the string to which the characters will be copied.
back
Address of the string to be copied.
cchMax
Number of characters to copy.

StrPBrk

LPTSTR StrPBrk(
    LPCTSTR psz,
    LPCTSTR pszSet
    );

Searches a string for the first occurrence of a character contained in a specified buffer. This search does not include the null terminator.

psz
Address of the string to be searched.
pszSet
Address of a null-terminated character buffer that contains the characters for which to search.

StrRChr

LPTSTR StrRChr(
    LPCTSTR lpStart,
    LPCTSTR lpEnd,
    WORD wMatch
    );

Searches a string for the last occurrence of a character that matches the specified character. The comparison is case sensitive.

lpStart
Address of the string to be searched.
lpEnd
Points to the end of the string to be searched. The character at this location in the buffer is not included in the search.
wMatch
Character to be used for comparison.

The comparison assumes that lpEnd points to the end of the string.

StrRStrI

LPTSTR StrRStrI(
    LPCTSTR lpSource,
    LPCTSTR lpLast,
    LPCTSTR lpSrch
    );

Searches for the last occurrence of a substring within a string. The comparison is not case sensitive.

lpSource
Address of the null-terminated source string.
lpLast
Address of where to search from in the source string.
lpSrch
Address of the string to search for.

StrSpn

int StrSpn(
    LPCTSTR psz,
    LPCTSTR pszSet
    );

Obtains the length of a substring within a string that consists entirely of characters contained in a specified buffer.

psz
Address of the string that is to be searched.
pszSet
Address of a null-terminated character buffer that contains the set of characters for which to search.

StrStr

LPTSTR StrStr(
    LPCTSTR lpFirst,
    LPCTSTR lpSrch
    );

Finds the first occurrence of a substring within a string. The comparison is case sensitive.

lpFirst
Address of the string being searched.
lpSrch
Substring to search for.

StrStrI

LPTSTR StrStrI(
    LPCTSTR lpFirst,
    LPCTSTR lpSrch
    );

Finds the first occurrence of a substring within a string. The comparison is not case sensitive.

lpFirst
Address of the string being searched.
lpSrch
Substring to search for.

StrToInt

int StrToInt( 
    LPCTSTR lpSrc 
    );

#define StrToLong StrToInt

Converts a decimal string to an integer. The StrToLong macro differs from this function in name only.

lpSrc
Address of the null-terminated string to be converted.

StrToIntEx

BOOL StrToIntEx(
    LPCTSTR pszString,
    DWORD dwFlags,
    int FAR * piRet
    );

Converts a decimal or hexadecimal string to an integer.

pszString
Address of a null-terminated string to be converted.
dwFlags
Specifies if pszString contains a decimal or hexadecimal value. This can be one of the following values:
STIF_DEFAULT pszString contains a decimal value.
STIF_SUPPORT_HEX pszString contains a hexadecimal value.
piRet
Address of an integer variable that receives the converted string.

StrTrim

BOOL StrTrim(
    LPTSTR psz,
    LPCTSTR pszTrimChars
    );

Removes (trims) any leading and trailing characters from a string.

psz
Address of a string buffer that contains the string to be trimmed.
pszTrimChars
Address of an array of characters that will be trimmed from psz. The last element in this array must be zero.

Example:

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
  //String one
  TCHAR buffer[] = TEXT("_!ABCDEFG#");
  TCHAR trim[] = TEXT("#A!_\0");

  cout  <<  "The string before calling StrTrim: ";
  cout  <<  buffer;
  cout  <<  "\n";

  StrTrim(buffer, trim);

  cout  <<  "The string after calling StrTrim: ";
  cout  <<  buffer;
  cout  <<  "\n";

}

OUTPUT:
- - - - - -
The string before calling StrTrim: _!ABCDEFG#
The string after calling StrTrim: BCDEFG

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.