NOTES ON CHARACTER STRING FUNCTIONS AND SUBROUTINES By MARTY PORTNER 30-dec-77 ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- The purpose of these notes is to acquaint the user with the various character string functions now avail- able in the FORTRAN library. String functions perform operations upon FORTRAN 'BYTE' arrays which will be referred to as 'character vari- ables'.The only responsibility of those who wish to use these functions and subroutines is that each character vari- able be declared as a 'BYTE' array. For example, the fol- lowing declaration in a FORTRAN program will insure that the string functions and subroutines treat 'STRING' as a valid character variable: BYTE STRING(100) . The following pages explain each of the functions and subroutines in detail. These functions and subroutines reside in the li- brary SY:[1,1]STRLIB. Programs wishing use these functions should be linked something like this: MCR>TKB PROG,PROG=PROG,[1,1]STRLIB/LB . Notes on String Functions PAGE 2 I. FUNCTION ISIZE(STRING) This function returns an integer which is equal to the number of characters in the argument STRING. For example if the value of STRING is 'ABCD' then ISIZE(STRING) returns the value 4. Notes on String Functions PAGE 3 II. FUNCTION INDEX(STRA,STRB) This function searches STRA for the first occurrance of STRB and returns the character position within STRA that marks the start of STRB. For example, the value of I after the FORTRAN statement I=INDEX('12345678','456') will be 4. If STRB is longer than STRA or STRB is not found in STRA the value 0 (zero) is returned. Notes on String Functions PAGE 4 III. FUNCTION LEQ(STRA,STRB) This function determines whether STRA and STRB are lex- ically equal, i.e., have the same length and are equal in all character positions. LEQ returns the logical values .TRUE. , .FALSE. . In the call invoked by the following FORTRAN statement, LEQ returns the value .TRUE. : IF (LEQ('678','678')) GOTO 100 . This function will return the value .FALSE. for any of the following reasons: a) STRA and STRB differ in some character position, b) STRA and STRB are of different lengths , c) fewer than 2 arguments were passed to it. Note that blanks (spaces) are valid characters. Therefore, a call such as LEQ(' 65 ','65') will return the value .FALSE. (for reason b) above). Notes on String Functions PAGE 5 IV. SUBROUTINE STRING(STRA,STRB) This subroutine is used mainly for assignment purposes. The net effect after a call to STRING is that STRB will con- tain the same characters as STRA. For example the call CALL STRING('BIMBO',STR) will cause the value of STR to become the character string 'BIMBO'. Notes on String Functions PAGE 6 V. SUBROUTINE NULL(STR) This subroutine reassigns STR to the value of the null string (string of length zero). Notes on String Functions PAGE 7 VI. SUBROUTINE SUBSTR(STRA,START,LEN,STRB) This subroutine creates a substring out of the variable STRA starting at character position START (an integer) going for length LEN and assigns this string to STRB. For example CALL SUBSTR('7890',2,2,STRC) will cause the value of STRC to become '89'.It is important to point out here that STRA and STRB need not be different strings, and in general source and destination strings in all of the string subroutines need not be different. This permits the programmer to make immediate assignments without a call to 'STRING'. If STRB is omitted, STRA is assumed to be the destina- tion string. STRB may be omitted as in either of the two following examples: CALL SUBSTR(STR,2,2) or CALL SUBSTR(STR,2,2,) If the value of START exceeds the length of STRA, no operation is performed (call is ignored). If LEN exceeds the number of characters left in STRA (starting from posi- tion START), only these remaining characters of the source string are assigned to the destination string. Notes on String Functions PAGE 8 VII. SUBROUTINE CONCAT(STRA,STRB,STRC) This subroutine is used to combine two character strings under the operation of concatenation. The effect here is to concatenate STRA to STRB and place the result in STRC. Provided STRC is not one of STRA or STRB, STRA and STRB are unaffected by 'CONCAT'. As an example, let STRA = 'AFTER' and STRB = 'WORD'. After the call CALL CONCAT(STRA,STRB,STRC) the value of STRC will be 'AFTERWORD'. The values of STRA and STRB will be unchanged. As in SUBSTR, if STRC is omitted, STRA is assumed to be the destination string. Notes on String Functions PAGE 9 VIII. SUBROUTINE DUPL(STRA,NTIMES,STRB) This subroutine will duplicate STRA the specified number of times ( NTIMES ) and store the result in STRB. For example the call CALL DUPL('HUBBA',2,STRB) results in the assignment of the value of 'HUBBAHUBBA' to STRB. Notes on String Functions PAGE 10 IX. SUBROUTINE TRUNC(STR,POS) This subroutine allows the user to truncate a string at a specified position within that string.For example, if the value of STR is 'FORMAT', then after the call CALL TRUNC(STR,5) the value of STR will be 'FORM'. Care must be taken when using TRUNC, for it does not check to see if POS is greater than the length of STR. If POS is some value greater than the length of STR, a special 'string terminater' character may placed outside the user program's data area and strange, eerie and macabre results may ensue. TRUNC may be used to properly initialize character var- iables.Consider this sequence : 1) READ(1,100) N,STR 2) 100 FORMAT(Q,A1) 3) CALL TRUNC(STR,N+1) This sequence of FORTRAN statements will read a record from LUN=1 and, using Q format, will return in N the number of characters read into STR. Statement 3 then properly ini- tializes STR by truncating STR at position N+1. This in- sures that the proper termination character is placed after the last character read into STR, thus making STR a valid character variable. If the argument POS is omitted, TRUNC assumes the value POS=1 and thus behaves identically to NULL. Notes on String Functions PAGE 11 X. SUBROUTINE SDELET(STR,POS,LEN) This subroutine deletes the specified number of char- acters in STR starting at the specified position within STR. For example, let STR = 'SATURDAY'. Then after the call CALL SDELET(STR,2,5) the value of STR will be 'SAY' . If in any call POS is omitted, SDELET assumes the value POS=1. If LEN is zero or omitted, no characters are deleted from STR. if LEN is present and the sum LEN+POS is greater than ISIZE(STR), SDELET acts exactly like TRUNC, thus trun- cating STR at position POS. Notes on String Functions PAGE 12 XI. SUBROUTINE SINSRT(STRA,POS,STRB) The duty of this subroutine is to insert the string STRB within STRA at position POS. As an example, let STRA = 'BULBS'. Then after the call CALL SINSRT(STRA,5,'OU') the value of STRA will be 'BULBOUS'. The only argument that is allowed to be omitted is POS. Should POS be omitted, the value POS=1 is assumed.If POS is present and its value is greater than the length of STRA, no insertion is performed. Notes on String Functions PAGE 13 XII. FUNCTION IBREAK(STRA,SET) This function returns an integer that is equal to the position in STRA where any one of the individual characters of SET is found. For example, the following call will re- turn the character position of the first vowel in the argu- ment WORD: I=IBREAK(WORD,'AEIOU') IBREAK assumes no defaults and will return 0 (zero) if either none of the individual characters of SET is found in WORD, or fewer than two arguments are passed to it.