$UnSpace

Normalize spaces and quotes

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $UnSpace function is the Unspace function.

This function normalizes a string by removing leading and trailing "space" characters and collapsing other sequences of "unquoted" spaces to single spaces. Normalization can also "undouble" quoted quote characters.

The $UnSpace function accepts three arguments and returns a string result which is the first argument, normalized according to the description of the returned value, as shown below.

Syntax

%out = $UnSpace(input, spaces, quotes)

Syntax terms

%out	This string is set to the normalized value of input.
input	The string to be normalized.
spaces	A string that is the set of space characters. The first character of this string is the replacement space character. The default set of space characters is the blank character.
quotes	A string that is the set of quote characters. If a quote character occurs twice in succession in quotes, the quote character should be "undoubled" when it occurs within a string quoted by that same character (see the usage note, below). No quote character may also occur as a space character. The default is that there are no quote characters.

Usage notes

• The returned value is the string value of the input argument, normalized as follows:
  • Leading space characters are removed. If there is not an unmatched quote, trailing space characters are removed.
  • Within a quoted substring, spaces are not collapsed nor replaced. If the quote character introducing the substring is specified as two occurrences in the quotes argument, each pair of consecutive occurrences of that character in the substring is replaced by a single occurrence of that character.

    If a quote character is not matched, the rest of the input is quoted.

  • Outside quoted substrings, each sequence of length one or more of any mixture of space characters is replaced by a single occurrence of the replacement space character.

Examples

Several examples follow, each one showing an invocation of $UnSpace and the corresponding result.

1. With only one argument, $UnSpace simply removes leading and trailing blank sequences and collapses other blank sequences:

   $UnSpace(' A B C ')

   The result is: A B C

2. $UnSpace can be used to make all space characters the same; here the space characters include the letters "X" and "S" and the blank character; they are all replaced by the letter "X":

   $UnSpace(' ASSSBSSXC ', 'XS ')

   The result is: AXBXC

3. Within a quoted substring, spaces are not changed:

   $UnSpace('."XAX"XBX', '.X', '"')

   The result is: "XAX".B

4. An unmatched quote (which is therefore, by definition, a trailing unmatched quote), causes the remander of the string to be quoted:

   $UnSpace('".A..."..B...C.."..', '.', '"')

   The result is: ".A...".B.C."..

5. Doubling a quote character in the quotes argument causes undoubling of quotes within a string quoted by that character:

   $UnSpace('" "" "', , '""')

   The result is: " " "

6. The following two inputs produce the same output; the first is a null quoted substring followed by the letter A and a final unmatched quote; the second is a quoted string whose first pair of characters is a doubled quote:

   $UnSpace('""A"', , '""')

   The result is: ""A"

   $UnSpace('"""A"', , '""')

   The result is: ""A"

7. If a quote character is not doubled in argument 3, undoubling for it is not performed:

   $UnSpace('" "" "', , '"')

   The result is: " "" "

8. Multiple quote characters can be specified; a quote character inside a substring quoted by a different character is not undoubled:

   $UnSpace('./A$$B/..$C//D$../E//F.', '.', '$$//')

   The result is: /A$$B/.$C//D$./E/F.

Products authorizing $UnSpace

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility