Ingres CL ST
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - ST
Abstract
This is the specification of the ST facility provided by the compatibility library.
Revision: 1.2, 15-Dec-1997
Document History
- Revision 1.2, 15-Dec-1997
- Converted to html.
- Revision 1.1, 30-Jul-94.
- STindex length considered only if > 0, otherwise the string had better be terminated.
- The '%p' pointer format is added to STprintf (7-may-93).
- Revision 1.0, last modified 29-Aug-91.
- Fixed typos -- the < and > in STbcompare, STcompare, and STscompare were reversed!
Specification
Introduction
ST provides functions for working with null (EOS) terminated strings.
Length arguments are i4 and therefore strings are limited to 32K in length.
Source and destination addresses can overlap for the routines STcopy, STlcopy, STmove and STpolycat as long as the destination address is lower than the source address (copying proceeds from the beginning of the string to the end).
White space is defined as a sequence of characters for which the CMwhite macro is true.
These routines can be implemented in a system independent fashion.
Library
CL
Header File <st.h>
The header file <st.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
STalloc - create an allocated copy of a string
Allocate permanent storage for a null-terminated string. STalloc allocates permanent storage for the string, copies the contents of the string into the new storage area, and returns the pointer to this area.
Inputs:
| string | string to be copied |
Outputs:
| None |
Returns:
| pointer to storage for the string |
Definition:
char * STalloc(string) char *string;
STbcompare - compare strings to length, selective case sensitivity
Compare 2 strings lexically. If arguments a_length or b_length are nonzero, only examine strings up to min(a_length,length of a, b_length, length of b). Depending on setting of argument ignrcase, case is significant or not. The procedure is case sensitive if ignrcase is FALSE. Return value is <0 for (a < b), 0 for (a = b), >0 for (a > b). "ab" is less than "abc" if both input lengths are zero. "ab" is equal to "abc" if either length is non-zero.
Inputs:
| a | pointer to first string to compare |
| a_length | length of first string |
| b | pointer to second string to compare |
| b_length | length of second string |
| ignrcase | variable used to indicate whether comparison is case sensitive; 0 if case is sensitive. |
Outputs:
| None |
Returns:
| < 0 | if a lexically < b. |
| 0 | if a lexically == b. |
| > 0 | if a lexically > b |
Definition:
i4 STbcompare(a, a_length, b, b_length, ignrcase) char *a; i4 a_length; char *b; i4 b_length; i4 ignrcase;
STcat - concatenate strings
Concatenate 2 null-terminated strings. post is copied to a position starting at the end of pre. pre is assumed to be large enough. Return pointer to pre.
Inputs:
| pre | pointer to beginning of "prefix" string |
| post | pointer to beginning of "suffix" string |
Outputs:
| pre | pointer to beginning of composite string |
Returns:
| pointer to beginning of composite string |
Definition:
char * STcat(pre, post) char *pre; char *post;
STcompare - compare strings
Compare 2 strings lexically. Return value is <0 for (a < b), 0 for (a = b), >0 for (a > b). "ab" is less than "abc".
Inputs:
| a | pointer to first string to compare |
| b | - pointer to second string to compare |
Outputs:
| None |
Returns:
| < 0 | if a lexically < b. |
| 0 | if a lexically == b. |
| > 0 | if a lexically > b |
Definition:
i4 STcompare(a, b) char *a; char *b;
STcopy - copy string
Copy null-terminated string in source to dest and null terminate. See comment in the Description section at the beginning of the chapter about overlapping buffers.
Inputs:
| source | pointer to string to be copied |
Outputs:
| dest | pointer to buffer into which source string was copied |
Returns:
| None |
Definition:
VOID STcopy(source, dest) char *source; char *dest;
STequal - compare strings for equality
Return non-zero if the two strings are equal 0 otherwise. This routine will probably be implemented as a macro which compares the first two characters of the string, calling a function only if they compare equal, the intent being to avoid function call overhead.
Since the macro may expand its arguments multiple times, it is very important that this routine is never invoked with arguments which have side-effects, such as use of the "++" operator.
Inputs:
| s1 | one string to compare |
| s2 | another string to compare. |
Outputs:
| None |
Returns:
| 0 | if strings are not equal, non-zero otherwise. |
Definition:
i4 STequal (s1, s2) char *s1; char *s2;
STgetwords - parse string into words
Parse a string into words. A word is a sequence of non-white space characters, delimited by white space or the beginning or the end of the string. A sequence of characters delimited by single or double quotes and followed by white space is also a word. The caller supplies an array of character pointers, into which the starting address of each word is placed. The first (or only) white space character after each word is replaced by a null character. Count is set by the caller to the size of wordarray, and then by STgetwords to the number of words found.
Inputs:
| string | pointer to string to be passed |
| count | size of "wordarray" |
Outputs:
| count | number of words found |
| wordarray | array of character pointers holding starting address of each word. |
Returns:
| None |
Definition:
VOID STgetwords(string, count, wordarray) char *string; i4 *count; char **wordarray;
STindex - Find first occurrence of character in string
Find first occurrence of a character within another string. This must be an exact match.
Inputs:
| str | pointer to source string. |
| mstr | pointer to matching character. (Note that this is a string pointer to handle one or two byte characters). The first occurrence of this character within 'str' will be returned. |
| len | If > 0, limit search to first len bytes of 'str'. If <= 0, 'str' must be NULL terminated. |
Outputs:
| None |
Returns:
| pointer to starting point of 'mstr' within 'str' if found, or NULL if not found. |
Definition:
char * STindex(str, mstr, len) char *str; char *mstr; i4 len;
STlcopy - copy characters, length limited
Copy chars to buffer. Move l chars of string source (or all chars up to a null) to buffer dest. null terminate string in dest. Return length of result string. See comment in the Description section at the beginning of the chapter about overlapping buffers.
Inputs:
| source | pointer to characters to be copied |
| l | maximum number of characters to copy, if null not encountered first |
Outputs:
| dest | buffer into which ``source string was copied |
Returns:
| length of result string |
Definition:
i4 STlcopy(source, dest, l) char *source; char *dest; i4 l;
STlength - length of a string
Return length of string, up to but not including the terminating null character.
Inputs:
| string | pointer to the string |
Outputs:
| None |
Returns:
| length of string |
Definition:
i4 STlength(string) char *string;
STmove - copy/move string with padding
Move null-terminated string source to dest. If source is shorter than dlen, then source is copied to dest and dest is padded out to dlen with padchar. If the length of source is greater than dlen, then only dlen characters of source are copied to dest. The result (dest) is NOT null-terminated.
See comment in the Description section at the beginning of the chapter about overlapping buffers.
Inputs:
| source | pointer to string to be copied |
| padchar | character used to pad the output buffer if "source" is shorter than "dlen |
| dlen | number of characters to place into output buffer |
Outputs:
| dest | pointer to buffer into which "source" string was copied |
Returns:
| None |
Definition:
VOID STmove(source, padchar, dlen, dest) char *source; char padchar; i4 dlen; char *dest;
STnlength - limited string length
Find length of possibly null terminated string. If null not found after count characters, stop and return count.
Inputs:
| count | variable indicating maximum number of characters to examine for a null. |
| string | pointer to the string |
Outputs:
| None |
Returns:
| length of string or "count", whichever is less |
Definition:
i4 STnlength(count, string) i4 count; char *string;
STpolycat - multiple string concatenate
Concatenate n null-terminated strings into space supplied by the user and null terminate. Return pointer to result. See comment in the Description section at the beginning of the chapter about overlapping buffers.
Inputs:
| n | variable indicating the number of input strings |
| a | pointer to first input string |
| b | pointer to second input string |
Outputs:
| result | pointer to buffer containing concatenated strings |
Returns:
| pointer to buffer containing concatenated strings. |
Definition:
char * STpolycat(n, a, b, ...., result) i4 n; char *a; char *b; ... .. char *result;
STprintf - formatted print to character buffer
Similar to SIfprintf() except the output is placed in the character buffer pointed to by the first argument. Returns pointer to buf.
Inputs:
| buf | The character buffer that will contain the formatted output string. |
| fmt | The format string that controls output and conversion of the subsequent arguments. (See 'SIfprintf()'.) |
| args | A variable number of arguments of all types that will be converted and output. |
Outputs:
| buf | the character buffer that contains the formatted output string. |
Returns:
| pointer to character buffer containing the formatted output string. |
Definition:
char * STprintf(buf, fmt, args...) char *buf; char *fmt; ... . args;
STrindex - find last occurrence of character within string
Find last occurrence of a character within another string. This must be an exact match.
Inputs:
| str | pointer to source string. |
| mstr | pointer to matching character. (Note that this is a string pointer to handle one or two byte characters). The last occurrence of this character within 'str' will be returned. |
| len | If this is nonzero, limit search to first n bytes of &'str'. If 0, 'str' must be NULL terminated. |
Outputs:
| None |
Returns:
| pointer to starting point of 'mstr' within 'str' if found, or NULL if not found. |
Definition:
char * STrindex(str, mstr, len) char *str; char *mstr; i4 len;
STscompare - compare strings, length limited, space insensitive
The strings a_ptr and b_ptr are compared. The first string may be no longer than a_len bytes, and the second string may be no longer than b_len bytes. If either length is zero, it is taken to be very long. A null byte also terminates the scan. Compares are based on the ascii or ebcdic ordering. Shorter strings are less than longer strings. Return value is >0 for a > b, <0 for a < b, and zero for a == b.
Examples:
| "abc" > "ab" |
| " a bc " == "ab c" |
| "abc" < "abd" |
Inputs:
| a_ptr | pointer to first string to compare |
| a_len | length of first string |
| b_ptr | pointer to second string to compare |
| b_len | length of second string |
Outputs:
None
Returns:
| < 0 | if a lexically < b. |
| 0 | if a lexically == b. |
| > 0 | if a lexically > b |
Definition:
i4 STscompare(a_ptr, a_len, b_ptr, b_len); char *a_ptr; i4 a_len; char *b_ptr; i4 b_len;
STskipblank - Skip blank characters in a string
Given the start of a string, find the first character in the string that is NOT the "blank" character. Restrict search to number of bytes specified in input parameter "len".
Inputs:
| string | Pointer to a character string to search. |
| len | Number of bytes to search. |
Outputs:
| None |
Returns:
| NULL | If all characters in string were the "blank" character. |
| ptr | Pointer to first byte in string that is NOT the "blank" character. |
Definition:
char * STskipblank(string, len) char *string; i4 len;
STtalloc - create copy of a string in tagged memory
Allocate permanent storage for a Null terminated string. STtalloc allocates permanent tagged storage for the string, copies the contents of the string into the new storage area, and returns the pointer to this area.
Inputs:
| tag | variable indicating tag to use to identify storage |
| string | pointer to string to be copied. |
Outputs:
| None |
Returns:
| pointer to allocated storage. |
Definition:
char * STtalloc(tag, string) i4 tag; char *string;
STtrmwhite - remove trailing white space
Delete all trailing white space of string, null terminate, return new length.
Inputs:
| string | pointer to string to be stripped of trailing white space |
Outputs:
| string | pointer to string that has been stripped of trailing whitespace |
Returns:
| length of resultant string |
Definition:
i4 STtrmwhite(string) char *string;
STzapblank - eliminate white space
Delete all white space from source, place into destination buffer dest, null terminate, and return new length of dest (not including null). source and dest may be the same.
Inputs:
| source | pointer to string to be manipulated |
Outputs:
| dest | pointer to buffer holding the resultant string Returns: |
| length of result string |
Definition:
i4 STzapblank(source, dest) char *source; char *dest;
|
Ingres Compatability Library |
