REBOL 3 Functions: trim

Contents

Description

Trim removes unwanted values, normally it trims whitespace from a string! or none! values from a block! or object!.

Here is an example of a string:

str: "  string   "
probe trim str
"string"

Note that the str is modified. To avoid that, use copy:

new-str: trim copy str

For a block! :

trim reduce [none 'a none 'b none]
[a b]

It removes the none! values from the block. (And it will also remove unset! values as well.)

Note that the block is modified. But, in this example, reduce creates a unique copy, so the original is not effected.

And for an object! :

trim system/options
make object! [
    home: %/C/Program%20Files/
    path: %/C/rebol/r3/
    boot: %/C/rebol/r3/view.exe
    binary-base: 16
    decimal-digits: 15
]

Because object fields cannot be removed (due to binding) the result of trim of an object is always to return a new shallow object. (The values of the object are not deep-copied or rebound.)

The new object only shows fields that have actual value (not none or unset.)

Details on trimming strings

The default for TRIM is to remove whitespace characters (tabs and spaces) from the heads and tails of every line of a string. Empty leading and trailing lines are also trimmed.

When a string includes multiple lines, the head and tail whitespace will be trimmed from each line (but not within the line):

str: {
    Now is the winter
    of our discontent
    made glorious summer
    by this sun of York.
}
probe trim str
{Now is the winter
of our discontent
made glorious summer
by this sun of York.
}

The line terminator of the final line is preserved.

As mentioned above, empty leading and trailing lines are also trimmed:

probe trim {

    Non-empty line.
    Non-empty line.
    Non-empty line.

}
{Non-empty line.
Non-empty line.
Non-empty line.
}

Note that TRIM modifies the string in the process.

str: "  string   "
trim str
probe str
"string"

TRIM does not copy the string. If that's what you want, then use TRIM with COPY to copy the string before trimming it.

Several refinements to TRIM are available. To trim just the head and/or tail of a string you can use the /HEAD or /TAIL refinements.

probe trim/head "  string  "
"string  "

probe trim/tail "  string  "
"  string"

probe trim/head/tail "  string  "
"string"

When using /HEAD or /TAIL, multiple lines are not affected:

probe trim/head {  line 1
    line 2
    line 3
}
{line 1
line 2
line 3
}

To trim just the head and tail of a multiline string, but none of its internal spacing:

str: {  line 1
    line 2
        line 3
            line 4
                line 5  }
probe trim/head/tail str
{line 1
line 2
    line 3
        line 4
            line 5}

If you use TRIM/LINES then all lines and extra spaces will be removed from the text. This is useful for word wrapping and web page kinds of applications.

str: {
    Now   is
    the
    winter
}
probe trim/lines str
"Now is^/the^/winter"

You can also remove /ALL space:

probe trim/all " Now is   the winter "
"Nowisthewinter"

str: {
    Now   is
    the
    winter
}
probe trim/all str
"Nowisthewinter"

One of the most useful TRIM refinements is /AUTO which will do a "smart" trim of the indentation of text lines. This mode detects the indentation from the first line and preserves indentation for the lines to follow:

probe trim/auto {
    line 1
        line 2
        line 3
            line 4
    line 5
}
{line 1
 line 2
 line 3
     line 4
 line 5
 }

This is useful for sections of text that are embedded within code and indented to the level of the code.

To trim other characters, the /WITH refinement is provided. It takes an additional string that specifies what characters to be removed.

str: {This- is- a- line.}
probe trim/with str "-"
"This is a line."

str: {This- is- a- line.}
probe trim/with str "- ."
"Thisisaline"

TRIM on blocks

When trim is used on a block!, it strips all none! values from the block:

trim reduce [1 2 none]
[1 2]

Note that trim modifies the argument block.

TRIM on objects

When trim is used on an object!, it will return a new object that has all none! values removed:

obj: make object [arg1: 10 arg2: none]
trim obj
make object! [
    arg1: 10
]