Contents

Character and String Functions

• byleng()
• ldchar()
• rdownshift()
• rfmtdouble()
• rfmtlong()
• rstod()
• rstoi()
• rstol()
• rupshift()
• stcat()
• stchar()
• stcmpr()
• stcopy()
• stleng()



• Formatting mask

The functions whose names begin with by act on and return fixed-length strings of bytes. The functions whose names begin with rst and st (except stchar) operate on and return null-terminated strings. The rdownshift() and rupshift() functions also operate on null-terminated strings but do not return values. When you compile your FESQLC program, the FESQLC preprocessor calls on the linker to link these functions to your program.

byleng()

Purpose:

Returns the number of significant characters in the specified string; does not include trailing blanks

Syntax:

mint byleng(char *s1, mint count);

Notes:

1. s1 is a pointer to a fixed-length string, not null-terminated.
2. count is the number of bytes in the fixed-length string.

ldchar()

Purpose:

To copy a fixed-length string into a null-terminated string without trailing blanks

Syntax:

void ldchar(char *from, mint count, char *to);

Notes:

1. from is a pointer to a fixed-length source string.
2. count is the number of bytes in the source string.
3. to is a pointer to the first byte of a null-terminated destination string. If the to argument points to the same location as the from argument, or to a location that overlaps the from argument, ldchar() does not preserve the original value.

rdownshift()

Purpose:

To convert all the characters in a null-terminated string to lowercase.

Syntax:

void rdownshift(char *s);

Notes:

s is a pointer to a null-terminated string.

rupshift()

Purpose:

To convert all the characters in a null-terminated string to uppercase.

Syntax:

void rupshift(char *s);

Notes:

1. s is a pointer to a null-terminated string.

stcat()

Purpose:

To concatenate one null-terminated string to another (src is added to the end of dst).

Syntax:

void stcat(char *src, char *dst);

Notes:

1. src is a pointer to the start of the string that FESQLC puts at the end of the destination string.
2. dst is a pointer to the start of the null-terminated destination string.
3. The resulting string is dstsrc.

stcopy()

Purpose:

To copy a string to another location

Syntax:

void stcopy(char *src, char *dst);

Notes:

1. src is a pointer to the string that you want to copy.
2. dst is a pointer to a location in memory where FESQLC copies the string.

stleng()

Purpose:

Returns the number of bytes in the specified string

Syntax:

mint stleng(char *src);

Notes:

1. src is a pointer to a null-terminated string.
2. The length does not include the null terminator.

stcmpr()

Purpose:

To compare two strings

Syntax:

mint stcmpr(char *s1, char *s2);

Notes:

1. s1 is a pointer to the first null-terminated string.
2. s2 is a pointer to the second null-terminated.
3. s1 is greater than s2 when s1 appears after s2 in the ASCII collation sequence.

Return code:

=0 The two strings are identical.
<0 The first string is less than the second string.
>0 The first string is greater than the second string.

stchar()

Purpose:

To copy a null-terminated string into a fixed-length string 

Syntax:

void stchar(char *from, char *to, mint count);

Notes:

1. from is a pointer to the first byte of a null-terminated source string.
2. to is a pointer to a fixed-length destination string. If this argument points to a location that overlaps the location to which the from argument points, FESQLC discards the from value.
3. count is the number of bytes in the fixed-length destination string.

rstoi()

Purpose:

To convert a string to a short integer.

Syntax:

mint rstoi(char *str, mint *val);

Notes:

1. str is a pointer to a null-terminated string.
2. val is a pointer to a mint value that holds the converted value.

Return code:

=0  The conversion was successful.
!=0 The conversion failed.

rstod()

Purpose:

To convert a string to a double. 

Syntax:

mint rstod(char *str, double *val);

Notes:

1. str is a pointer to a null-terminated string.
2. val is a pointer to a double value that holds the converted value.

Return code:

=0  The conversion was successful.
!=0 The conversion failed.

rstol()

Purpose:

To convert a string to a long integer

Syntax:

mint rstol(char *str, mlong *val);

Notes:

1. str is a pointer to a null-terminated string.
2. val is a pointer to an mlong value that holds the converted value.

Return code:

=0  The conversion was successful.
!=0 The conversion failed.

rfmtdouble()

Purpose:

To convert a double value to a character string having a specified format.

Syntax:

mint rfmtdouble(double dvalue, char *format, char *outbuf);

Notes:

1. dvalue is the double value to format.
2. format is a pointer to a char buffer that contains the formatting mask.
3. outbuf is a pointer to a char buffer that receives the formatted string.

Return code:

0         The conversion was successful.
-1211 The program ran out of memory (memory-allocation error).
-1217 The format string is too large.

rfmtlong()

Purpose:

To convert a long integer to a character string having a specified format

Syntax:

mint rfmtlong(int4 lvalue, char *format, char *outbuf);

Notes:

1. lvalue is the int4 integer to convert.
2. format is a pointer to the char buffer that contains the formatting mask.
3. outbuf is a pointer to a char buffer that receives the formatted string for the integer value.

Return code:

0        The conversion was successful.
-1211 The program ran out of memory (memory-allocation error).
-1217 The format string is too large.

Formatting Mask

A numeric-formatting mask specifies a format to apply to some numeric value. This mask is a combination of the following formatting characters:

Any other characters in the formatting mask are reproduced literally in the result.

Examples: