String: String Operations

      $func  String         e.Source = s.String;
      $func  StringInit     s.String s.Len s.Fill = ;
      $func  StringFill     s.String s.Fill = ;
      $func  StringLength   s.String = s.Len;
      $func  StringRef      s.String s.Index = s.Char;
      $func  StringSet      s.String s.Index s.Char = ;
      $func  StringReplace  s.String e.Source = ;
      $func  Substring      s.String s.Index s.Len = s.NewString;
      $func  SubstringFill  s.String s.Index s.Len s.Fill = ;

These functions provide a way to create, modify, and access strings. The arguments of the functions must satisfy the following restrictions. s.String must be a reference to a string, s.Index and s.Len non-negative integers, s.Fill a character symbol, e.Source a sequence of references to strings, word symbols, and character symbols.

If one or more of the above restrictions are violated, the result returned by the functions is $error(Fname "Invalid argument"), where Fname is the function's name.

At any moment, a string contains a finite sequence (which may be empty) of character symbols, which is said to be the contents of the string. A string containing a sequence of N+1 character symbols Gc0, Gc1, ..., GcN is said to have the length N+1. The contents of the string will be written as

      Gc0 Gc1 ... GcN

Thus the string components Gc0, Gc1, ..., GcN are numbered starting from zero.

String creates a new string and returns a reference to the new string. The contents of the new string is formed from e.Source in the following way.

Suppose the parameter e.Source has the form Gs1 Gs2 ... GsM, where each symbol Gsj is either a character symbol, a word symbol, or a reference to a string. Then each symbol Gsj is transformed as follows.

If Gsj is a character symbol Gc, Gsj is left unchanged.

If Gsj is a word symbol, Gsj is replaced with the character sequence that is the contents of the word.

If Gsj is a reference to a string, Gsj is replaced with the contents of the string (without changing the state of the string).

The value of the parameter e.Source thus transformed becomes the contents of the new string.

StringInit replaces the contents of the string referred to by s.String with a new contents of length s.Len where all the characters are s.Fill.

StringFill replaces each character in the string referred to by s.String with s.Fill. The length of the string remains unchanged.

StringLength returns the length of the string referred to by s.String.

StringRef returns the character contained in the position s.Index in the string referred to by s.String.

StringSet replaces the character contained in the position s.Index in the string referred to by s.String with s.Char. The length of the string remains unchanged.

StringReplace replaces the contents of the string referred to by s.String with the new contents formed from s.Source in the same way as it is done by the function String.

Substring creates a new string, and returns a reference to the new string, the contents of which is formed in the following way. Let the contents of the string referred to by s.String be Gc0 Gc1 ... GcN. Then the contents of the new string is obtained by removing the first s.Index characters from this sequence, and selecting the first s.Len characters of the remaining sequence.

The contents of the source string remains unchanged.

SubstringFill replaces s.Len consecutive characters in the string referred to by s.String with s.Char, starting from the character in the position s.Index. The length of the string remains unchanged.

If the length of the string is not sufficient for one of the above operations to be performed, the string remains unchanged, and the value returned by the functions is $error(Fname "Index out of range"), where Fname is the function's name.

If one of the above operations has to create a string contents whose length exceeds the size limit imposed by the Refal Plus implementation, the string remains unchanged, and the value returned by the functions is $error(Fname "Size limit exceeded"), where Fname is the function's name.