9.5.2 String functions

There are a number of useful built-in functions which manipulate strings. Remember that an E-string can be used wherever a normal string can, but normal strings cannot be used where an E-string is required. If a parameter is marked as string then a normal or E-string can be passed as that parameter, but if it is marked as e-string then only an E-string may be used. Some of these functions have default arguments, which means you don't need to specify some parameters to get the default values (see 7.3 Default Arguments). (You can, of course, ignore the defaults and always give all parameters.)

String(maxsize)

Allocates memory for an E-string of maximum size maxsize and returns a pointer to the string data. It is used to make space for a new E-string, like a STRING declaration does. The following code fragments are practically equivalent:

  DEF s[37]:STRING

  DEF s:PTR TO CHAR
  s:=String(37)

The slight difference is that there may not be enough memory left to hold the E-string when the String function is used. In that case the special value NIL (a constant) is returned. Your program must check that the value returned is not NIL before you use it as an E-string (or dereference it).

The memory for the declaration version, STRING, is allocated when the program is run, so your program won't run if there isn't enough memory. The String version is often called dynamic allocation because it happens only when the program is running; the declaration version has allocation done by the E compiler.

The memory allocated using String can be deallocated using DisposeLink (see 11.3.5 System support functions).

StrCmp(string1,string2,length=ALL)

Compares string1 with string2 (they can both be normal or E-strings). Returns TRUE if the first length characters of the strings match, and FALSE otherwise. The length defaults to the special constant ALL which means that the strings must agree on every character. For example, the following comparisons all return TRUE:

  StrCmp('ABC',  'ABC')
  StrCmp('ABC',  'ABC', ALL)
  StrCmp('ABCd', 'ABC',    3)
  StrCmp('ABCde','ABCxxjs',3)

And the following return FALSE (notice the case of the letters):

  StrCmp('ABC',  'ABc')
  StrCmp('ABC',  'ABc', ALL)
  StrCmp('ABCd', 'ABC', ALL)

StrCopy(e-string,string,length=ALL)

Copies the contents of string to e-string, and also returns a pointer to the resulting E-string (for convenience). Only length characters are copied from the source string, but the special constant ALL can be used to indicate that the whole of the source string is to be copied (and this is the default value for length). Remember that E-strings are safely manipulated, so the following code fragment results in s becoming `More th', since its maximum size is (from its declaration) seven characters.

  DEF s[7]:STRING
  StrCopy(s, 'More than seven characters', ALL)

A declaration using STRING (or ARRAY) reserves a small part of memory, and stores a pointer to this memory in the variable being declared. So to get data into this memory you need to copy it there, using StrCopy. If you're familiar with very high-level languages like BASIC you should take care, because you might think you can assign a string to an array or an E-string variable. In E (and languages like C and Assembly) you must explicitly copy data into arrays and E-strings. You should not do the following:

  /* You don't want to do things like this! */
  DEF s[80]:STRING
  s:='This is a string constant'

This is fairly disastrous: it throws away the pointer to reserved memory that was stored in s and replaces it by a pointer to the string constant. s is then no longer an E-string, and cannot be repaired using SetStr. If you want s to contain the above string you must use StrCopy:

  DEF s[80]:STRING
  StrCopy(s,'This is a string constant')

The moral is: remember when you are using pointers to data and when you need to copy data. Also, remember that assignment does not copy large arrays of data, it copies only pointers to data, so if you want to store some data in an ARRAY or STRING type variable you need to copy it there.

StrAdd(e-string,string,length=ALL)

This does the same as StrCopy but the source string is copied onto the end of the destination E-string. The following code fragment results in s becoming `This is a string and a half'.

  DEF s[30]:STRING
  StrCopy(s, 'This is a string', ALL)
  StrAdd(s,  ' and a half')

StrLen(string)

