Parse Library Module

The parse library module has the file name parse.c. This module performs string manipulation and word parsing.

Note that most word oriented functions have two levels. The higher level functions operate on space delimited words and the low level functions (whose names begin with ll_ [el el]) operate on a word string delimited by any character.

Here is a list of functions in the parse library module:

- trim
- word
- ll_word
- wordlen
- ll_wordlen
- indxword
- ll_indxword
- words
- ll_words
- command_words
- command_word
- command_indxword
- command_wordlen
- sub_string
- getyn
- command_worddel
- worddel
- ll_worddel
- ll_wordput
- num
- ucase
- parse_extend
- initstring
- inittstring
- initqstring
- delbytes
- qatoi
- qatol
- stricmp
- strnicmp
- logic_string_to_flag
- flag_2_logic_string
- pmatch
- lpad
- rpad
- strip_space

# Module Dependencies

You can compile this module and place the object code into a library and link the library into your program. You can also just include this module into your make routine. No other modules are required in order to use this parse module.

# Module Header Files

This module requires the header file parse.h which is automatically included from the header file enhlib.h which is automatically included from header file stdhead.h.

# Module Functions

## trim

    Prototype  : void trim(char *instr, char *outstr)
    Parameters :
          Name : instr
    Description: input string

          Name : outstr
    Description: output string

This function takes the input string, removes leading, tailing, and intra-word spacing and places the result into the output string which must already be allowed to sufficient size.

This trim function is not like most trim functions in that extraneous spaces are removed from the beginning, end and also between each word in the string.

