synopsis.
String functions at level 0 use primary raw language data type "char *". though often times a function in this group is basically a wrapper around the same functionality offered by the host operating system, using these functions provide advantages:

• a single name across all supported OS's
• a more descriptive, standardized function name. For example, compare z_str_to_longint() vs. atol().
• more powerful functions (ie, z_skip_nonwhitespace(), z_yank_token(), z_pad_blanks_right())

[C] functions (aka subroutines):

z_delete_endchar()
SIGNATURE: int z_delete_endchar (char *s)
SYNOPSIS: deletes that final character. the converse of z_append_char()
RETURNS: 0
TRAITS: stable
 

z_delete_char()
SIGNATURE: int z_delete_char (char *str, size_t n, int *pi = NULL)
SYNOPSIS: delete a char at the nth position of a string
RETURNS:
0: successful deletion
-1: indicates bad parameter was passed in
TRAITS: stable
 

z_insert_char()
SIGNATURE: int z_insert_char (char *s, char c, int n, int maxi)
SYNOPSIS: inserts a char at the nth position of the string
DESCRIPTION:
characters at position 'str[n]' and up get moved up. the caller must specify the maximum length of the string; if it is exceeded, the characters at the end fall off. The length of the string can exceed param 'maxi'. If so, the insert shift procedure affects only the 1st 'maxi' chars.
RETURNS: 0
TRAITS: stable
 

z_append_char()
SIGNATURE: int z_append_char (char *s, char c)
SYNOPSIS: appends the char 'c' to the string 's'.
RETURNS: 0
TRAITS: stable; no error checking
 

z_digit_to_char()
SIGNATURE: char z_digit_to_char (const int n, const int base = 10, const boolean use_uc = TRUE, int *pi = NULL)
SYNOPSIS:
converts the numeric value of 'n' to a character. The value of 'n' must be in the correct range - very small, in [0..15].
Examples:
z_digit_to_char (2, 10, TRUE); // returns '2'
z_digit_to_char (2, 2); // ERROR! (returns '')
z_digit_to_char (13, 16, FALSE); // returns 'c'
z_digit_to_char (12, 16, TRUE); // returns 'B'
z_digit_to_char (2001, 8); // error in any base
PARAMETERS

• n: the number (value) to be converted to a character
• base: the numeric base to use. The default value is 10 (decimal). This value can be only one of the following: 16, 10, 8, or 2. Any other value will result in an error, and the operation will be aborted.
• use_uc: TRUE / FALSE; if TRUE, any letter (alphabetic) output values will be in upper-case; otherwise (if FALSE), they will be in lower-case. This parameter is applicable only for hexadecimal (base = 16).
• pi: error output indicator varlable. values:
  0: ok; digit properly converted and returned

RETURNS:
[character, in '0'..'F'] - successful mapping (/conversion)
'\0': error in one or more input values
 

z_is_printable()
SIGNATURE: boolean z_is_printable (char c)
SYNOPSIS: checks if the given character is 'regular'. a wrapper for the system function 'isprint()'
DESCRIPTION:
note that using this instead of an 'is-ascii' function is superior, as checking if a character is printable by checking if it is 'ASCII' introduces a dependency on ASCII character-encoding.
RETURNS: TRUE | FALSE
TRAITS:
stable. However, there is no provision for locale, limiting its usefulness for Scandinavian or Baltic languages (where there are for example, 'o' with 2 dots above it, or Spanish 'hard-n')
 

z_strpos()
SIGNATURE: int z_strpos (const char *s, char c, int *pie = NULL)
SYNOPSIS: this routine gives the index offset of the first occurance of 'c' in 's', if one is found; and if not, it returns -1
RETURNS:
[n]: (n >= 0) index offset of the first occurance of 'c' in 's'
-1: no 'c' found in 's'
TRAITS: stable
 

z_toupper()
SIGNATURE: int z_toupper (char c)
SYNOPSIS: yields the upper-case letter for a given letter
RETURNS: the upper-case letter for 'c', if possible; otherwise, 'c'
TRAITS: stable; potential incorrect results
 

z_islower()
SIGNATURE: boolean z_islower (char c)
SYNOPSIS: returns the lower-case letter for the input parameter 'c'
RETURNS:
the lower-case letter, if the inputted letter ('c') is an upper-case letter;
or FALSE, otherwise.
TRAITS: stable; potential incorrect results
 

z_isalpha()
SIGNATURE: boolean z_isalpha (char c)
SYNOPSIS: tells if the input parameter 'c' is "'alphabetic"; checks whether the character is printable and a letter
RETURNS: TRUE - character is alphabetic; | FALSE - otherwise
WARNING: totally dependent on ASCII ordering
TRAITS: stable
 

z_int_to_str_wcommas()
SIGNATURE: int z_int_to_str_wcommas (long int x, char *out, int *pi = NULL)
DESCRIPTION:
this is a simplified version of the '[xxx_to_dollarstr]()' series of functions. It inserts commas every 3 digits and works only for base 10. This function was written to address the frequent needs of having a comma-formatted number printed.
 

