=========================================
   STDLIB.KCL
   STRING/MEMORY LIBRARY FOR KAMASOFT C'
=========================================

The library is loaded in the compilation
phase (ExT, G) to the upper part of
memory. A function is used by declaring
the library once with extern
"stdlib.kcl"; and each function with
ordinary function.

FUNCTION LIST
-------------------------

name     bytes  input  output
-------  -----  -----  ------
ATOI        78      1       1
FILL16      42      3       1
FIND16      56      3       1
HEXVAL      65      1       1
ITOA        56      2       1
ITOAS       73      2       1
ITOHEX      51      2       1
MEMCHR      40      3       1
MEMCMP      55      3       1
MEMCPY      35      3       1
MEMMOVE     60      3       1
MEMSET      39      3       1
STRCAT      44      2       1
STRCHR      30      2       1
STRCMP      45      2       1
STRCPY      35      2       1
STRLEN      27      1       1
STRLWR      38      1       1
STRNCMP     58      3       1
STRRCHR     35      2       1
STRUPR      38      1       1

PARAMETER PASSING
--------------------------
- the last (or only) argument is in
register HL
- all arguments are also in the parameter
block
  pointed to by the system variable 5CB0h
 Each argument takes 2 bytes:
     arg1 = ((5CB0))+0 and +1
     arg2 = ((5CB0))+2 and +3   etc.
- the return value (for functions that
return
  one) is in register HL (the high byte H
  is
  zero for byte results)

=========================================
 ATOI - string to integer
=========================================

INPUT : 1 - arg1 s
OUTPUT: 1 - the value (signed)

Reads a decimal integer from the start of
string s. Leading spaces are skipped,
then an optional + or - sign, then the
digits; the first character that is not a
digit ends the number. The result is the
signed value (-32768 to 32767, it wraps
on overflow). With no digits the result
is 0. Pair it with INPUT to turn typed
text into a number.

USAGE:
  declare int n;
  declare char b[6];
  extern "stdlib.kcl";
  extern "basic.kcl";
  {
  print("N? "); input(b,6);
  n=atoi(b);   /* "  -12" -> -12 */
  }

=========================================
 FILL16 - fill an array of 16-bit words
=========================================

INPUT : 3 - arg1 arr, arg2 val, arg3 n
OUTPUT: 1 - arr (the start address)

Stores the 16-bit value val into the
first n words of the integer array arr
(each word low byte first). It is the
16-bit version of MEMSET. n is a count of
words, not bytes, so it writes n*2 bytes.
Returns arr.

USAGE:
  declare int a[100];
  extern "stdlib.kcl";
  fill16(a,0,100); /* clear 100 ints */

=========================================
 FIND16 - find a 16-bit word in an array
=========================================

INPUT : 3 - arg1 arr, arg2 val, arg3 n
OUTPUT: 1 - index 0..n-1, or 0FFFFh if
not found

Searches the first n words of the integer
array arr for the value val and returns
the index (0-based) of the first match.
If val is not present it returns 0FFFFh
(-1). It is the 16-bit counterpart of
MEMCHR; n counts words.

USAGE:
  declare int a[5];
  declare int i;
  extern "stdlib.kcl";
  i=find16(a,42,5); /* -1 if absent */

=========================================
 HEXVAL - hexadecimal string to integer
=========================================

INPUT : 1 - arg1 s
OUTPUT: 1 - the value (0-65535)

Reads a hexadecimal number from the start
of string s. Leading spaces are skipped;
then the digits 0-9 and A-F (lower case
a-f too) are taken until the first
character that is not a hex digit. The
16-bit value is returned; more than four
digits simply keep the low word. There is
no 0x or h prefix or sign.

USAGE:
  declare int w;
  extern "stdlib.kcl";
  w=hexval("1A2B");   /* 6699 */
  w=hexval("ff");     /* 255 */

=========================================
 ITOA - unsigned integer to string
=========================================

INPUT : 2 - arg1 value, arg2 buf
OUTPUT: 1 - number of digits written

Writes the 16-bit value (treated as
unsigned, 0-65535) into buf as a decimal
string and adds a terminating zero. It
returns the number of digits. buf must
hold up to 6 bytes (five digits plus the
zero). For signed numbers use ITOAS.

