summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2004-05-24 23:31:42 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2004-05-24 23:31:42 (GMT)
commitef7d2e991dce0522cc493243c5bd0d91df5fc06a (patch)
tree22e615f8fef8ddbf0c194e78db3f38a4d60601e8
parent8357e1bbb6ca9e656801de05df415698640e17bb (diff)
downloadtcl-ef7d2e991dce0522cc493243c5bd0d91df5fc06a.zip
tcl-ef7d2e991dce0522cc493243c5bd0d91df5fc06a.tar.gz
tcl-ef7d2e991dce0522cc493243c5bd0d91df5fc06a.tar.bz2
Added examples
-rw-r--r--doc/binary.n24
-rw-r--r--doc/clock.n37
-rw-r--r--doc/proc.n22
-rw-r--r--doc/regsub.n30
4 files changed, 83 insertions, 30 deletions
diff --git a/doc/binary.n b/doc/binary.n
index 0a863c1..98775e0 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: binary.n,v 1.17 2004/05/13 10:12:56 dkf Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.18 2004/05/24 23:31:42 dkf Exp $
'\"
.so man.macros
.TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -739,6 +739,28 @@ IEEE floating point representations. This is very common, but not
universal. To transfer floating-point numbers portably between all
architectures, use their textual representation (as produced by
\fBformat\fR) instead.
+.SH EXAMPLES
+This is a procedure write a Tcl string to a binary-encoded channel as
+UTF-8 data preceded by a length word:
+.CS
+proc writeString {channel string} {
+ set data [encoding convertto utf-8 $string]
+ puts -nonewline [binary format Ia* \e
+ [string length $data] $data]
+}
+.CE
+
+This procedure reads a string from a channel that was written by the
+previously presented \fBwriteString\fR procedure:
+.CS
+proc readString {channel} {
+ if {![binary scan [read $channel 4] I length]} {
+ error "missing length"
+ }
+ set data [read $channel $length]
+ return [encoding convertfrom utf-8 $data]
+}
+.CE
.SH "SEE ALSO"
format(n), scan(n), tclvars(n)
diff --git a/doc/clock.n b/doc/clock.n
index a0f6e9b..b23e976 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -10,7 +10,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: clock.n,v 1.16 2004/05/18 21:45:55 kennykb Exp $
+'\" RCS: @(#) $Id: clock.n,v 1.17 2004/05/24 23:31:42 dkf Exp $
'\"
.so man.macros
.TH clock n 8.4 Tcl "Tcl Built-In Commands"
@@ -29,16 +29,14 @@ or manipulate strings or values that represent some notion of
time. The \fIoption\fR argument determines what action is carried
out by the command. The legal \fIoptions\fR (which may be
abbreviated) are:
-.VS 8.3
.TP
\fBclock clicks\fR ?\fI\-option\fR?
If no \fIoption\fR argument is supplied, returns a high-resolution
time value as a system-dependent integer value. The unit of the value
is system-dependent but should be the highest resolution clock available
on the system such as a CPU cycle counter.
-.VE 8.3
-.VS 8.5
.TP
+.VS 8.5
If the \fIoption\fR argument is \fB\-milliseconds\fR, then the value is
guaranteed to be an approximate count of milliseconds returned as
a wide integer; the rule should
@@ -80,7 +78,6 @@ Full weekday name (Monday, Tuesday, etc.).
Abbreviated month name (Jan, Feb, etc.).
.IP \fB%B\fR
Full month name.
-.VS 8.4
.IP \fB%c\fR
Locale specific date and time. The format for date and time
in the default "C" locale on Unix is "%a %b %d %H:%M:%S %Y".
@@ -88,10 +85,8 @@ On Windows, this value is the locale specific long date and time, as
specified in the Regional Options control panel settings.
.IP \fB%C\fR
First two digits of the four-digit year (19 or 20).
-.VE 8.4
.IP \fB%d\fR
Day of month (01 - 31).
-.VS 8.4
'\" Since the inclusion of compat/strftime.c, %D, %e, %h should work on all
'\" platforms.
.IP \fB%D\fR
@@ -106,32 +101,24 @@ The ISO8601 year number corresponding to the ISO8601 week (%V), expressed
as a four-digit number.
.IP \fB%h\fR
Abbreviated month name.
-.VE 8.4
.IP \fB%H\fR
Hour in 24-hour format (00 - 23).
-.VS 8.4
.IP \fB%I\fR
Hour in 12-hour format (01 - 12).
-.VE 8.4
.IP \fB%j\fR
Day of year (001 - 366).
-.VS 8.4
.IP \fB%k\fR
Hour in 24-hour format, without leading zeros (0 - 23).
.IP \fB%l\fR
Hour in 12-hour format, without leading zeros (1 - 12).
-.VE 8.4
.IP \fB%m\fR
Month number (01 - 12).
.IP \fB%M\fR
Minute (00 - 59).
-.VS 8.4
.IP \fB%n\fR
Insert a newline.
-.VE 8.4
.IP \fB%p\fR
AM/PM indicator.
-.VS 8.4
.IP \fB%r\fR
Time in a locale-specific "meridian" format. The "meridian"
format in the default "C" locale is "%I:%M:%S %p".
@@ -139,29 +126,23 @@ format in the default "C" locale is "%I:%M:%S %p".
Time as %H:%M.
.IP \fB%s\fR
Count of seconds since the epoch, expressed as a decimal integer.
-.VE 8.4
.IP \fB%S\fR
Seconds (00 - 59).
-.VS 8.4
.IP \fB%t\fR
Insert a tab.
.IP \fB%T\fR
Time as %H:%M:%S.
.IP \fB%u\fR
Weekday number (Monday = 1, Sunday = 7).
-.VE 8.4
.IP \fB%U\fR
Week of year (00 - 52), Sunday is the first day of the week.
-.VS 8.4
.IP \fB%V\fR
Week of year according to ISO-8601 rules. Week 1 of a given
year is the week containing 4 January.
.IP \fB%w\fR
Weekday number (Sunday = 0, Saturday = 6).
-.VE 8.4
.IP \fB%W\fR
Week of year (00 - 52), Monday is the first day of the week.
-.VS 8.4
.IP \fB%x\fR
Locale specific date format. The format for a date in the default "C"
locale for Unix is "%m/%d/%y".
@@ -172,7 +153,6 @@ Locale specific 24-hour time format. The format for a
24-hour time in the default "C" locale for Unix is "%H:%M:%S".
On Windows, this value is the locale specific time format, as
specified in the Regional Options control panel settings.
-.VE 8.4
.IP \fB%y\fR
Year without century (00 - 99).
.IP \fB%Y\fR
@@ -180,7 +160,6 @@ Year with century (e.g. 1990)
.IP \fB%Z\fR
Time zone name.
.RE
-.VS 8.4
.sp
'\" All the field descriptors should be portable now that
'\" compat/strftime.c is in place, with the possible exception
@@ -206,7 +185,6 @@ Time zone name.
'\"Time as %H:%M:%S.
'\".RE
'\".sp
-.VE 8.4
.RS
If the \fB\-format\fR argument is not specified, the format string
\fB"%a %b %d %H:%M:%S %Z %Y"\fR is used. If the \fB\-gmt\fR argument
@@ -248,11 +226,9 @@ acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR
?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR?, \fIday, dd monthname
yy\fR, \fI?CC?yymmdd\fR, \fI?CC?yy-mm-dd\fR, \fIdd-monthname-?CC?yy\fR.
The default year is the current year. If the year is less
-.VS
than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
as 1969-1999. Not all platforms can represent the years 38-70, so
an error may result if these years are used.
-.VE
.TP
\fIISO 8601 point-in-time\fR
An ISO 8601 point-in-time specification, such as \fICCyymmddThhmmss\fR, where
@@ -299,6 +275,15 @@ Return the current date and time as a system-dependent integer value. The
unit of the value is seconds, allowing it to be used for relative time
calculations. The value is usually defined as total elapsed time from
an ``epoch''. You shouldn't assume the value of the epoch.
+.SH EXAMPLE
+Print out the current date and time, first using the default format
+and then using an ISO 8601 format:
+.CS
+set now [clock seconds]
+set isoFmt "%Y-%m-%dT%H:%M:%SZ"
+puts "DEFAULT: [clock format $now]"
+puts "ISO8601: [clock format $now -format $isoFmt -gmt 1]"
+.CE
.SH "SEE ALSO"
date(1), time(n)
diff --git a/doc/proc.n b/doc/proc.n
index 6735ef0..81d0170 100644
--- a/doc/proc.n
+++ b/doc/proc.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: proc.n,v 1.3 2000/09/07 14:27:50 poenitz Exp $
+'\" RCS: @(#) $Id: proc.n,v 1.4 2004/05/24 23:31:42 dkf Exp $
'\"
.so man.macros
.TH proc n "" Tcl "Tcl Built-In Commands"
@@ -69,6 +69,26 @@ invoked, the procedure's return value is the value specified in a
executed in the procedure's body.
If an error occurs while executing the procedure
body, then the procedure-as-a-whole will return that same error.
+.SH EXAMPLES
+This is a procedure that accepts arbitrarily many arguments and prints
+them out, one by one.
+.CS
+proc printArguments args {
+ foreach arg $args {
+ puts $arg
+ }
+}
+.CE
+
+This procedure is a bit like the \fBincr\fR command, except it
+multiplies the contents of the named variable by the value, which
+defaults to \fB2\fR:
+.CS
+proc mult {varName {multiplier 2}} {
+ upvar 1 $varName var
+ set var [expr {$var * $multiplier}]
+}
+.CE
.SH "SEE ALSO"
info(n), unknown(n)
diff --git a/doc/regsub.n b/doc/regsub.n
index d0c6e01..16ff77d 100644
--- a/doc/regsub.n
+++ b/doc/regsub.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: regsub.n,v 1.9 2003/02/20 15:33:02 dkf Exp $
+'\" RCS: @(#) $Id: regsub.n,v 1.10 2004/05/24 23:31:42 dkf Exp $
'\"
.so man.macros
.TH regsub n 8.3 Tcl "Tcl Built-In Commands"
@@ -114,9 +114,35 @@ string after replacement is returned.
.VE 8.4
See the manual entry for \fBregexp\fR for details on the interpretation
of regular expressions.
+.SH EXAMPLES
+Replace (in the string in variable \fIstring\fR) every instance of
+\fBfoo\fR which is a word by itself with \fBbar\fR:
+.CS
+regsub -all {\e<foo\e>} $string bar string
+.CE
+
+Insert double-quotes around the first instance of the word
+\fBinteresting\fR, however it is capitalised.
+.CS
+regsub -nocase {\e<interesting\e>} $string {"&"} string
+.CE
+
+Convert all non-ASCII and tcl-significant characters into \eu escape
+sequences by using \fBregsub\fR and \fBsubst\fR in combination:
+.CS
+# This RE is just a character class for everything "bad"
+set RE {[][{}\e$\es\eu0100-\euffff]}
+
+# We will substitute with a fragment of Tcl script in brackets
+set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}
+
+# Now we apply the substitution to get a subst-string that
+# will perform the computational parts of the conversion.
+set quoted [subst [regsub -all $RE $string $substitution]]
+.CE
.SH "SEE ALSO"
-regexp(n), re_syntax(n)
+regexp(n), re_syntax(n), subst(n)
.SH KEYWORDS
match, pattern, regular expression, substitute