stafstring.h

Software Testing Automation Framework (STAF)的开发代码

/*****************************************************************************/
/* Software Testing Automation Framework (STAF)                              */
/* (C) Copyright IBM Corp. 2001                                              */
/*                                                                           */
/* This software is licensed under the Common Public License (CPL) V1.0.     */
/*****************************************************************************/

#ifndef STAF_String
#define STAF_String

#include "STAFError.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Begin C language definitions */

typedef struct STAFStringImplementation *STAFString_t;
typedef const struct STAFStringImplementation *STAFStringConst_t;


typedef enum STAFUTF8Char_e
{
    kUTF8_NULL     =  0,   /* Single byte null                               */
    kUTF8_SPACE    =  1,   /* Space                                          */
    kUTF8_LCURLY   =  2,   /* Left curly brace                               */
    kUTF8_RCURLY   =  3,   /* Right curly brace                              */
    kUTF8_LPAREN   =  4,   /* Left parenthesis                               */
    kUTF8_RPAREN   =  5,   /* Right parenthesis                              */
    kUTF8_LANGLE   =  6,   /* Left angle bracket (a.k.a, less than sign)     */
    kUTF8_RANGLE   =  7,   /* Right angle bracket (a.k.a, greater than sign) */
    kUTF8_COLON    =  8,   /* Colon                                          */
    kUTF8_SCOLON   =  9,   /* Semi-colon                                     */
    kUTF8_COMMA    = 10,   /* Comma                                          */
    kUTF8_PERIOD   = 11,   /* Period                                         */
    kUTF8_BSLASH   = 12,   /* Back-slash                                     */
    kUTF8_SLASH    = 13,   /* Slash (a.k.a., forward-slash)                  */
    kUTF8_EQUAL    = 14,   /* Equal sign                                     */
    kUTF8_SQUOTE   = 15,   /* Single quote (a.k.a., apostrophe)              */
    kUTF8_DQUOTE   = 16,   /* Double quote                                   */
    kUTF8_VBAR     = 17,   /* Vertical bar (a.k.a., pipe)                    */
    kUTF8_NULL2    = 18,   /* Double-byte null                               */
    kUTF8_POUND    = 19,   /* Pound sign (a.k.a. number sign or hash)        */
    kUTF8_CR       = 20,   /* Carriage return                                */
    kUTF8_LF       = 21,   /* Line feed                                      */
    kUTF8_STAR     = 22,   /* Star (a.k.a, asterisk)                         */
    kUTF8_HYPHEN   = 23,   /* Hyphen (a.k.a., dash)                          */
    kUTF8_PERCENT  = 24,   /* Percent sign                                   */
    kUTF8_QUESTION = 25,   /* Question mark                                  */
    kUTF8_CARET    = 26,   /* Caret (^)                                      */
    kUTF8_AMP      = 27,   /* Ampersand (&)                                  */
    kUTF8_AT       = 28,   /* At (@)                                         */
    kUTF8_TAB      = 29,   /* Tab                                            */
    kUTF8_BANG     = 30    /* Bang (a.k.a, exclaimation mark)                */
} STAFUTF8Char_t;

typedef enum STAFUTF8CharType_e
{
    kUTF8_TYPE_SPACE = 0, kUTF8_TYPE_WHITESPACE = 1,
    kUTF8_TYPE_ASCII = 2, kUTF8_TYPE_DIGIT      = 3
} STAFUTF8CharType_t;

typedef enum STAFStringCaseSensitive_e
{
    kSTAFStringCaseInsensitive = 0,
    kSTAFStringCaseSensitive = 1
} STAFStringCaseSensitive_t;


/***********************************************************************/
/* STAFStringConstruct - Creates a STAFString from buffer of size len  */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A pointer to a buffer of UTF-8 chars                 */
/*          (In)  The length of the buffer                             */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstruct(STAFString_t *pString,
                             const char *buffer,
                             unsigned int len,
                             unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructCopy - Creates a STAFString from a STAFString    */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A STAFString_t                                       */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructCopy(STAFString_t *pString,
                                 STAFStringConst_t aString,
                                 unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructFromCurrentCodePage - Creates a STAFString from  */
/*                                          a buffer of size len con-  */
/*                                          sisting of current code-   */
/*                                          page characters            */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A pointer to a buffer of local codepage chars        */
/*          (In)  The length of the buffer                             */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructFromCurrentCodePage(
                                             STAFString_t *pString,
                                             const char *from,
                                             unsigned int len,
                                             unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructFromUInt - Creates a STAFString from an unsigned */
/*                               integer                               */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  The value to be represented as a string              */
/*          (In)  The base in which to represent the value [1..16]     */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructFromUInt(STAFString_t *pString,
                                     unsigned int value,
                                     unsigned int base,
                                     unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructSubString - Creates a substring of a STAFString  */
/*                                with index and len refering to ei-   */
/*                                ther UTF-8 chars (0) or bytes (1)    */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A STAFString_t                                       */
/*          (In)  The index of the char or byte to start from          */
/*          (In)  Len of chars or bytes to get from string             */
/*          (In)  0->index/len are in chars; 1->index/len are in bytes */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructSubString(STAFString_t *pSubStr,
                                      STAFStringConst_t aString,
                                      unsigned int index,
                                      unsigned int len,
                                      unsigned int corb,
                                      unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructSubWord - Creates a subword string from a        */
/*                              STAFString                             */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A STAFString_t                                       */
/*          (In)  The starting word from the string (0 based)          */
/*          (In)  The number of words to retrieve (0 meaning all)      */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructSubWord(STAFString_t *pWord,
                                    STAFStringConst_t aString,
                                    unsigned int index,
                                    unsigned int count,
                                    unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructChar - Creates a string of length 1 representing */
/*                           a specified character in UTF8             */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  A STAFString_t                                       */
/*          (In)  The starting word from the string (0 based)          */
/*          (In)  The number of words to retrieve (0 meaning all)      */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructChar(STAFString_t *pChar,
                                 STAFUTF8Char_t aChar,
                                 unsigned int *osRC);

/***********************************************************************/
/* STAFStringConstructJoin - Creates a STAFString by joining all of    */
/*                           the strings in an array                   */
/*                                                                     */
/* Accepts: (Out) A pointer to a STAFString_t                          */
/*          (In)  An array of STAFString_t                             */
/*          (In)  The size of the array                                */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */
/***********************************************************************/

STAFRC_t STAFStringConstructJoin(STAFString_t *pString,
                                 STAFString_t aStringArray[],
                                 unsigned int arraySize,
                                 unsigned int *osRC);

/***********************************************************************/
/* STAFStringNumOfWords - Returns the number of words in a STAFString  */
/*                                                                     */
/* Accepts: (In)  A STAFString_t                                       */
/*          (Out) The number of words                                  */
/*          (Out) A pointer to an OS return code (may be NULL)         */
/*                                                                     */
/* Returns: kSTAFOk on success                                         */
/*          other on error                                             */