USAGE:
  declare char b[6];
  extern "stdlib.kcl";
  itoa(1234,b); /* b = "1234",0 */

=========================================
 ITOAS - signed integer to string
=========================================

INPUT : 2 - arg1 value, arg2 buf
OUTPUT: 1 - length of the string

Like ITOA but the value is signed (-32768
to 32767). A negative number is written
with a leading minus sign. The string is
0-terminated and the return value is its
length (the sign counts). buf should hold
up to 7 bytes (sign, five digits, zero).

USAGE:
  declare char b[7];
  extern "stdlib.kcl";
  itoas(-42,b); /* b = "-42",0 ; 3 */

=========================================
 ITOHEX - integer to 4-digit hex string
=========================================

INPUT : 2 - arg1 value, arg2 buf
OUTPUT: 1 - 4 (digits written)

Writes the 16-bit value as exactly four
upper-case hexadecimal digits into buf,
followed by a terminating zero, and
returns 4. The value is always padded to
four digits (for example 255 gives
"00FF"). buf must hold at least 5 bytes.

USAGE:
  declare char b[5];
  extern "stdlib.kcl";
  itohex(6699,b); /* b = "1A2B",0 */

=========================================
 MEMCHR - find a byte in memory
=========================================

INPUT : 3 - arg1 s, arg2 c, arg3 n
OUTPUT: 1 - pointer to the byte, or 0

Scans the first n bytes from address s
for a byte equal to c (only the low byte
of c is used) and returns the address of
the first match, or 0 if it is not found
in that range. Unlike STRCHR it does not
stop at a zero byte; it always looks at
exactly n bytes.

USAGE:
  declare char buf[256];
  declare int p;
  extern "stdlib.kcl";
  p=memchr(buf,13,256); /* find CR */

=========================================
 MEMCMP - compare two memory blocks
=========================================

INPUT : 3 - arg1 a, arg2 b, arg3 n
OUTPUT: 1 - 0 equal, 0FFFFh a<b, 1 a>b

Compares n bytes at address a with n
bytes at address b. It returns 0 if all n
bytes are equal, 0FFFFh (-1) if the first
differing byte is smaller in a, or 1 if
it is larger in a. Unlike STRCMP it does
not stop at a zero, so it can compare any
binary data.

USAGE:
  declare int r;
  extern "stdlib.kcl";
  r=memcmp(buf1,buf2,16);
  if(r==0) print("same");

=========================================
 MEMCPY - copy a memory block
=========================================

INPUT : 3 - arg1 dst, arg2 src, arg3 n
OUTPUT: 1 - dst (the start address)

Copies n bytes from src to dst using a
single block move (LDIR). It does not
handle the case where the two areas
overlap - if dst lies inside the source
range use MEMMOVE instead. Returns dst.

USAGE:
  declare char a[64], b[64];
  extern "stdlib.kcl";
  memcpy(b,a,64);

=========================================
 MEMMOVE - copy memory (overlap-safe)
=========================================

INPUT : 3 - arg1 dst, arg2 src, arg3 n
OUTPUT: 1 - dst (the start address)

Copies n bytes from src to dst and works
even when the two areas overlap. If dst
is below src it copies forward (LDIR); if
dst is above src it copies backward
(LDDR), so no byte is over-written before
it is read. Returns dst. Use it to slide
data up or down inside a buffer.

USAGE:
  declare char buf[100];
  extern "stdlib.kcl";
  /* shift 90 bytes up by one: */
  memmove(buf+1,buf,90);

=========================================
 MEMSET - fill memory with a byte
=========================================

INPUT : 3 - arg1 dst, arg2 val, arg3 n
OUTPUT: 1 - dst (the start address)

Writes the byte val (only the low byte of
the argument) into n consecutive bytes
from dst. Handy to clear a buffer to 0 or
to fill it with spaces. Returns dst.

USAGE:
  declare char buf[256];
  extern "stdlib.kcl";
  memset(buf,0,256);   /* clear */
  memset(buf,' ',40);  /* spaces */

=========================================
 STRCAT - append one string to another
=========================================

INPUT : 2 - arg1 dst, arg2 src
OUTPUT: 1 - new length of dst

