StringMod  -  String manipulation module

by Alan Wrigley

This item complements the article Creating Relocatable Modules on page 46 of this month's RISC User magazine, which describes how to implement your own SWI calls using a module. The module presented here is called StringMod, and this provides a set of SWIs for manipulating character strings.

Running the item from the RISC User menu system opens a directory viewer containing the module together with its source code program. By studying the source code in conjunction with the accompanying article (as well as Part 1 last month), you will get a clearer idea of how modules are constructed and how to implement SWI calls.

StringMod is installed by double-clicking on the StringRM icon in a directory viewer. Once installed, the module adds the following string manipulation SWIs to the system:
  String_CaseConvert
  String_Split
  String_Shorten
  String_Compare
These will be particularly useful for Assembler programmers for whom there are few string handling functions available in the operating system. One or two of the calls will also be useful to Basic programmers as they perform functions that require unwieldy code in Basic. It is intended that further functions will be added at a later date and an upgrade published on the magazine disc.

The parameters for the SWI calls are as follows:
  
  
&D0180 String_CaseConvert

  On entry:

  R0 = reason code
       0: convert to upper case
       1: convert to lower case
       2: capitalise all first letters
  R1 = pointer to string
  R2 = pointer to buffer

  On exit:

  buffer holds converted string

This call enables you to convert a string to upper case characters, to lower case characters, or to mixed case where the first letter of each word is capitalised.

------------------------------------------------

&D0181 String_Split

  On entry:

  R0 = reason code
       0: split at position in R6
       1: split before first occurrence of char in R6
       2: split after first occurrence of char in R6
       3: split at first occurrence of char in R6, ignoring char
       4: split before last occurrence of char in R6
       5: split after last occurrence of char in R6
       6: split at last occurrence of char in R6, ignoring char
  R1 = pointer to string
  R2 = buffer 1
  R3 = buffer 2
  R4 = length of buffer 1
  R5 = length of buffer 2
  R6 = position in string, or character
       depending on reason code in R0

  On exit:

  Buffer 1 holds first string
  Buffer 2 holds second string
  Error generated if either buffer overflows

This call enables you to split a string, either at a specified position, or at the first or last occurrence of a specified character. In the case of the latter two options, you can choose whether the string is split before the character specified or after it, with an option to remove the character in the process. For example, you could use this call to split a file's pathname from its leafname by using reason code 6 in R0, and the ASCII value of "." (46) in R6. If you wish to include the full stop at the end of the pathname, use reason code 5 instead.

------------------------------------------------

&D0182 String_Shorten

  On entry:

  R0 = flags
       Bit 0 set:   Remove from beginning
             unset: Remove from end
       Bit 1 set:   R4 = no of chars to remove
             unset: R4 = no of chars to include
  R1 = pointer to string
  R2 = pointer to buffer
  R3 = length of buffer
  R4 = number of chars

  On exit:

  Buffer holds shortened string

This call enables you to shorten a string by a specified amount, or to shorten it to a specified length. Characters may be removed from either end of the string.

------------------------------------------------

&D0183 String_Compare

  On entry:

  R0 = flags
       Bit 0 set:   consider case
             unset: ignore case
       Bit 1 set:   find string 2 within string 1
             unset: match complete string
  R1 = pointer to string 1
  R2 = pointer to string 2

  On exit:

  If flag bit 1 unset on entry:
      R0 = 0 if no match, 1 if strings match

  If flag bit 1 set on entry:
      R0 = 0 if no match, otherwise position of string 2 in string 1

This call enables you to compare two strings. Depending on the state of the flags in R0, case is either taken into account or not. Also the flags determine whether to attempt to match the two complete strings, or whether to indicate the position of the second string in the first.

Copyright  Alan Wrigley 1995