## word

    Prototype   : int word(char *instr, char *outstr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : word number

    Returns     : TRUE if extraction was successful, FALSE otherwise

This function will extract a specific space delimited word from the input string and place it into the output string which must already be allocated to sufficient size.

## ll_word

    Prototype   : int ll_word(char *instr, char *outstr, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : TRUE if extraction was successful, FALSE otherwise

This function will extract a specific word delimited by any character and place it into the output string which must already be allocated to sufficient size.

## wordlen

    Prototype   : int wordlen(char *instr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : word number

    Returns     : word length upon success, -1 otherwise

This function will determine the length (in characters) of a specific space delimited word in the input string.

Note that it is valid to have a word of zero characters.

## ll_wordlen

    Prototype   : int ll_wordlen(char *instr, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : word length upon success, -1 otherwise

This function will determine the length (in characters) of a specific word delimited by a specific character in the input string.

Note that it is valid to have a word of zero characters.

## indxword

    Prototype   : int indxword(char *instr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : word number

    Returns     : word position/index upon success, -1 otherwise

This function will determine the position/index of a specific space delimited word within the input string.

Note that the returned index is base zero (first position is zero) to conform to C's array indexing.

## ll_indxword

    Prototype   : int ll_indxword(char *instr, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : word position/index upon success, -1 otherwise

This function will determine the position/index of a specific word delimited by a specific character within the input string.

Note that the returned index is base zero (first position is zero) to conform to C's array indexing.

## words

    Prototype   : int words(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : number of words upon success, zero otherwise

This function counts the number of space delimited words in the input string.

## ll_words

    Prototype   : int ll_words(char *instr, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : delim
    Description : word delimiter

    Returns     : number of words upon success, zero otherwise

This function counts the number of words delimited by a specific character within the input string.

## command_words

    Prototype   : int command_words(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : number of command words upon success, zero otherwise

This function will count the number of command words within the input string.

## command_word

    Prototype   : int command_word(char *instr, char *outstr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : command word number

    Returns     : TRUE if the extraction was successful, FALSE otherwise

This function will extract a specific command word from the input string.

## command_indxword

    Prototype   : int command_indxword(char *instr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : command word number

    Returns     : position/index of the command word upon success, -1 otherwise

This function will determine the position or index of a specific command word within the input string.

Note that the returned index is base zero (first position is zero) to conform to C's array indexing.

## command_wordlen

    Prototype   : int command_wordlen(char *instr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : which
    Description : command word number

    Returns     : the length upon success, -1 otherwise

This function determines the length of a specific command word within the input string.

Note that it is valid to have a word of zero characters.

## sub_string

    Prototype   : int sub_string(char *instr, char *sub)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : sub
    Description : sub-string

    Returns     : position/index upon success, -1 otherwise

This function searches the input string for a sub-string.

Note that the returned index is base zero (first position is zero) to conform to C's array indexing.

## getyn

    Prototype   : int getyn(char *prompt)
    Parameters  :
          Name  : prompt
    Description : prompt string

    Returns     : TRUE if yes, FALSE if no

This function will display the prompt string and wait for a user yes or no response. No other response is allowed. Function will not exit until a valid response is received.

## command_worddel

    Prototype   : int command_worddel(char *instr, char *outstr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : command word number

    Returns     : TRUE upon success, FALSE otherwise

This function will delete a specific command word within the input string and load the result into the output string.

## worddel

    Prototype   : int worddel(char *instr, char *outstr, int which)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : word number

    Returns     : TRUE upon success, FALSE otherwise

This function will delete a specific space delimited word from the input string and load the this into the output string which must already be allocated to sufficient size.

## ll_worddel

    Prototype   : int ll_worddel(char *instr, char *outstr, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : TRUE upon success, FALSE otherwise

This function will delete a specific word from the input string based on a specific word delimiter. The output string must already be allocated to sufficient size.

## ll_wordput

    Prototype   : int ll_wordput(char *instr, char *outstr, char *wdata, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : wdata
    Description : word data

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : TRUE upon success, FALSE otherwise

This function will place the word data into the input string at the specific word. If the specific word already exists, it will be replaced, if does not exist, the word string will be extended out to the required word before copying. Each word is delimited by the word delimiter. The new string will be returned in the output string upon success. The output string must be already allocated large enough to hold the result string.

## num

    Prototype   : int num(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : TRUE if a number, FALSE otherwise

This function evaluates the input string to determine whether it is a valid number. Numbers are the digits 0-9. A minus sign is allowed in the first character. No other characters are allowed.

## ucase

    Prototype   : void ucase(char *instr, char *outstr)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

This function will convert the input string to uppercase and copy the string to the output string which must already be allocated to sufficient size.

## parse_extend

    Prototype   : int parse_extend(char *instr, char *outstr, int which, char delim)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : which
    Description : word number

          Name  : delim
    Description : word delimiter

    Returns     : TRUE upon success, FALSE otherwise

This function will extend the input string out to the requested word. Each word is delimited by the word delimiter. You may not extend using the space delimiter because of the nature of the space and the trim function. The output string must already be allocated to sufficient size.

## initstring

    Prototype   : char *initstring(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : pointer to output string upon success, NULL otherwise

This function will create a copy of the input string and return a pointer to the copy. The copy is created using dynamic memory allocation and it is the callers responsibility to de-allocate the memory used.

## inittstring

    Prototype   : char *inittstring(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : pointer to output string upon success, NULL otherwise

This function will create a trimed copy of the input string and return a pointer to the copy. The copy is created using dynamic memory allocation and it is the callers responsibility to de-allocate the memory used.

## initqstring

    Prototype   : char *initqstring(char *instr)
    Parameters  :
          Name  : instr
    Description : input string

    Returns     : pointer to output string upon success, NULL otherwise

This function will create a quoted copy of the input string (if the input string contains more than one word) and return a pointer to the copy. If the input string does not contain more than one word, the output copy will not be quoted. Quoted strings contain matching single quotes. The copy is created using dynamic memory allocation and it is the callers responsibility to de-allocate the memory used.

## delbytes

    Prototype   : int delbytes(char *instr, char *outstr, int pos, int numbytes)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : outstr
    Description : output string

          Name  : pos
    Description : position/index

          Name  : numbytes
    Description : number of bytes

    Returns     : TRUE upon success, FALSE otherwise

This function will delete the number of bytes from the input string starting from the given position and place the result into the output string which must already be allocated to a sufficient size. The number of bytes may be zero which indicates from the position for the remainder of the string.

## qatoi

    Prototype   : int qatoi(char *instr, int *numval)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : numval
    Description : converted value

    Returns     : TRUE upon success, FALSE otherwise

This function will convert a number in the input string to an integer. This function differs from the standard C library function atoi in the sense that non-numeric characters (other than the minus sign) are not allowed.

## qatol

    Prototype   : int qatol(char *instr, long *numval)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : numval
    Description : converted value

    Returns     : TRUE upon success, FALSE otherwise

This function will convert a number in the input string to a long integer. This function differs from the standard library function atol in the sense that non-numeric characters (other than the minus sign) are not allowed.

## stricmp

    Prototype   : int stricmp(char *s1, char *s2)
    Parameters  :
          Name  : s1
    Description : first input string

          Name  : s2
    Description : second input string

    Returns     : same values as the standard library function strcmp

This function compares two strings case insensitive. This function not a standard ANSI C library function and is included in some compiler libraries and not included in others. The compilation of this function depends on the define HAS_STRICMP which is given in the header file stdhead.h. If your C standard library contains this function, make sure you have defined HAS_STRICMP either from the stdhead.h header file or from the compiler command line.

## strnicmp

    Prototype   : int strnicmp(char *s1, char *s2, int len)
    Parameters  :
          Name  : s1
    Description : first input string

          Name  : s2
    Description : second input string

          Name  : len
    Description : number of bytes to compare

    Returns     : same values as the standard library function strncmp

This function compares two strings case insensitive up to the given number of bytes. This function not a standard ANSI C library function and is included in some compiler libraries and not included in others. The compilation of this function depends on the define HAS_STRICMP which is given in the header file stdhead.h. If your C standard library contains this function, make sure you have defined HAS_STRICMP either from the stdhead.h header file or from the compiler command line.

## logic_string_2_flag

    Prototype   : int logic_string_2_flag(char *instr, int *flag)
    Parameters  :
          Name  : instr
    Description : input string

          Name  : flag
    Description : converted flag

    Returns     : TRUE upon success, FALSE otherwise

This function converts a string representation of a flag or switch to an integer (boolean) flag value. The input string must be one of:

- yes
- no
- true
- false
- on
- off
- 0
- 1

String comparison is case insensitive.

## flag_2_logic_string

    Prototype   : int flag_2_logic_string(int flag, char *outstr)
    Parameters  :
          Name  : flag
    Description : input flag

          Name  : outstr
    Description : output logic string

    Returns     : TRUE upon success, FALSE otherwise

This function converts a boolean value to an English logic string. The input flag value must be either zero or one. The output logic string will be on for one and off for zero.

## pmatch

    Prototype   : int pmatch(char *pat, char *name)
    Parameters  :
          Name  : pat
    Description : pattern

          Name  : name
    Description : name or word to match

    Returns     : TRUE if a match was found, FALSE otherwise

This function will attempt to match the given name or word with the pattern. The pattern may include two wildcards:

    * - match all characters up to the next non-wildcard
    ? - match a single character

The match comparison is case sensitive.

## lpad

    Prototype   : void lpad(char *istr, char *ostr, int padlen, int padch)
    Parameters  :
          Name  : istr
    Description : input string

          Name  : ostr
    Description : output string

          Name  : padlen
    Description : desired padded length

          Name  : padch
    Description : pad character

This function will pad a string on the left with the pad character to the desired padded length. Function returns the padded string in the output string which must already be allocated to sufficient size by the caller.

## rpad

    Prototype   : void rpad(char *istr, char *ostr, int padlen, int padch)
    Parameters  :
          Name  : istr
    Description : input string

          Name  : ostr
    Description : output string

          Name  : padlen
    Description : desired padded length

          Name  : padch
    Description : pad character

This function will pad a string on the right with the pad character to the desired padded length. Function returns the padded string in the output string which must already be allocated to sufficient size by the caller.

## strip_space

    Prototype   : void strip_space(char *istr, char *ostr)
    Parameters  :
          Name  : istr
    Description : input string

          Name  : ostr
    Description : output string

This function will strip all spaces from the input string and place the result into the output string which must already be allocated to sufficient size by the caller.

Goto Top | GPL Software Overview | GPL Library
Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2006 Future Lab, Last Updated Jun 30, 2006