C64 OS PROGRAMMER'S GUIDE

Chapter 4: Using the KERNAL → String (module)

• String Manipulation
  • strlen
  • memncpy
  • strdel
  • strins
• Character Manipulation
  • asc2pet
  • pet2asc
  • pet2scr
  • tolower
  • toupper
  • isdigit

String Manipulation

The following string manipulation routines are designed to operate on C-strings. Sequences of characters in memory that end with null ($00) byte. These routines are not designed to be equivalent to the functions found in the standard C string library, even though their names sound familiar. Additional string routines will be added to the string library. The KERNAL provides these routines because they are used by very low-level processes.

strlen

Purpose	Measure the length of a C-string with a 16-bit result.
Module offset	0
Communication registers	X, Y
Stack requirements	3 bytes
Zero page usage	None
Registers affected	X, Y
Input parameters	RegPtr → Pointer to a C-string
Output parameters	RegWrd ← Length of the C-string

Description: This is routine is used to measure the length of a C-string. It does not affect the A register. Pass a RegPtr to the string to be measured, and a RegWrd is returned with the 16-bit length of the string.

memncpy

Purpose	Copy memory of 16-bit length from one memory region to another.
Module offset	3
Communication registers	A, X, Y
Stack requirements	2 bytes
Zero page usage	Custom
Registers affected	A, X, Y
Input parameters	X → ZP address to a memory source Y → ZP address to a memory destination X → ZP address to a 16-bit length to copy
Output parameters	None

Description: This is routine is used to copy memory pointed to by a zero page pointer to a place in memory pointed to by another zero page pointer. The length to copy is a 16-bit length stored in another zero page pair of bytes. It is necessary to set up the zero page values before calling this routine.

There are no range checks and no checks for the allocation status of the destination. It is only safe to copy the memory between non-overlapping regions, or overlapping regions in which the destination address is lower in memory than the source address. If the regions overlap and destination is higher in memory than the source address, some portion of the data will become corrupted during the transfer.

The following example copies 768 bytes from $1000 to $3000, and uses 6 zero page bytes that are chosen arbitrarily for this code example.

strdel

Purpose	Remove characters in a string at an index and shift end of string back.
Module offset	24
Communication registers	A, Y
Stack requirements	4 bytes
Zero page usage	$61, $62, $63, $64
Registers affected	A, Y
Input parameters	strptr → Pointer to C-string Y → start index A → number of characters to delete
Output parameters	None

Description: This routine is used to delete a number of characters from a C-string, and shift all of the characters following the deleted range, up to the null terminator byte, back to the start index of the deletion. This closes the gap left by the characters that were deleted.

Before calling this routine, the zero page pointer strptr, defined in //os/s/:string.s, must be configured to point to the start of the C-string. This routine can only operate on a string with a maximum length of 255 characters. This routine is used by the TKInput class.

strins

Purpose	Insert space into a string by shifting up all characters starting at index.
Module offset	27
Communication registers	A, Y
Stack requirements	4 bytes
Zero page usage	$61, $62, $63, $64
Registers affected	A, Y
Input parameters	strptr → Pointer to C-string Y → start index A → number of spaces to insert
Output parameters	None

Description: This routine is used to insert a number of spaces into a C-string, and shift all of the characters following the start index, up to the null terminator byte, rightward by the number specified. This opens a gap into which characters can be inserted. After this routine returns, the gap contains remnants of what used to be at the memory where the gap now is.

Before calling this routine, the zero page pointer strptr, defined in //os/s/:string.s, must be configured to point to the start of the C-string. This routine can only operate on a string with a maximum length of 255 characters. This routine is used by the TKInput class.

---

Character Manipulation

This set of 6 routines all operate on a single byte at a time. The byte is passed in the accumulator, the value is modified and returned in the accumulator. Except for isdigit which does not modify the input, but returns the result in the carry. These routines can be linked one to the other. For example, asc2pet, then tolower, then pet2scr can be called one after the next, and the accumulator will get transformed from an ASCII character to a lower case screencode version of the same character.

asc2pet

Purpose	Convert a byte of ASCII to PETSCII.
Module offset	6
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	A
Input parameters	A → ASCII character
Output parameters	A ← PETSCII equivalent character

Description: This routine is used to convert a single byte of ASCII to its PETSCII equivalent. Non-mapping characters are converted to a space ($20, decimal 32.)

pet2asc

Purpose	Convert a byte of PETSCII to ASCII.
Module offset	9
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	A
Input parameters	A → PETSCII character
Output parameters	A ← ASCII equivalent character

Description: This routine is used to convert a single byte of PETSCII to its ASCII equivalent. Non-mapping characters are converted to a space ($20, decimal 32.)

pet2scr

Purpose	Convert a byte of PETSCII to a screencode.
Module offset	12
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	A
Input parameters	A → PETSCII character
Output parameters	A ← Screencode equivalent character

Description: This routine is used to convert a single byte of PETSCII to its Screencode equivalent. PETSCII codes that do not have printable representations are converted into various reversed screencodes.

tolower

Purpose	Convert a byte of PETSCII to a lowercase version of itself.
Module offset	15
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	A
Input parameters	A → Mixed-case PETSCII character
Output parameters	A ← Lowercase PETSCII character

Description: This routine is used to convert a single byte of PETSCII to its lowercase equivalent. This only affects a PETSCII byte that is in the range of "A" to "Z" (uppercase) by converting it to "a" to "z" (lowercase). All other PETSCII input values are returned unmodified.

toupper

Purpose	Convert a byte of PETSCII to an uppercase version of itself.
Module offset	18
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	A
Input parameters	A → Mixed-case PETSCII character
Output parameters	A ← Uppercase PETSCII character

Description: This routine is used to convert a single byte of PETSCII to its uppercase equivalent. This only affects a PETSCII byte that is in the range of "a" to "z" (lowercase) by converting it to "A" to "Z" (uppercase). All other PETSCII input values are returned unmodified.

isdigit

Purpose	Determine if a PETSCII character is a digit.
Module offset	21
Communication registers	A
Stack requirements	2 bytes
Zero page usage	None
Registers affected	None
Input parameters	A → PETSCII character
Output parameters	C ← Set if the character is a digit C ← Clear if the character is a non-digit

Description: This routine is used to check if a single byte of PETSCII is a digit (0 through 9). The carry is used to indicate its status as a digit. Carry set if it is a digit, carry clear if it is not a digit. The accumulator is not modified by calling this routine.

KERNAL Modules in Alphabetical Order

• File
• Input
• Math
• Memory
• Menu
• Screen
• Service
• String
• Timers
• Toolkit

KERNAL Modules in Module Lookup Table Order

• Memory
• Input
• String
• Math
• Screen
• Menu
• Service
• File
• Toolkit
• Timers

Return to Using the KERNAL → KERNAL Modules

---

Table of Contents

This document is subject to revision updates.

Last modified: Apr 20, 2023