strops.tm

来自「一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件」· TM 代码 · 共 737 行 · 第 1/2 页

\function{Sprintf}
\synopsis{Format objects into a string}
\usage{String_Type Sprintf (String_Type format, ..., Integer_Type n)}
\description
  \var{Sprintf} formats a string from \var{n} objects according to
  \var{format}.  Unlike \var{sprintf}, the \var{Sprintf} function
  requires the number of items to format.
  
  The format string is a C library \var{sprintf} style format
  descriptor.  Briefly, the format string may consist of ordinary
  characters (not including the \exmp{%} character), which are copied
  into the output string as-is, and a conversion specification
  introduced by the \exmp{%} character.  The \var{%} character must be
  followed by at least one other character to specify the conversion:
#v+
     s    value is a string
     f    value is a floating point number
     e    print float in exponential form, e.g., 2.345e08
     g    print float as e or g, depending upon its value
     c    value is an ascii character
     %    print the percent character
     d    print a signed decimal integer
     u    print an unsigned decimal integer
     o    print an integer as octal
     X    print an integer as hexadecimal
     S    convert value to a string and format as string
#v-
  Note that \var{%S} is a \slang extension which will cause the value
  to be formatted as string.  In fact, \exmp{sprintf("%S",x)} is
  equivalent to \exmp{sprintf("%s",string(x))}.
#v+
     s = Sprintf("%f is greater than %f but %s is better than %s\n",
                 PI, E, "Cake" "Pie", 4);
#v-
  The final argument to \var{Sprintf} is the number of items to format; in
  this case, there are 4 items.
\seealso{sprintf, string, sscanf}
\done

\function{create_delimited_string}
\synopsis{Concatenate strings using a delimiter}
\usage{String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)}
#v+
    String_Type delim, s_1, ..., s_n
    Integer_Type n
#v-
\description
  \var{create_delimited_string} performs a concatenation operation on
  the \var{n} strings \var{s_1}, ...,\var{s_n}, using the string
  \var{delim} as a delimiter.  The resulting string is equivalent to
  one obtained via
#v+
      s_1 + delim + s_2 + delim + ... + s_n
#v-
\example
  One use for this function is to construct path names, e.g.,
#v+
    create_delimited_string ("/", "user", "local", "bin", 3);
#v-
  will produce \exmp{"usr/local/bin"}.
\notes
  The expression \exmp{strcat(a,b)} is equivalent to
  \exmp{create_delimited_string("", a, b, 2)}.
\seealso{strjoin, is_list_element, extract_element, strchop, strcat}
\done

\function{extract_element}
\synopsis{Extract the nth element of a string with delimiters}
\usage{String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);}
\description
  The \var{extract_element} function may be used to extract the
  \var{nth} element of the \var{delim} delimited list of strings
  \var{list}.  The function will return the \var{nth} element of the
  list, unless \var{nth} specifies more elements than the list
  contains, in which case \var{NULL} will be returned.
  Elements in the list are numbered from \var{0}.
\example
  The expression
#v+
     extract_element ("element 0, element 1, element 2", 1, ',')
#v-
  returns the string \exmp{" element 1"}, whereas
#v+
     extract_element ("element 0, element 1, element 2", 1, ' ')
#v-
  returns \exmp{"0,"}.

  The following function may be used to compute the number of elements
  in the list:
#v+
     define num_elements (list, delim)
     {
        variable nth = 0;
        while (NULL != extract_element (list, nth, delim))
          nth++;
        return nth;
     }
#v-

  Alternatively, the \var{strchop} function may be more useful.  In
  fact, \var{extract_element} may be expressed in terms of the
  function \var{strchop} as
#v+
    define extract_element (list, nth, delim)
    {
       list = strchop(list, delim, 0);
       if (nth >= length (list))
         return NULL;
       else
         return list[nth];
    }
#v-
   and the \var{num_elements} function used above may be recoded more
   simply as:
#v+
    define num_elements (list, delim)
    {
       return length (strchop (length, delim, 0));
    }
#v-
\seealso{is_list_element, is_substr, strtok, strchop, create_delimited_string}
\done

\function{is_list_element}
\synopsis{Test whether a delimited string contains a specific element}
\usage{Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)}
\description
  The \var{is_list_element} function may be used to determine whether
  or not a delimited list of strings, \var{list}, contains the element
  \var{elem}.  If \var{elem} is not an element of \var{list}, the function
  will return zero, otherwise, it returns 1 plus the matching element
  number.
