:TITLE: Modifying Strings - tolower, toupper, trim, format
;#
;# RCSID: $Header: /home/cvs/TclTutor3/lesson/Tcl_English/Tcl_English19.lsn,v 1.2 2010/12/22 15:53:19 clif Exp $
;# Copyright (c) 1995 Clif Flynt
;# 9300 Fleming Rd.
;# Dexter, MI  48130
;# clif@cflynt.com
;# See file "NOTICE" for licensing terms.
;#
:LESSON_TEXT_START_LEVEL 0:
These are the commands which modify a string.  None of these modify the
string in place.  
<DL>
<B><DT>string tolower</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from upper to lower case.
<B><DT>string toupper</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from lower to upper case.
<B><DT>string totitle</B> <I>string</I>
<DD> Returns <I>string</I> with the first letter converted from lower to upper case, and the rest converted to lower case.
<B><DT>string trim</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from both ends.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>string trimleft</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the left.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>string trimright</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the right.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>format</B> <I>formatString ?arg1 arg2 ... argN?</I>
<DD>Returns a string formatted in the same manner as the ANSI <B>sprintf</B>
procedure.  <I>FormatString</I> is a string including <B>% sequence </B>
references which define the format for the respective <I>arg</I>.
</DL>
:TEXT_END:

:LESSON_TEXT_START_LEVEL 1:
These are the commands which modify a string.  
Note that none of these modify the string in place.  In all cases a new string is returned.
<DL>
<B><DT>tolower</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from upper to lower case.
<B><DT>toupper</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from lower to upper case.
<B><DT>string totitle</B> <I>string</I>
<DD> Returns <I>string</I> with the first letter converted from lower to upper case, and the rest converted to lower case.
<B><DT>trim</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from both ends.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>trimleft</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the left.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>trimright</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the right.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>format</B> <I>formatString ?arg1 arg2 ... argN?</I>
<DD>Returns a string formatted in the same manner as the ANSI <B>sprintf</B>
procedure.  <I>FormatString</I> is a description of the formatting to use.
The full definition of this protocol is in the <CODE>format</CODE> man page.
A useful subset of the definition is that <I>formatString</I> consists of
literal words, backslash sequences, and <B>% fields</B>.  The <B>% fields</B>
are strings which start with a <B>%</B> and end with one of:
<UL COMPACT>
<B><LI>s</B>... Data is a string
<B><LI>d</B>... Data is a decimal integer
<B><LI>x</B>... Data is a hexadecimal integer
<B><LI>o</B>... Data is an octal integer
<B><LI>f</B>... Data is a floating point number
</UL>
The <B>%</B> may be followed by 
<UL COMPACT>
<B><LI>-</B>... Left justify the data in this field
<B><LI>+</B>... Right justify the data in this field
</UL>
The justification value may be followed by a number giving the minimum
number of spaces to use for the data.
</DL>
:TEXT_END:

:LESSON_TEXT_START_LEVEL 2:
The Tcl <CODE>string</CODE> command also includes several commands which
will modify a string.  When one of these commands is used, it returns a new
modified string, and leaves the original string intact.  If you wish to
replace the original string you can assign the new string to the original 
string name.
<P>
Tcl also includes a command that will take data from several sources and
create a new string.  The <CODE>format</CODE> command simplifies the 
creation of strings with a particular amount of data formatted in a 
particular way.
<DL>
<B><DT>tolower</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from upper to lower case.
<B><DT>toupper</B> <I>string</I>
<DD> Returns <I>string</I> with all the letters converted from lower to upper case.
<B><DT>string totitle</B> <I>string</I>
<DD> Returns <I>string</I> with the first letter converted from lower to upper case, and the rest converted to lower case.
<B><DT>trim</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from both ends.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>trimleft</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the left.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>trimright</B> <I>string ?trimChars?</I>
<DD> Returns <I>string</I> with all occurrences of <I>trimChars</I> removed
from the right.  By default <I>trimChars</I> are whitespace (spaces, tabs,
newlines)
<B><DT>format</B> <I>formatString ?arg1 arg2 ... argN?</I>
<DD>Returns a string formatted in the same manner as the ANSI <B>sprintf</B>
procedure.  <I>FormatString</I> is a description of the formatting to use.
<P>
The full definition of this protocol is in the <CODE>format</CODE> man page.
A useful subset of the definition is that <I>formatString</I> consists of
literal words, backslash sequences, and <B>% fields</B>.  The <B>% fields</B>
are strings which start with a <B>%</B> and end with one of:
<UL COMPACT>
<B><LI>s</B>... Data is a string
<B><LI>d</B>... Data is a decimal integer
<B><LI>x</B>... Data is a hexadecimal integer
<B><LI>o</B>... Data is an octal integer
<B><LI>f</B>... Data is a floating point number
</UL>
The <B>%</B> may be followed by 
<UL COMPACT>
<B><LI>-</B>... Left justify the data in this field
<B><LI>+</B>... Right justify the data in this field
</UL>
The justification value may be followed by a number giving the minimum
number of spaces to use for the data.
</DL>
<P>
The <I>formatString</I> argument to the <CODE>format</CODE> command needs
some further explanation.  
<P>
A simple format string would be just "%s".  This would print out the
<I>arg</I> as a simple string. ie:
<PRE>
set xx [format "%s" "This is a test"]
and
set xx "This is a test"
</PRE>
are equivalent statements.  
<P>
The format command is more useful when you are building tables, and want
each entry to fill the same number of spaces, or when you are dealing with
floating point numbers and want to control the precision that is reported.
<P>
The example below shows the <CODE>format</CODE> command being used to
create a simple table.  The string <CODE>%-20s</CODE> places the first 
<I>arg</I> in a 20 space field, and puts the first character of <I>arg</I>
in the lefttmost of the 20 spaces.  This is called <B>left justified</B>.
<P>
The string <CODE>%10s</CODE> puts the second <I>arg</I> in a field 10
spaces long, with the last character in the <I>arg</I> in the rightmost 
space of the field.  This is <B>right justified</B>, and is the default
mode for strings.
<P>
The string <CODE>%10d</CODE> treats the second <I>arg</I> as an integer,
and right justifies it.
<P>
In the last format statement, the <B>%10.2f</B> formats the <I>arg</I>
with 10 spaces, 2 of which are to the right of the decimal.  Note that
the Pentium style price is rounded to the nearest cent.
:TEXT_END:

:CODE_START:
set upper "THIS IS A STRING IN UPPER CASE LETTERS"
set lower "this is a string in lower case letters"
set trailer "This string has trailing dots ...."
set leader "....This string has leading dots"
set both  "((this string is nested in parens )))"

puts "tolower converts this: $upper"
puts "              to this: [string tolower $upper]\n"
puts "toupper converts this: $lower"
puts "              to this: [string toupper $lower]\n"
puts "trimright converts this: $trailer"
puts "                to this: [string trimright $trailer .]\n"
puts "trimleft converts this: $leader"
puts "               to this: [string trimleft $leader .]\n"
puts "trim converts this: $both"
puts "           to this: [string trim $both "()"]\n"

set labels [format "%-20s %+10s " "Item" "Cost"]
set price1 [format "%-20s %10d Cents Each" "Tomatoes" "30"]
set price2 [format "%-20s %10d Cents Each" "Peppers" "20"]
set price3 [format "%-20s %10d Cents Each" "Onions" "10"]
set price4 [format "%-20s %10.2f per Lb." "Steak" "3.59997"]

puts "\n Example of format:\n"
puts "$labels"
puts "$price1"
puts "$price2"
puts "$price3"
puts "$price4"
:TEXT_END:

