util/src/TclTk/tcl8.6.12/doc/Concat.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl_Concat \- concatenate a collection of strings
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 const char *
  18 \fBTcl_Concat\fR(\fIargc, argv\fR)
  19 .SH ARGUMENTS
  20 .AS "const char *const" argv[]
  21 .AP int argc in
  22 Number of strings.
  23 .AP "const char *const" argv[] in
  24 Array of strings to concatenate.  Must have \fIargc\fR entries.
  25 .BE
  26
  27 .SH DESCRIPTION
  28 .PP
  29 \fBTcl_Concat\fR is a utility procedure used by several of the
  30 Tcl commands.  Given a collection of strings, it concatenates
  31 them together into a single string, with the original strings
  32 separated by spaces.  This procedure behaves differently than
  33 \fBTcl_Merge\fR, in that the arguments are simply concatenated:
  34 no effort is made to ensure proper list structure.
  35 However, in most common usage the arguments will all be proper
  36 lists themselves;  if this is true, then the result will also have
  37 proper list structure.
  38 .PP
  39 \fBTcl_Concat\fR eliminates leading and trailing white space as it
  40 copies strings from \fBargv\fR to the result.  If an element of
  41 \fBargv\fR consists of nothing but white space, then that string
  42 is ignored entirely.  This white-space removal was added to make
  43 the output of the \fBconcat\fR command cleaner-looking.
  44 .PP
  45 The result string is dynamically allocated
  46 using \fBTcl_Alloc\fR;  the caller must eventually release the space
  47 by calling \fBTcl_Free\fR.
  48 .SH "SEE ALSO"
  49 Tcl_ConcatObj
  50 .SH KEYWORDS
  51 concatenate, strings