String handling functions

Copyright © 2007 Christopher Williams (abbrev@gmail.com).

Contents

• Introduction
• C function prototypes
• Calling the functions
• Implementation notes
• Bugs
• Version History

Introduction

This is an implementation for the Z80 of the string handling functions found in the ANSI C Standard Library. All of the functions, except for two, are implemented. The "POSIX" locale is assumed in functions where applicable. Here is a complete list of the functions in the Standard Library:

• memchr
• memcmp
• memcpy
• memmove
• memset
• strcat
• strchr
• strcmp
• strcoll (same as strcmp in POSIX locale)
• strcpy
• strcspn
• strerror*
• strlen
• strncat
• strncmp
• strncpy
• strpbrk
• strrchr
• strspn
• strstr
• strtok*
• strxfrm (same as strncpy+strlen in POSIX locale)

*These functions are not implemented (yet).

Note: Strings are zero-terminated (end with a 0 byte), as in C; this allows them to be any length.

C function prototypes

For reference, here are the C function prototypes for all of the functions:

• void *memchr(const void *s, int c, size_t n);
• int memcmp(const void *s1, const void *s2, size_t n);
• void *memcpy(void *s1, const void *s2, size_t n);
• void *memmove(void *s1, const void *s2, size_t n);
• void *memset(void *s, int c, size_t n);
• char *strcat(char *s1, const char *s2);
• char *strchr(const char *s, int c);
• int strcmp(const char *s1, const char *s2);
• int strcoll(const char *s1, const char *s2);
• char *strcpy(char *s1, const char *s2);
• size_t strcspn(const char *s1, const char *s2);
• char *strerror(int errcode);
• size_t strlen(const char *s);
• char *strncat(char *s1, const char *s2, size_t n);
• int strncmp(const char *s1, const char *s2, size_t n);
• char *strncpy(char *s1, const char *s2, size_t n);
• char *strpbrk(const char *s1, const char *s2);
• char *strrchr(const char *s, int c);
• size_t strspn(const char *s1, const char *s2);
• char *strstr(const char *s1, const char *s2);
• char *strtok(char *s1, const char *s2);
• size_t strxfrm(char *s1, const char *s2, size_t n);

Calling the functions

Calling convention for all functions

All of the functions follow a common convention for arguments and return values.

Inputs

• For functions that use one string, HL contains its address.
• For functions that use two strings, DE contains the address of the first string, and HL contains the address of the second string.
• For a length argument, BC contains the length.
• For a character argument, E contains the character.

Outputs

• HL contains the address of a string or character.
• A contains the result of a comparison:
  • A < 0 if s1 < s2
  • A = 0 if s1 = s2
  • A > 0 if s1 > s2
• Carry flag indicates that the character(s) was/were not found (this is an extension to the C standard to facilitate assembly programming).

Here are the inputs and outputs of each of the functions in detail:

memchr - scan memory for a character

Input

• HL = s
• BC = n (number of bytes in s)
• E = c (byte to find)

Output

• HL = address of matching byte, or NULL if byte is not found
• Z80 extension: carry is set if byte is not found

memcmp - compare memory areas

Input

• DE = s1
• HL = s2
• BC = n

Output

• A < 0 if s1 < s2
• A = 0 if s1 = s2
• A > 0 if s1 > s2

memcpy - copy memory area

Input

• DE = dest
• HL = src
• BC = n (number of bytes to copy)

Output

• HL = dest

memmove - copy memory area

Input

• DE = dest
• HL = src
• BC = n (number of bytes to copy)

Output

• HL = dest

memset - fill memory with a constant byte

Input

• HL = s
• BC = n (number of bytes to copy)
• E = c (byte to fill)

Output

• HL = s

strcat - concatenate two strings

Input

• DE = dest
• HL = src

Output

• HL = dest

strchr - locate character in string

Input

• HL = s
• E = c (character to find)

Output

• HL = address of matching byte, or NULL if character is not found
• Z80 extension: carry is set if character is not found

strcmp - compare two strings

Input

• DE = s1
• HL = s2

Output

• A < 0 if s1 < s2
• A = 0 if s1 = s2
• A > 0 if s1 > s2

strcpy - copy a string

Input

• DE = dest
• HL = src

Output

• HL = dest

strcspn - search a string for a set of characters

Input

• DE = s
• HL = reject

Output

• HL = number of characters in the initial segment of s which are not in reject

strlen - calculate the length of a string

Input

• HL = s

Output

• HL = number of characters in s

strncat - concatenate two strings

Input

• DE = dest
• HL = src
• BC = n (maximum number of bytes to copy from src)

Output

• HL = dest

strncmp - compare two strings

Input

• DE = s1
• HL = s2
• BC = n (maximum number of bytes to compare)

Output

• A < 0 if s1 < s2
• A = 0 if s1 = s2
• A > 0 if s1 > s2

strncpy - copy a string

Input

• DE = dest
• HL = src
• BC = n (maximum number of bytes to copy)

Output

• HL = dest

strpbrk - search a string for any of a set of characters

Input

• DE = s
• HL = accept

Output

• HL = address of character in s that matches one of the characters in accept, or NULL if no such character is found
• Z80 extension: carry is set if character is not found

strrchr - locate character in string

Input

• HL = s
• E = c (character to find)

Output

• HL = address of last matching byte, or NULL if character is not found
• Z80 extension: carry is set if character is not found

strspn - search a string for a set of characters

Input

• DE = s
• HL = accept

Output

• HL = number of characters in the initial segment of s which consist only of characters from accept

strstr - locate a substring

Input

• DE = haystack
• HL = needle

Output

• HL = address of needle in haystack

strxfrm - string transformation

Input

• DE = dest
• HL = src
• BC = n (maximum number of characters to copy)

Output

• HL = number of bytes required to store the transformed string in dest excluding the terminating '\0' character.

Implementation notes

In this implementation, some functions depend on one or more other functions to work correctly. The following table lists these functions and their dependencies.

This means that, for example, if you include "strcat.asm", you should also include "strcpy.asm".

Bugs

There are no known bugs in this version. However, two of the functions in the Standard (strerror and strtok) are missing in this implementation. I did not implement strerror because it's almost useless without more of the C Standard Library. I did not implement strtok for a few reasons, one being that it is not reentrant (it stores static data), another being that it modifies the original string. I may write strtok in a future version, but for now it's missing.

Version History

• 2004-03-27. Wrote the strcmp function.
• 2007-01-27. Wrote all (except for two) other string handling functions.