z_real_to_str_wcommas()
SIGNATURE: int z_real_to_str_wcommas (double x, char *out, count_t frac_dig = 0, int *pi = NULL)
DESCRIPTION:
this is a simplified version of the '[xxx_to_dollarstr]()' series of functions. This function is analogous to 'z_int_to_str_wcommas()' but works with real numbers (eg, float and double types). You can add a fractional decimal part, with virtually no limit to how many decimal places - correction, a hard stop of 4,096 characters after the decimal point (hope that's enough).
 

z_dollarstr_to_double()
SIGNATURE: double z_dollarstr_to_double (const char *s, int *pei = NULL)
SYNOPSIS: string to number conversion. parses a string containing a formatted number
DESCRIPTION:
This takes an input string such as "$8,460.11" and returns a double with value 8460.11. Here are some examples of input and output:

   INPUT         OUTPUT          INPUT           OUTPUT
   -----         ------          -----           ------
   "$  ,875.87"   875.87         "6,70,100.99"        6.0
   "$xi^6,100.9" 6100.9          "-y83.8"            83.8
   ". 89.77"       89.77         "@-(#@66.4"         66.4
   "44..30"        44.0          "@-83-.8"          -83.0
   "6700,888.9"  6700.0          ",123,345."     123345.0
   "(400.0"       400.0          "(125.75)"        -125.75

RETURNS: [numeric equivalent]
TRAITS: stable; obscure behaviour
 

z_double_to_dollarstr()
SIGNATURE: int z_double_to_dollarstr (double v, char *out, u_int wid, u_int dwid, u_int bitcode, int *pi = NULL)
SYNOPSIS: number to string conversion. create a formatted number as a string, from a type double
DESCRIPTION:
This function can print something like "$(1,453.66)" from the value -1453.66 There are quite a few formats to choose from. What is used is determined by the bitcode put into 5th parameter:

   5 4 3 2 1 0
   ^ ^ ^ ^ ^ ^
   | | | | | |....add '$'
   | | | | |......move '$' to far left (obviously meaningful if bit 0 set).
   | | | |........use () (parens) for neg. number. if not set, uses '-'.
   | | |          revision, Wed Aug 5 1987: space added at end of a positive
   | | |          number if this flag is used, to align negative numbers.
   | | |..........no commas. default is commas.
   | |............if too big, fill with '*'s
   |..............if too big, fill with '9's; bit field 5 (9's) wins over 4.

RETURNS:
0: success
-1: error - bad input parameter
TRAITS: stable; obscure behaviour; somewhat complex to use
 

z_ulong_to_dollarstr()
SIGNATURE: char *z_ulong_to_dollarstr (unsigned long, int, int, int * = NULL)
SYNOPSIS: similar to z_ulong_to_dollarstr(). formats a value of type unsigned long
DESCRIPTION:

bitcode:
43210
^^^^^
|||||.....pad with zeros in front
||||......left justify (doesn't mix with pad w. zeros; this has priority)
|||.......insert commas
||........if width o/flow, chop off low-order digits (default priority)
|.........if width o/flow, chop off high-order digits

RETURNS:
[char * pointer to buffer] - contains the resultant character string (success)
NULL: bad input parameter
WARNING:
usage of this function is DANGEROUS because it returns a pointer to a local stack variable that is logically destroyed after the function call returns
TRAITS: obscure behaviour; somewhat complex to use
 

z_long_to_dollarstr()
SIGNATURE: char *z_long_to_dollarstr (long val, int width, int bitcode, int *pi = NULL)
SYNOPSIS: almost the same as "z_ulong_to_dollarst()"; but for [signed] long integers.
DESCRIPTION:

bitcode:
543210
^^^^^^
||||||.....pad with zeros in front
|||||......left justify (doesn't mix with pad w. zeros; this has priority)
||||.......insert commas
|||........if width o/flow, chop off low-order digits (default priority)
||.........if width o/flow, chop off high-order digits
|..........if negative value, use '(', ')'.

RETURNS: [char * pointer to buffer] - contains the resultant character string (success) NULL: bad input parameter
WARNING: not thread-safe (uses static char buffer)
TRAITS: buggy; incomplete; not recommended; NEEDS REPAIR
 

is_z_valid_variable_name()
SIGNATURE: boolean is_z_valid_variable_name (const char *p, boolean auc = TRUE)
SYNOPSIS: test if string is valid [c language] variable name
DESCRIPTION:
this subroutine tests if the sequence of characters starting at 'p' represents a valid variable name, according to c-language standards. A valid variable name must start with a letter, and then can contain '0'..'9', 'a'..'z', or '_' (an underbar). whether upper case is ok too is up to the user by specifying the value of input parameter 'auc'
RETURNS:
0: ok (valid name)
-1: not ok (or error in input)
 

z_int_to_str()
SIGNATURE: int z_int_to_str (const int n, char *buf, const int base = 10, const size_t nmax = 0, int *pi = NULL)
SYNOPSIS: convert an integer ('n') to a string ('buf'). The output may be printed (to 'buf') in decimal, hexadecimal, octal, or binary.
PARAMETERS

• n: the number (value) to be converted to a string
• buf: the character buffer where the result is stored
• base: the base to use. the default value is 10 (decimal). This value can be only one of: 16, 10, 8, or 2. Any other value will result in an error and the operation will be aborted.
• nmax: the size of 'buf', in bytes (eg, the maximum number of characters 'buf' can hold). If 0 is specified, the buffer size will not be checked. This case is dangerous in that if the result uses more characters than the size of 'buf', fatal program errors (stack overflow, buffer overruns, segmentation faults) may result.
• pi: error output indicator varlable. values:
  0: ok; number properly converted and returned
  zErr_Value_NotHandled: illegal 'base' value
  zErr_Param_NullPointer: input buffer is null pointer
  zErr_Index_OutofBounds: illegal digit value encountered [PANIC; this should never happen]
  zErr_Result_TooBig: buffer overflow

RETURNS: 0
TRAITS:
"stable". Early notes describe this funcation as "[giving] potential incorrect results", but the reason for this note is unknown. This function was upgraded on Monday Aug 27, 2012 to handle multiple base values.
 

z_longint_to_str()
SIGNATURE: int z_longint_to_str (long int n, char *s, const size_t nmax = 0, int *pi = NULL)
SYNOPSIS:
same as 'z_int_to_str()', except input type is 'long int'.
PARAMETER LIST & RETURN VALUES: see 'z_int_to_str()'
 

z_count_to_str()
SIGNATURE: int z_count_to_str (count_t int n, char *s, const size_t nmax = 0, int *pi = NULL)
SYNOPSIS:
same as "z_longint_to_str()", except input type is 'count_t'
PARAMETER LIST & RETURN VALUES: see 'z_int_to_str()'
TRAITS: stable; potential incorrect results
 

z_ulong_to_str()
SIGNATURE: int z_ulong_to_str (u_long n, char *s, const size_t nmax = 0, int *pi = NULL)
SYNOPSIS: same as "z_longint_to_str()", except input type is 'u_long'
RETURNS: 0
 

z_double_to_str()
SIGNATURE: int z_double_to_str (double d, char *s, const char *fmt = NULL, int *pi = NULL)
SYNOPSIS:
similar as "z_longint_to_str()"; input type is 'double'
RETURN VALUES: see 'z_int_to_str()'
DESCRIPTION:
if the 3rd parameter ('fmt') is NULL or "", the default formatting is used. otherwise, you can pass it a format command - same used by sprintf(). Default format is "%lf".
RETURNS: 0
TRAITS: stable; obscure behaviour; potential strange results
 

z_str_to_int()
SIGNATURE: int z_str_to_int (const char *b, int base = 10, int *pe = NULL)
SYNOPSIS:
read the value inside string 'b'; if it's a number, returns its value. the number may be preceded by blanks and a "+" or "-" sign. Note that the string must not contain non-numeric characters (it can start with a '+' or '-'). It can have preceding blanks - they will be skipped. Thus, z_str_to_int("28days") will return an error, not 28.
PARAMETERS

• b: character buffer containing a numeric
• base: integer value for number base (must be: [2,] 8, 10, or 16)
• pe: error output indicator varlable. values:
  0: ok; number properly converted and returned
  1: invalid input: null buffer
  2: invalid input: base not implemented or illegal value
  3: non-number(s) encountered
  4: found more than 1 "+" or "-"

DESCRIPTION:
some examples:

   z_str_to_int("  85") ....... returns 85 (as an int)
   z_str_to_int("A3", 16) ..... returns 163
   z_str_to_int("-17", 8) ..... returns -15
   z_str_to_int("two", 10, &ie) returns -1, and error flag "ie" is non-zero
   z_str_to_int("45!", 10, &ie) returns -1, and error flag "ie" is non-zero

RETURNS: [numeric value]
TRAITS: base 2 is not [yet] supported
 

z_str_to_longint()
SIGNATURE: long z_str_to_longint (const char *b, int *pi = NULL)
SYNOPSIS: read the value inside string 'b'; if it's a number, returns its value
PARAMETERS

pi: output parameter, error indicator flag. values:
0 - ok - success;
-1 - bad [null] input parameter

RETURNS: [numeric value]
 

z_str_to_count()
SIGNATURE: count_t z_str_to_count (const char *b, int *p = NULL)
SYNOPSIS: similar to z_str_to_longint(), for "count_t" type
RETURNS: 0
 

z_str_to_double()
SIGNATURE: double z_str_to_double (const char *s, int *pi = NULL)
SYNOPSIS: converts the contents of a character array to its value as a real number (type double).
PARAMETERS

• in: input parameter, a pointer to character string containing characters representing a real number
• pi: [output] error indicator variable. values:
  0: successful conversion
  zErr_Param_NullPointer: 's' is NULL
  zErr_NoData: contents of 's' is an empty string ("")
  zErr_DirtyData: the contents of 's' had leading whitespace (a warning only)
  zErr_Data_BadFormat: NaN. the first (non-whitespace) char indicated that the contents is not a real number
  zErr_Data_Unexpected: the contents of the object contains non-numeric characters ("45.72(.." is not allowed)

DESCRIPTION:
this subroutine started a long time ago as a modification of the standard "atof()" function (p. 69, K&R white book). It does the following:

• skips any leading white space
• checks for a sign ('+' or '-)
• computes a value, loading each char to a digit
• if any char is not part of a valid real number, the subroutine exits with error. nothing but a number (with leading whitespace) is allowed.

Valid values of 's' include: " 45." (returns 45; 'pi' is set to zErr_DirtyData); "+63" (returns 63); "-9." (returns -9); " 87.9350" (returns 87.935; 'pi' is set).
RETURNS: [numeric value of the input string]
 

z_str_to_hex()
SIGNATURE: int z_str_to_hex (const char *in, char *out, size_t len = 0, boolean uc = TRUE, int meth = 0)
PARAMETERS

• in: input parameter, pointer to character string containing text to be encoded. Can be any text, but this subroutine is intended for [readable] clear-text.
• out: output parameter, pointer to character string to recieve the encoded output of 'in'. must be non-null in order for this subroutine to succeed, and MUST have enough space (number of bytes) to recieve the input. The space must be double the number of bytes processed plus 1 (for the '\0' endcap - string terminator).
• len: The number of bytes to process. Can be less than the natural length of the string. If 0 (the default), z_strlen() will be used to determine the number of bytes, which means the string in this case must be null-terminated and the output buffer correspondingly big enough.
• uc: if TRUE (the default), the output will use large letters for the hexadecimal values emitted ('A'..'F'); small (eg ['a'..'f']) otherwise.
• meth: "method" flag. We recommend not playing or modifying with this variable. The default is 0. It controls which implementation of this functionality is to be run. There are a few (currently 2 or 3) implementations with marginal differences. These are provided as a way to boost performance. The first implementation has 'meth' value 0. If this parameter is out of bounds the subroutine will fail, do nothing, and simply return -1.

DESCRIPTION:
converts 'len' characters in 'in' to their hexadecimal character representation. 'out' *must* be twice as long as 'len' (or the number of characters in 'in', up to the first null ['\0'] character). there is no way to check for buffer overrun so it is the responsibility of the user-application to ensure the integrity of the buffers 'in' and 'out'.
RETURNS:
0: success
-1: error - one or both char buffer parameters are null pointers, or 'meth' out of bounds
 

z_hex_to_str()
SIGNATURE: int z_hex_to_str (const char *in, char *out, size_t len, int meth = 0)
DESCRIPTION:
converts 'len' characters in 'in' to their clear-text equivalent. This function is the corollary to z_str_to_hex().
RETURNS:
0: success
-1: error - one or both char buffer parameters are null pointers, or the input buffer contains non-hex characters
 

z_hex_to_char()
SIGNATURE: char z_hex_to_char (const char c1, const char c2, int *pi = NULL)
SYNOPSIS:
converts 2 "hex" characters to normal character value. The two input variables 'c1' and 'c2' should be consecutive characters from a character buffer.
DESCRIPTION:
This function is intended to be used like so:

for (i = 0; i < n; i+= 2)
{
    c1 = buf[i];
    c2 = buf[i+1];
    out[i] = z_hex_to_char(c1, c2);
}

RETURNS: [char c]: 'c' is the resultant clear-text character, the decoded product of hex characters c1 & c2.
 

z_num_digits()
SIGNATURE: count_t z_num_digits (const char *buf, int *pi = NULL)
SYNOPSIS:
counts the number of digits for the text contained in 'buf'. The input parameter 'buf' must be pointing to text representing a number in order for this function to work.
PARAMETERS

• buf: character array contain a number.
• pi: [output] error indicator variable. values:
  0: success; num-string counted
  zErr_Param_BadVal: inputted string is NaN

 

z_numstr_trimzero()
SIGNATURE: int z_numstr_trimzero (char *in, int *pi = NULL)
SYNOPSIS: trims trailing zeros from a "numeric string"
PARAMETERS

• in: character array contain a number. The text must be null-terminated (with '\0'). It must contain a valid, non-null buffer.
• pi: [output] error indicator variable. values:
  0: success; string trimmed.
  zErr_Param_NullPointer: null pointer parameter.
  zErr_Param_BadVal: inputted string is NaN
  zErr_IsEmpty: 0-length string

DESCRIPTION:
the string in question must be the textual representation of a number, such as "10", 3.14", or "-1760.9". This function uses is_z_str_a_number() to make sure the contents of 'in' is strictly a number. If the buffer passes the test, any zeros at the end will be bobbed. Thus, "0.1750000" will become "0.175".

RETURNS:
0: success
1: warning: input was 0-length
-1: error - null pointer(s) passed in, or 'in' is NaN
 

z_str_incnumbers()
SIGNATURE: int z_str_incnumbers (char *str, int *p = NULL)
SYNOPSIS: 'increments' digits in a string, like a number
DESCRIPTION:
some examples:

    input           output
    "573-89-"       "573-90-"
    "12345"         "12346"
    "999."          "999."          (*error*)
    "0"             "1"
    "hi, 7 & 8 & 9" "hi, 7 & 9 & 0"

RETURNS: 0
 

z_yankdouble_fromstr()
SIGNATURE: double z_yankdouble_fromstr (const char *src, int *p = NULL)
RETURNS: [numeric value of the input string]
TRAITS: needs checking
 

z_copyreal_fromstr()
SIGNATURE: int z_copyreal_fromstr (char *dest, const char *src, int *pexi = NULL)
SYNOPSIS: if 'src' on the start of a number, copies the number to 'dest'
DESCRIPTION:
given that the cppsn ('src') is on a digit, this function copies the part of the string that is a floating point number (e.g., [0-9]*.[0-9]*) to 'dest' and returns the number of characters copied
RETURNS:
[n > 0] number of characters in the output string
-1: error ('src' not pointing to a real number)
 

z_is_str_allnumbers()
SIGNATURE: boolean z_is_str_allnumbers (const char *p, const size_t n = 0, int *p = NULL)
SYNOPSIS: tells if all characters in the given (null-terminated) string are digits
RETURNS:
TRUE: all digits
FALSE: not all digits (at least 1 non-numeric char), or bad input
 

z_is_str_valid_name()
SIGNATURE: boolean z_is_str_valid_name (const char *s, const size_t n = 0, int *pe = NULL)
SYNOPSIS:
similar to z_is_str_allnumbers(). The first character can be a digit ('0'..'9'). Checks only the first 'n' characters, if 'n' is set [to non-zero].
RETURNS:
TRUE: the text in 's' is a simple "word" type.
FALSE: not a simple word
TRAITS:
this was planned to be phased out, but then we needed something to distinguish between a "simple word" type and "compiler name" type, eg, "91601" vss. "Windows98_OS" (10/27/2012). The requirements were modified slightly
 

is_z_str_a_number()
SIGNATURE: boolean is_z_str_a_number (const char *s, int *pi = NULL)
SYNOPSIS: returns TRUE if the contents of 's' is [wholly-entirely] a number, or FALSE otherwise.
PARAMETERS

• s: the input character buffer, to be searched for a number. The contents of this buffer must be a number (as described here) in order to quality for returning TRUE.
• pi: [optional] output error indicator variable. Values:
  0: the number is an int. examples: "-1", "053", "666".
  1: the number is a float. examples: "76.", "-0.345", "-.7856".
  zErr_Data_Unexpected: this is the standard value for NaN errant syntax

DESCRIPTION:
this subroutine is purely and simply an alias for "is_z_str_on_number(s, TRUE)". Note that this function does not handle embedded commas, eg "1,000,000.3"
 

is_z_str_on_number()
SIGNATURE: boolean is_z_str_on_number (const char *s, boolean strict, int *pi = NULL)
PARAMETERS

• s: the input character buffer, to be searched for a number. The beginning of this buffer must be a number (as described here) in order to quality for returning TRUE.
• strict: if TRUE, the contents of the entire string must represent a single number in order for this function to return TRUE. Else, it returns FALSE and 'pi' is set to zErr_DirtyData.
• pi: [optional] output error indicator variable. Values:
  0: the number is an int. examples: "-1", "053", "666".
  1: the number is a float. examples: "76.", "-0.345", "-.7856".
  zErr_Data_Unexpected: this is the standard value for NaN errant syntax
  zErr_DirtyData: this is used if the numeric string is followed by non-numeric characters and 'strict' is FALSE.
  -1: bad syntax. examples: "-a", "-.xyx", "!abc", ".oh boy" (NOTE - THIS VALUE APPEARS TO BE WRONG!).

DESCRIPTION:
this is similar to z_is_str_allnumbers(), but allows input string 's' to contain characters typically used in number representation, such as '-' or '.'. Thus, all these are valid "number-strings" (and if 's' is set to these values, this subroutine will return TRUE):
"0.5500", "-3.14159265", "-88"
note: if 'strict' is TRUE, the entire string must be a valid numeric in order for this subroutine to return TRUE. If it contains anything else, even after the number (eg "10%"), the routine will return FALSE. However, the output variable will be 0, indicating that the text started as a number (rather strange combinations).
Note that this function does not handle embedded commas, eg "11,500" (comma-formatted numbers are a regional convention; some locales use dots or even single-quotes where the American convention places commas).
RETURNS:
TRUE: the text in 's' is entirely a number ('strict' = TRUE), or it starts with a number ('strict' = FALSE)
FALSE: the text in 's' is not a number
 

reverse()
SIGNATURE: int reverse (char *s)
SYNOPSIS: swaps the characters in a string
RETURNS: 0
TRAITS: low-value
 

z_extract_size_frombytes()
SIGNATURE: size_t z_extract_size_frombytes (const byte_t *ptr, int *pexi = NULL)
 

z_insert_size_intobytes()
SIGNATURE: int z_insert_size_intobytes (size_t n, byte_t *s, int *pexi = NULL)
RETURNS: 0
 

z_eol()
SIGNATURE: int z_eol (const char *s)
SYNOPSIS: test if the given string is is at the end of a line
DESCRIPTION: returns a 1 if the first character is '\n', '\r', or '\0'
RETURNS:
1: the first char of the string is on e-o-line character
0: otherwise
 

z_sgets()
SIGNATURE: const char *z_sgets (char *d, size_t maxn, const char *s, int *pe = NULL)
DESCRIPTION:
reads characters from 's' into the char array 'd', like fgets(). unlike gets()/fgets(), it returns a pointer to the start of 's', where sgets() finished input (this makes it useful to keep in a loop to read successive chunks of a buffer).
RETURNS:
<ptr>: points to start of next line
NULL: if no chars are copied
 

z_getline_stdin()
SIGNATURE: size_t z_getline_stdin (char *b, size_t n, int *pe = NULL)
SYNOPSIS: gets a (char *) line from stdin
PARAMETERS

pi: [optional] output error indicator variable. Values:
0: successful line fetch
1: e-o-input (stdin was closed)

RETURNS: the number of characters fetched
 

z_str_center()
SIGNATURE: int z_str_center (char *b, size_t n, int *pe = NULL)
SYNOPSIS: surrounds a string with 'n' blanks
RETURNS:
0: success;
-1: error ('n' >= length of string)
 

z_right_justify()
SIGNATURE: int z_right_justify (char *d, const char *s, size_t maxn, int *pe = NULL)
SYNOPSIS: move nonblank chars to right side of buffer
DESCRIPTION:

examples:
    "  oops!  "     ->     "    oops!"
    "  oops!"       ->     "  oops!"
    "ugh   "        ->     "   ugh"

RETURNS: 0
 

z_left_justify()
SIGNATURE: int z_left_justify (char *dest, const char *src, int *pexi = NULL)
SYNOPSIS: take out leading whitespace in a string; removes all the gaps left at the end of a line.
RETURNS:
0: success
-1: bad input (null value(s))
 

z_len()
SIGNATURE: int z_len (char *buffer, int *pexi)
SYNOPSIS:
this routine returns the length of a string when trailing spaces, newlines, and s are disregarded; eg, z_len ("ABCD ") -> 4
RETURNS: string length (>= 0)
TRAITS: unusual
 

z_substring()
SIGNATURE: const char *z_substring (const char *victim, const char *sub, int * = NULL)
SYNOPSIS: search for the first occurence of "sub" in "victim"
RETURNS:
a pointer to where "sub" is found
NULL, if not found
 

z_str_reverse()
SIGNATURE: int z_str_reverse (char *buf)
SYNOPSIS:
reverses all the characters in 'buf'; puts them in reverse order. "abc!" becomes "!cba". All characters up to '\0' are processed.
 

yank_up2char()
SIGNATURE: char *yank_up2char (char *dest, char *src, char key)
SYNOPSIS: copy a string, up to specified char
DESCRIPTION: copies up to (but not including) the given char "key", if it is found. if not found, the operation is not done.
RETURNS:
a pointer in "src" where "key" is [first] found
NULL, if not found
 

z_strchr()
SIGNATURE: const char *z_strchr (const char *s, char c, int *pexi = NULL)
SYNOPSIS: returns a pointer to 1st occurrence of char c in string s
RETURNS:
a pointer to the 1st occurrence of char c in string s
NULL pointer if c does not occur in the string s
 

concat()
SIGNATURE: int concat (int nargs, char *dest, ...)
SYNOPSIS:
a "varchar" function. concatenate a variable number of strings into parameter buffer "dest". specify the number of strings to concatenate in parameter "nargs".
DESCRIPTION:
it is the user's responsibility to ensure that a sufficiently large enough buffer is provided. ie, "concat (n, dest, s1, s2, s3);" concatenates s1+s2+s3 and puts it in dest. '3' is the number of strings to concat().
RETURNS: 0
 

z_copy()
SIGNATURE: int z_copy (char *source, char *dest, int m, int n)
SYNOPSIS: copies n chars, starting at position m
RETURNS: 0
 

delete_chars()
SIGNATURE: int delete_chars (char *s, int m, int n)
SYNOPSIS: extract (delete) a section of a string; delete characters from position m to position n
RETURNS:
0: success
-1: caller provided bad input parameters (eg, m+n > [string length])
 

put_words_in_box80()
SIGNATURE: int put_words_in_box80 (char box[][80], char *source, int max_n)
SYNOPSIS:
parses a char string into "words". if the input string ("source") contains this:
" OEX IBM ATT CYR"
the output will be a set of strings containing this:
{ "OEX", "IBM", "ATT", "CYR" }
PARAMETERS

• box - an array of 80[]-char strings. define it like "char box[5][80];"
• source - a char buffer containing the input to parse
• max_n - max number of words allowable; size of "box"

RETURNS:
number of words read
-1, if error
TRAITS: this function will probably be phased out
 

put_words_in_box256()
SIGNATURE: int put_words_in_box256 (char box[][256], char *source, int max_n)
SYNOPSIS: like "put_words_in_box80()" but for bigger string buffers (256)
RETURNS:
number of words read
-1, if error
TRAITS: this function will probably be phased out
 

z_number_to_commastr()
SIGNATURE: char *z_number_to_commastr (long, int, int)
SYNOPSIS:
format a long int into a string, adding commas and interpreting parameters to determine where the decimal point goes. Commas are inserted every three digits to the left of the decimal. sample usage:
'strng (12345678, 12, 2)' returns " 123,456.78"
'strng (12345, 8, 2)' returns " 123.45"
 

z_strcspn()
SIGNATURE: int z_strcspn (char *s1, char *s2)
SYNOPSIS: find length of segment of s1 consisting of chars not from s2
DESCRIPTION:
this finds the length of [an initial] segment of s1 consisting entirely of characters not from s2. useful in environments lacking system function "strcspn()".
 

z_isdigit()
SIGNATURE: int z_isdigit (int c)
SYNOPSIS: checks whether a character is a number (ie, a digit)
RETURNS: 1: character is a digit; 0: otherwise
WARNING: totally dependent on ASCII ordering
 

z_ispunct()
SIGNATURE: int z_ispunct (int c)
SYNOPSIS: checks whether a character is a punctuation
RETURNS: 1: character is punctuation; 0: otherwise
WARNING: totally dependent on ASCII ordering
 

z_strcpy()
SIGNATURE: int z_strcpy (char *out, const char *in)
SYNOPSIS: an os-independent "strcpy()"
RETURNS:
0: success
-1: error (null parameter string[s])
 

z_strncpy()
SIGNATURE: char *z_strncpy (char *d, const char *s, size_t n)
SYNOPSIS:
this does a "strncpy()" with a '\0' tacked on the end. if a null byte ('\0') is encountered in the input string 's', the copy ends there.
To copy a specific number of bytes without interpreting the contents, use z_bcopy().
RETURNS:
0: success
-1: error (null parameter string[s])
 

z_strcat()
SIGNATURE: int z_strcat (char *out, const char *in, int *pexi = NULL)
SYNOPSIS: an os-independent "strcat()"
RETURNS:
0: success
-1: error (null parameter string[s])
 

z_strdup()
SIGNATURE: char *z_strdup (const char *in)
SYNOPSIS: an os-independent "strdup()"; allocates new memory and copies a string into the space
 

z_bcopy()
SIGNATURE: int z_bcopy (byte_t *dest, const byte_t *source, size_t n)
SYNOPSIS:
this subroutine is a replacement for the 'bcopy()' system call. It copies binary strings (eg, non-text blocks of data). There is no interpretation of the contents - exactly 'n' bytes will be copied (this differs from z_strncpy(), which stops if a null byte is encountered).
RETURNS:
0: success
-1: error (null parameter string[s])
 

z_bfind()
SIGNATURE: int z_bfind (const byte_t *a, const byte_t *b, size_t a_len, size_t b_len, int *pe = NULL)
SYNOPSIS: searches for "b" in "a". b_len <= a_len.
PARAMETERS

• a: block of bytes to search
• b: block of bytes to search for in "a"
• a_len: number of bytes in "a" (could be less than a's length)
• b_len: number of bytes in "b"
• pe: error indicator [output] var. values:
  0: ok; "b" found
  1: not found
  2: null input buffer
  3: b_len > a_len
  4: a_len == 0 || b_len == 0

DESCRIPTION:
this is a binary-byte version of z_substr(). Used by the find() member function whtn the string is in binary mode.
RETURNS:
[n > 0]: index offset into "a"
-1: error or string not found (error probably due to length of "b" exceeding "a", or null pointer)
 

z_bcmp()
SIGNATURE: int z_bcmp (const byte_t *a, const byte_t *b, size_t len, boolean man = FALSE)
SYNOPSIS: compare 2 "binary" character blocks
DESCRIPTION:
compares byte string 'a' against byte string 'b'; Both strings are assumed to be "len" bytes long. len == zero bytes always returns zero. a new flag, "do_manual", if set, lets you bypass any "bcmp()" system call (which would be faster).
RETURNS:
0: a and b are identical
1: a and b are different
 

z_yank_word()
SIGNATURE: int z_yank_word (char *dest, const char *source, int *pexi = NULL)
SYNOPSIS: extracts a "word" from "source"; doesn't modify source string
DESCRIPTION:
does the equivalent of vi's "yw": if positioned on alphanumeric, yanks all 'word' characters to end of token - up to but not including the 1st non-alphanum. if positioned on whitespace, yanks whitespace. if on other extraneous char, yanks up to alphanumeric, whitespace
RETURNS: 0
 

z_yank_bigword()
SIGNATURE: int z_yank_bigword (char *, const char *, int * = NULL)
SYNOPSIS: extracts a "word" + trailing non-whitespace from "source"; doesn't modify source string
DESCRIPTION:
does the equivalent of vi's "yW": if positioned on alphanumeric, yanks all to end of token - up to but not including 1st non-alphanum. if positioned on whitespace, yanks whitespace. if on other extraneous char, yanks up to alphanumeric, whitespace gets yanked too.
RETURNS: 0
 

z_yank_token()
SIGNATURE: int z_yank_token (char *d, const char *s, count_t *pn = NULL, boolean inc_q = FALSE, boolean inc_bs = TRUE)
SYNOPSIS: extracts a "quoted substring" from "s"; doesn't modify source string
PARAMETERS

• inc_q - if TRUE, the output string will include any captured quotes
• inc_bs - if TRUE, includes "\" if a "\"" encountered

DESCRIPTION:
if the input string ("s") contains ""HELLO" and trailer..", this routine copies "HELLO" to the output string "d". It implements a policy of including any back-slashes when encountered in the substring to extract, e.g., if a "\'" is encountered, a "\'" gets stored, not a "'". the caller needs some control over quoted text; data bags, in particular, have different requirements, depending on whether they are doing a "load()" or a "print()".
RETURNS:
0: success
1: error
 

z_yank_quote()
SIGNATURE: const char *z_yank_quote (char *d, const char *s, boolean incl_q = FALSE, boolean incl_bs = FALSE, int *pi = NULL)
SYNOPSIS:
this important function extracts a quotation sub-string from the input string "s". the first character of the string must start with either a single-quote or a double-quote. see z_yank_token() for details.
if the input string ("s") has embedded backslashes, whether the character following the backslash may or may not be included in the output is highly dependent on the 'incl_bs' [4th] parameter. If 'incl_bs' is TRUE, this means do not interpret any "\[n]" character combination - it is raw text, to be passed thru without interpretation. If 'incl_bs' is FALSE, and a "\{something}" is found in the input stream (usually backslash + single character), the lexeme will be reinterpreted as follows: If it is one of these: 'n', 'r', '\', or one of the enveloping quote characters (either ''' >or '"'), it will recieve special processing. (if you want to avoid this, double-up your back-quotes or set 'incl_bs' to TRUE).
PARAMETERS

• d: destination char buffer. It must point to a [pre-allocated] buffer space large enough to hold the output string.
• s: source character string. It must be null-terminated. incl_quotes: TRUE / FALSE; if TRUE, the enveloping quote characters will be included with the output
• incl_bs: TRUE / FALSE; if TRUE, the input string will be processed "raw", without [re]interpretation of special character sequences, and the back-slashes will be copied verbatim to the output buffer (including any terminating back-slash). If FALSE, special sequences that start with a back-slash will be "interpreted": "\\" -> "\"; "\n" is converted to a LINEFEED (aka 'NEWLINE') character (ASCII 10); "\r" is converted to a CARRIAGE RETURN character (ASCII 13, or 0x0D). In the case of a back-slash followed by a NULL (eg, character value 0x0), this will terminate processing. Note that this is an error condition, as the input was not matched with a closing quote character.
• pi: error indicator variable. values:
  0: success - successfully parsed and copied a quote;
  1: input string did not start with a [either single- or double-] quote;
  2: null pointer passed in (dest or source);
  3: syntax error - input string was not properly closed with a matching closing quote

RETURNS:
[pointer into s]: if all went well, this returns a pointer to the character position of input string "s" just beyond the closing quote character. Ie, if given the string ""(hi)"" (note the inner double-quotes), the pointer will be on position 6 (starting from 0 as the first character position): 0: ", 1: (, 2: h, 3: i, 4: ), 5: ", 6: \0. In this example, the final character in the character string is also the closing quote. If the string was instead ""(hi)"XYZ", the pointer would have been on the 'X'.
NULL: error ocurred (string probably didn't start with a quote char)
 

z_nl_strip()
SIGNATURE: int z_nl_strip (char *, int * = NULL)
SYNOPSIS: remove any trailing newlines (and carriage-returns)
RETURNS: 0
 

z_trim()
SIGNATURE: int z_trim (char *s, int *pexi = NULL)
SYNOPSIS: this routine takes off any newlines, ^M's, blanks, or tabs from the end of a string. it is a super-set of "z_nl_strip()"
RETURNS: 0
 

z_trimchar()
SIGNATURE: int z_trimchar (char *s, charc, int *pexi = NULL)
SYNOPSIS: this trims a string of a specific char only. this was made for culling off trailing spaces
RETURNS: 0
 

z_append_nl()
SIGNATURE: int z_append_nl (char *, int * = NULL)
SYNOPSIS: adds a '\n' to a string
RETURNS: 0
 

z_append_nl_ifnone()
SIGNATURE: int z_append_nl_ifnone (char *, int * = NULL)
SYNOPSIS: adds a '\n' to e-o-string, only if not there
RETURNS: 0
 

z_appendchar_ifnone()
SIGNATURE: int z_appendchar_ifnone (char *, char, int * = NULL)
SYNOPSIS: adds a specific char to e-o-string, if not there
DESCRIPTION: add 'c' to a string, only if the last char of the string isn't that character
RETURNS: 0
 

z_lastchar_isnl()
SIGNATURE: boolean z_lastchar_isnl (const char *, int * = NULL)
SYNOPSIS: check whether the end of the line is a newline
RETURNS:
TRUE - if the last char of the string is a '\n' or '\r'
FALSE - otherwise.
 

z_lastchar_isthis()
SIGNATURE: boolean z_lastchar_isthis (const char *, char, int * = NULL)
SYNOPSIS: test for specific char at the end of the string
RETURNS:
TRUE: last char of the string matches the inputted parameter character
FALSE: otherwise
 

z_uppercase_line()
SIGNATURE: int z_uppercase_line (char *, int * = NULL)
SYNOPSIS: convert string's lower-case letters to upper-case
RETURNS: 0
 

z_lowercase_line()
SIGNATURE: int z_lowercase_line (char *, int * = NULL)
SYNOPSIS: convert string's upper-case letters to lower-case
RETURNS: 0
 

z_number_of_lines()
SIGNATURE: count_t z_number_of_lines (const char *s, count_t max_n = 0, int *pe = NULL)
SYNOPSIS: counts the number of lines in the input string "s", up to "max_n"
RETURNS: [n >= 0] number of lines
 

z_pad_blanks_right()
SIGNATURE: int z_pad_blanks_right (char *buffer, size_t max, int *pexi = NULL)
SYNOPSIS: add spaces to a string (with max length 'max')
 

z_pad()
SIGNATURE: int z_pad (char *s, size_t n, char c, int *pi = NULL)
SYNOPSIS: tacks on n units of the desired character c to the string s.
RETURNS:
0: success
1: error
 

z_ch_append()
SIGNATURE: int z_ch_append (char *s, size_t n, char c)
SYNOPSIS: add char "c" "n" times to "s"
RETURNS: 0
TRAITS: it is unknown why this exists; this function will probably be phased out
 

z_nullstring()
SIGNATURE: int z_nullstring (char *s, size_t n, int *pi)
SYNOPSIS:
put a specific number of '\0's in a string buffer. This function used to be called z_bero(). It is the equivalent of (BSD and solaris) "bzero()". This function is provided for convenience - it is exactly equivalent to z_fillstring(s, n, '\0').
RETURNS:
0: success
1: error
 

z_fillstring()
SIGNATURE: int z_fillstring (char *s, size_t n, char c, int *pi)
SYNOPSIS: puts n units of c in string s.
RETURNS:
0: success
1: error
WARNING: this subroutine does not do boundary checking. Use it at your own risk!
 

z_isreadable()
SIGNATURE: boolean z_isreadable (const char *ptr, size_t max_n = 0, int *p = NULL)
SYNOPSIS:
tells if the contents of the character buffer is "readable". 'ptr' must point to a valid [non-null] character buffer. By default, the entire contents of the string is searched. If 'max_n' is not zero, only the first 'max_n' characters (if the value is less than the buffer length, as defined by z_strlen()) will be checked. The definition of a readable character 'c' is one where 'z_is_printable(c)' returns TRUE. Basically, it is a number (0..9), letter ('A'..'Z', 'a'..'z'), punctuation (eg, ',.!;:' etc), or readable character ('#', '@', '^', '&', '}', '[', etc).
WARNING:
[currently] a readable character is one in 'ISO-eng', so some characters that are valid in other languages (Spanish 'n' as in "ano", Viking 'o' with a diagonal bar through it or 2 dots over it, etc) would be considered "unreadable".
 

z_isblank_string()
SIGNATURE: boolean z_isblank_string (const char *ptr, boolean incl_nl = FALSE)
SYNOPSIS: tell if given string ("ptr") consists entirely of whitespace
RETURNS: TRUE (if so), FALSE (otherwise)
 

z_stricmp()
SIGNATURE: int z_stricmp (const char *a, const char *b)
SYNOPSIS:
compare 2 strings without regard to case descr: using this routine, the following strings are lexigraphically equivalent:
"abcd", "ABCD", "aBcD"
And the following hold true: "xyzz" > "XYZ"; "BOO" > "bo"
RETURNS:
0: the strings are lexographically identical
1: the strings are lexographically different
-1: error occurred
 

z_strincmp()
SIGNATURE: int z_strincmp (const char *a, const char *b, size_t n)
 

z_strcmp()
SIGNATURE: int z_strcmp (const char *a, const char *b)
SYNOPSIS: compares 2 strings for equality
RETURNS:
0: a and b are identical
1: a and b are different
-1: error (null parameter string[s])
 

z_strncmp()
SIGNATURE: int z_strncmp (const char *a, const char *b, size_t n)
SYNOPSIS: compares first n chars of 2 strings for equality
 

z_strlen()
SIGNATURE: size_t z_strlen (const char *s, int *pexi = NULL)
SYNOPSIS: an os-independent "strlen()"
RETURNS:
(n >= 0): length of the string
-1: error (null input string)
 

skipto_nextword()
SIGNATURE: int skipto_nextword (const char **ptr)
SYNOPSIS: set pointer over current word, to the next word
 

z_skip_whitespace()
SIGNATURE: int z_skip_whitespace (const char **line, boolean incl_nl = FALSE, int *pi = NULL)
SYNOPSIS: moves a char ptr-ptr over any current white space
 

z_skip_nonwhitespace()
SIGNATURE: int z_skip_nonwhitespace (const char **pptr, int *pi = NULL)
SYNOPSIS: set pointer position to the next white space (or e-o-line)
RETURNS: 0
 

z_extract_word()
SIGNATURE: int z_extract_word (char *d, const char *s, int *pi = NULL)
SYNOPSIS: copy input to output until whitespace encountered
RETURNS:
0: success
1: error (bad input parameter)
 

z_extract_bigword()
SIGNATURE: int z_extract_bigword (char *d, const char *s, int *pi = NULL)
 

note.
this group of functions contains some of the very first code written for the Z Directory (circa 1985).

bugs.
some of the parameter ordering and return value conventions need to be cleaned up. Also, a couple of routines [eg z_ulong_to_dollarstr()] return pointers to decaying stack variables, which means using them is a risky proposition; or pointers to static buffers [eg z_long_to_dollarstr()] which means that the problems with using them is fixed/limited output buffer size and possible corruption when used in multi-threaded applications.

history.

??? 05/06/1985: strng(): made it return "   0.00", not "   .00"
??? 06/05/1985: strng() - first version
??? 09/19/1985: strng() fixed special case: longthing == 0 && decimals == 0
Thu 11/13/1986: {11:25pm} concat(): "strcat (a,a);" bus error; patching
??? 04/29/1987: strng() got rid of malloc(); now length restricted to 255
Sun 08/09/1987: z_substring() created
??? 07/04/1989: "delete()" renamed to "delete_chars()"
??? 06/24/1995: created "z_strcmp()"
??? 01/23/1998: z_substring(): trapped for null string in input parameters
??? 12/25/1996: changed "z_stricmp()"; added "z_strincmp()"
??? 01/25/1998: "z_getline_stdin()" moved in, from layer 1
??? 03/23/1998: bug fix, "z_stricmp()" (if unequal length strings)
??? 03/28/1999: new var-args bugs, when including "/usr/include" mixed in w. gnu
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")
Fri 11/08/2002: added "z_isblank_string()" {--AG}
Sat 08/23/2003: 'cosmetic' clean-up
Sun 01/08/2012: added "z_isreadable()"