\example
  The expression
#v+
     is_list_element ("element 0, element 1, element 2", "0,", ' ');
#v-
  returns \exmp{2} since \exmp{"0,"} is element number one of the list
  (numbered from zero).
\seealso{extract_element, is_substr, create_delimited_string}
\done

\function{is_substr}
\synopsis{Test for a specified substring within a string.}
\usage{Integer_Type is_substr (String_Type a, String_Type b)}
\description
  This function may be used to determine if \var{a} contains the
  string \var{b}.  If it does not, the function returns 0; otherwise it
  returns the position of the first occurance of \var{b} in \var{a}.
\notes
  It is important to remember that the first character of a string
  corresponds to a position value of \exmp{1}.
\seealso{substr, string_match, strreplace}
\done

\function{make_printable_string}
\synopsis{Format a string suitable for parsing}
\usage{String_Type make_printable_string(String_Type str)}
\description
  This function formats a string in such a way that it may be used as
  an argument to the \var{eval} function.  The resulting string is
  identical to \var{str} except that it is enclosed in double quotes and the
  backslash, newline, and double quote characters are expanded.
\seealso{eval, str_quote_string}
\done

\function{sprintf}
\synopsis{Format objects into a string}
\usage{String sprintf (String format, ...);}
\description
  This function performs a similar task as the C function with the same
  name.  It differs from the \slang function \var{Sprintf} in that it
  does not require the number of items to format.
  See the documentation for \var{Sprintf} for more information.
\seealso{Sprintf, string, sscanf, vmessage}
\done

\function{sscanf}
\synopsis{Parse a formatted string}
\usage{Int_Type sscanf (s, fmt, r1, ... rN)}
#v+
    String_Type s, fmt;
    Ref_Type r1, ..., rN
#v-
\description
 The \var{sscanf} function parses the string \var{s} according to the
 format \var{fmt} and sets the variables whose references are given by
 \var{r1}, ..., \var{rN}.  The function returns the number of
 references assigned, or \var{-1} upon error.
 
 The format string \var{fmt} consists of ordinary characters and
 conversion specifiers.  A conversion specifier begins with the
 special character \var{%} and is described more fully below.  A white
 space character in the format string matches any amount of whitespace
 in the input string.  Parsing of the format string stops whenever a
 match fails.

 The \var{%} is used to denote a conversion specifier whose general
 form is given by \exmp{%[*][width][type]format} where the brackets
 indicate optional items.  If \var{*} is present, then the conversion
 will be performed by no assignment to a reference will be made.  The
 \var{width} specifier specifies the maximum field width to use for
 the conversion.  The \var{type} modifier is used to indicate size of
 the object, e.g., a short integer, as follows. 
 
 If \em{type} is given as the character \var{h}, then if the format
 conversion is for an integer (\var{dioux}), the object assigned will
 be a short integer.  If \em{type} is \var{l}, then the conversion
 will be to a long integer for integer conversions, or to a double
 precession floating point number for floating point conversions.

 The format specifier is a character that specifies the conversion:
