<<TOC>>
----
'''`[string] trim`''' removes characters from the beginning and end of a string.


** Synopsis **

    :   '''string trim''' ''string ?chars?''


** See Also **
   [string map]:   Replace substrings in a string.

   [string]    :   all the other "string"-commands

   [Trimming indentation]:   

   [textutil%|%textutil]:   Provides [regular expressions%|%regular expression] variants of the `string trim` commands, as well as `trimPrefix` an `trimEmptyHeading`.


** Description **

Returns a value equal to ''string'' except that any leading or trailing characters 
that occur in ''chars'' are removed. <<br>>
If ''chars'' is not specified then white space is removed (spaces, tabs, newlines, and carriage returns).


----
** Examples **
***Example 1***
======
# http://ideone.com/IX2f6Y
 set s1 " Hello ! "
 set s2 [string trim $s1]
 puts "<$s1> <$s2>"
#
 set s1 "*** Hello_###"
 set s2 [ string trim $s1 "*#_" ]
 puts "<$s1> <$s2>"
#. 
======

'''Output:'''
======none
< Hello ! > <Hello !>
<*** Hello_###> < Hello>
======

***Example 2***
======
# http://codepad.org/b4bHNWjo
 set s1 " * Hello ** "
 set s2 [string trim $s1]
 set s3 [string trim $s1 " *"]
 puts "<$s1>\n<$s2>\n<$s3>"
======

'''Output:'''
======none
< * Hello ** >
<* Hello **>
<Hello>
======

----

** What Constitutes Whitespace **

See [TIP] [http://www.tcl.tk/cgi-bin/tct/tip/318.html%|%#318: Extend Default Whitespace in 'string trim' Beyond ASCII].

[escargo] 2008-06-02:
This also related to behavior discussed in [comp.lang.tcl] with the subject,
"string trim not trimming special space characters" (starting on 2008-03-04).

The characters removed by `string trim ''string''` (with no ''chars'' argument) are '''not'''
all the ones for which `[string is] space ''char''` returns `1`.

I think the [TIP] should also include Unicode nonbreaking spaces. 

[LV]: You could either update the TIP page with your concerns, or post a comment over on the [TCT] mailing list.


** Discussion **

[MiHa] 2015-05-17: As I already ranted, missing examples are a common shortcoming in the docs.
As an example, how I would like examples done (here in the wiki, as well as in the help-system
that comes with the tcl/tk-installation. <<br>>
I added a demo-section, with links to two different online-compilers/interpretes, 
where the examples can be seen "live".

[pyk] 2015-05-17:  The added examples are better than what previously passed as
examples on this page.  I've adjusted them to conform to the [Tcl minimal
escaping style].  @MiHa: if you as the author of the new examples take
exception to that, just change them back to your own preferred style.  
As far as putting the '''Description''' section before the Synopsis section, 
I think there's enough precedent having an unnamed summary with the '''description'''
coming after the synopsis to justify leaving the current order as it is.

'''MiHa''' 2015-05-18: I don't like that style, so changed it back. <<br>>
Also, I feel a document should start with a proper headline.


<<categories>> Command | String Processing