diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/binary.n | 24 | ||||
| -rw-r--r-- | doc/clock.n | 37 | ||||
| -rw-r--r-- | doc/proc.n | 22 | ||||
| -rw-r--r-- | doc/regsub.n | 30 |
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) @@ -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 |