#v+
       %     Matches a literal percent character.  No assigment is
             performed.
       d     Matches a signed decimal integer.
       D     Matches a long decimal integer (equiv to `ld')
       u     Matches an unsigned decimal integer
       U     Matches an unsigned long decimal integer (equiv to `lu')
       i     Matches either a hexidecimal integer, decimal integer, or 
             octal integer.
       I     Equivalent to `li'.
       x     Matches a hexidecimal integer.
       X     Matches a long hexidecimal integer (same as `lx').
       e,f,g Matches a decimal floating point number (Float_Type).
       E,F,G Matches a double precision floating point number, same as `lf'.
       s     Matches a string of non-whitespace characters (String_Type).
       c     Matches one character.  If width is given, width
             characters are matched.
       n     Assigns the number of characters scanned so far.
       [...] Matches zero or more characters from the set of characters
             enclosed by the square brackets.  If '^' is given as the
             first character, then the complement set is matched. 
#v-
\example
 Suppose that \var{s} is \exmp{"Coffee: (3,4,12.4)"}.  Then
#v+
    n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);
#v-
 will set \var{n} to \4, \var{item} to \exmp{"Coffee"}, \var{x} to \3,
 \var{y} to \4, and \var{z} to the double precision number
 \exmp{12.4}.  However,
#v+
    n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);
#v-
 will set \var{n} to \1, \var{item} to \exmp{"Coffee:"} and the
 remaining variables will not be assigned.
\seealso{sprintf, unpack, string, atof, int, integer, string_match}
\done

\function{str_delete_chars}
\synopsis{Delete characters from a string}
\usage{String_Type str_delete_chars (String_Type str, String_Type del_set}
\description
  This function may be used to delete the set of characters specified
  by \var{del_set} from the string \var{str}.  The result is returned.
\example
#v+
    str = str_delete_chars (str, "^A-Za-z");
#v-
  will remove all characters except \exmp{A-Z} and \exmp{a-z} from
  \var{str}.
\done

\function{str_quote_string}
\synopsis{Escape characters in a string.}
\usage{String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)}
\description
  The \var{str_quote_string} returns a string identical to \var{str}
  except that all characters in the set specified by the string
  \var{qlis} are escaped with the \var{quote} character, including the
  quote character itself.   This function is useful for making a
  string that can be used in a regular expression.
\example
  Execution of the statements
#v+
   node = "Is it [the coat] really worth $100?";
   tag = str_quote_string (node, "\\^$[]*.+?", '\\');
#v-
  will result in \var{tag} having the value:
#v+
    Is it \[the coat\] really worth \$100\?
#v-
\seealso{str_uncomment_string, make_printable_string}
\done

\function{str_replace}
\synopsis{Replace a substring of a string}
\usage{Integer_Type str_replace (String_Type a, String_Type b, String_Type c)}
\description
  The \var{str_replace} function replaces the first occurance of \var{b} in
  \var{a} with \var{c} and returns an integer that indicates whether a
  replacement was made or not. If \var{b} does not occur in \var{a}, zero is
  returned.  However, if \var{b} occurs in \var{a}, a non-zero integer is
  returned as well as the new string resulting from the replacement.
\notes
  This function has been superceded by \var{strreplace}.
\seealso{strreplace}
\done

\function{str_uncomment_string}
\synopsis{Remove comments from a string}
\usage{String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)}
\description
  This function may be used to remove comments from a string \var{s}.
  The parameters, \var{beg} and \var{end}, are strings of equal length
  whose corresponding characters specify the begin and end comment
  characters, respectively.  It returns the uncommented string.
\example
  The expression
#v+
     str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")
#v-
  returns the string \exmp{"Hello   World"}.
\notes
  This routine does not handle multicharacter comment delimiters and it
  assumes that comments are not nested.
\seealso{str_quote_string}
\done

\function{strcat}
\synopsis{Concatenate strings}
\usage{String_Type strcat (String_Type a_1, ...,  String_Type a_N)}
\description
   The \var{strcat} function concatenates its N \var{String_Type}
   arguments \var{a_1}, ... \var{a_N} together and returns the result.
\example
#v+
    strcat ("Hello", " ", "World");
#v-
   produces the string \exmp{"Hello World"}.
\notes
   This function is equivalent to the binary operation \exmp{a_1+...+a_N}.
   However, \var{strcat} is much faster making it the preferred method
   to concatenate string.
\seealso{sprintf, create_delimited_string}
\done

\function{strchop}
\synopsis{Chop or split a string into substrings.}
\usage{String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote)}
\description
   The \var{strchop} function may be used to split-up a string
   \var{str} that consists of substrings delimited by the character
   specified by \var{delim}.  If the integer \var{quote} is non-zero,
   it will be taken as a quote character for the delimiter.  The
   function returns the substrings as an array.
\example
   The following function illustrates how to sort a comma separated
   list of strings:
#v+
     define sort_string_list (a)
     { 
        variable i, b, c;
        b = strchop (a, ',', 0);
        
        i = array_sort (b, &strcmp);
        b = b[i];   % rearrange
        
        % Convert array back into comma separated form
        return strjoin (b, ",");
     }
#v-
\notes
   The semantics of this \var{strchop} and \var{strchopr} have been
   changed since version 1.2.x of the interpreter.  Old versions of
   these functions returned the values on the stack, which meant that
   one could not chop up arbitrarily long strings that consist of
   many substrings.