Returns the length of string. This assumes that the string is terminated by a null character (i.e., ASCII zero), which is true for any strings made from E-strings and string constants. However, you can make a string constant look short if you use the null character (the special sequence `\0') in it. For instance, these calls all return three:

  StrLen('abc')
  StrLen('abc\0def')

In fact, most of the string functions assume strings are null-terminated, so you shouldn't use null characters in your strings unless you really know what you're doing.

For E-strings StrLen is less efficient than the EstrLen function.

EstrLen(e-string)

Returns the length of e-string (remember this can be only an E-string). This is much more efficient than StrLen since E-strings know their length and it doesn't need to search the string for a null character.

StrMax(e-string)

Returns the maximum length of e-string. This is not necessarily the current length of the E-string, rather it is the size used in the declaration with STRING or the call to String.

RightStr(e-string1,e-string2,length)

This is like StrCopy but it copies the right-most characters from e-string2 to e-string1 and both strings must be E-strings. At most length characters are copied, and the special constant ALL cannot be used (to copy all the string you should, of course, use StrCopy). For instance, a value of one for length means the last character of e-string2 is copied to e-string1.

MidStr(e-string,string,index,length=ALL)

Copies the contents of string starting at index (which is an index just like an array index) to e-string. At most length characters are copied, and the special constant ALL can be used if all the remaining characters in string should be copied (this is the default value for length). For example, the following two calls to MidStr result in s becoming `four':

  DEF s[30]:STRING
  MidStr(s, 'Just four',      5)
  MidStr(s, 'Just four apples', 5, 4)

InStr(string1,string2,startindex=0)

Returns the index of the first occurrence of string2 in string1 starting at startindex (in string1). startindex defaults to zero. If string2 could not be found then -1 is returned.

TrimStr(string)

Returns the address of (i.e., a pointer to) the first non-whitespace character in string. For instance, the following code fragment results in s becoming `12345'.

  DEF s:PTR TO CHAR
  s:=TrimStr('  \n \t   12345')

LowerStr(string)

Converts all uppercase letters in string to lowercase. This change is made in-place, i.e., the contents of the string are directly affected. The string is returned for convenience.

UpperStr(string)

Converts all lowercase letters in string to uppercase. Again, this change is made in-place and the string is returned for convenience.

SetStr(e-string,length)

Sets the length of e-string to length. E-strings know how long they are, so if you alter an E-string (without using an E-string function) and change its size you need to set its length using this function before you can use it as an E-string again. For instance, if you've used an E-string like an array (which you can do) and written characters to it directly you must set its length before you can treat it as anything other than an array:

  DEF s[10]:STRING
  s[0]:="a"     /* Remember that "a" is a character value. */
  s[1]:="b"
  s[2]:="c"
  s[3]:="d"     /* At this point s is just an array of CHAR. */
  SetStr(s, 4)  /* Now, s can be used as an E-string again.  */
  SetStr(s, 2)  /* s is a bit shorter, but still an E-string.*/

Notice that this function can be used to shorten an E-string, but this change is destructive (it cannot easily be reversed to give the original, longer E-string).

Val(string,address=NIL)

What this function does is straight-forward but how you use it is a bit complicated. Basically, it converts string to a LONG integer. Leading whitespace is ignored, and a leading `%' or `$' means that the string denotes a binary or hexadecimal integer (in the same way they do for numeric constants). The decoded integer is returned as the regular return value (see 7.4 Multiple Return Values). The number of characters of string that were read to make the integer is stored at address, which is usually a variable address (from using {var}), and is also returned as the first optional return value. If address is the special constant NIL (i.e., zero) then this number is not stored (this is the default value for address). You can use this number to calculate the position in the string which was not part of the integer. If an integer could not be decoded from the string then zero is returned as both return values and stored at address.

Follow the comments in this example, and pay special attention to the use of the pointer p.

  DEF s[30]:STRING, value, chars, p:PTR TO CHAR
  StrCopy(s, ' \t \n 10 \t $3F -%0101010')
  value, chars:=Val('abcde 10 20')  -> Two return values...
    /* After the above line, value and chars will both be zero */
  value:=Val(s, {chars})          -> Use address of chars
    /* Now value will be 10, chars will be 7 */
  p:=s+chars
    /* p now points to the space after the 10 in s */
  value, chars:=Val(p)
    /* Now value will be $3F (63), chars will be 6 */
  p:=p+chars
    /* p now points to the space after the $3F in s */
  value, chars:=Val(p)
    /* Now value will be -%0101010 (-42), chars will be 10 */

Notice the two different ways of finding the number of characters read: a multiple-assignment and using the address of a variable.

There's a couple of other string functions (ReadStr and StringF) which will be discussed later (see 11.3.1 Input and output functions).

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.