Appends the zero-terminated string src to
the end of the zero-terminated string dst
(writing over the old terminator) and
terminates the result. dst must have room
for both strings plus the zero. Returns
the new total length of dst.

USAGE:
  declare char s[20];
  extern "stdlib.kcl";
  strcpy(s,"FILE");
  strcat(s,".BIN"); /* "FILE.BIN" */

=========================================
 STRCHR - find first char in a string
=========================================

INPUT : 2 - arg1 s, arg2 c
OUTPUT: 1 - pointer to the char, or 0

Returns a pointer to the first character
c in the zero-terminated string s, or 0
if c does not occur. Only the low byte of
c is used. Looking for 0 returns a
pointer to the terminator.

USAGE:
  declare int p;
  extern "stdlib.kcl";
  p=strchr("NAME=VAL",'='); 
  /* p points at the '=' */

=========================================
 STRCMP - compare two strings
=========================================

INPUT : 2 - arg1 s1, arg2 s2
OUTPUT: 1 - 0 equal, 0FFFFh s1<s2, 1
s1>s2

Compares the two zero-terminated strings
s1 and s2 character by character. It
returns 0 if they are equal, 0FFFFh (-1)
if s1 sorts before s2, or 1 if s1 sorts
after s2 (by character code). The
comparison is case sensitive.

USAGE:
  extern "stdlib.kcl";
  if(strcmp(name,"YES")==0)
    print("matched");

=========================================
 STRCPY - copy a string
=========================================

INPUT : 2 - arg1 dst, arg2 src
OUTPUT: 1 - length copied (without the 0)

Copies the zero-terminated string src
into dst including the terminating zero,
and returns its length (not counting the
zero). dst must be large enough to hold
src plus the zero.

USAGE:
  declare char s[16];
  declare int n;
  extern "stdlib.kcl";
  n=strcpy(s,"HELLO"); /* n = 5 */

=========================================
 STRLEN - length of a string
=========================================

INPUT : 1 - arg1 s
OUTPUT: 1 - number of characters

Returns the number of characters in the
zero-terminated string s, not counting
the terminating zero. An empty string
gives 0.

USAGE:
  declare int n;
  extern "stdlib.kcl";
  n=strlen("hello");   /* 5 */

=========================================
 STRLWR - lower-case a string
=========================================

INPUT : 1 - arg1 s
OUTPUT: 1 - length of the string

Converts every upper-case letter A-Z in
the zero-terminated string s to lower
case, in place. Other characters are left
unchanged. Returns the length of the
string (it does not change).

USAGE:
  declare char s[16];
  extern "stdlib.kcl";
  strcpy(s,"Hello");
  strlwr(s);   /* "hello" */

=========================================
 STRNCMP - compare strings up to n chars
=========================================

INPUT : 3 - arg1 s1, arg2 s2, arg3 n
OUTPUT: 1 - 0 equal, 0FFFFh s1<s2, 1
s1>s2

Like STRCMP but compares at most n
characters. It returns 0 if the first n
characters are equal (or both strings end
first), 0FFFFh (-1) if s1 sorts before
s2, or 1 if after. Use it to match a
prefix.

USAGE:
  extern "stdlib.kcl";
  /* does it start with "GO" ? */
  if(strncmp(cmd,"GO",2)==0)
    print("go!");

=========================================
 STRRCHR - find last char in a string
=========================================

INPUT : 2 - arg1 s, arg2 c
OUTPUT: 1 - pointer to the char, or 0

Returns a pointer to the LAST character c
in the zero-terminated string s, or 0 if
c does not occur. Only the low byte of c
is used. Useful to find a file extension
by searching for the last '.'.

USAGE:
  declare int p;
  extern "stdlib.kcl";
  p=strrchr("A.B.TXT",'.'); 
  /* p points at the '.' before TXT */

=========================================
 STRUPR - upper-case a string
=========================================

INPUT : 1 - arg1 s
OUTPUT: 1 - length of the string

Converts every lower-case letter a-z in
the zero-terminated string s to upper
case, in place. Other characters are left
unchanged. Returns the length of the
string (it does not change).

USAGE:
  declare char s[16];
  extern "stdlib.kcl";
  strcpy(s,"Hello");
  strupr(s);   /* "HELLO" */

=========================================
 End
