strops.tm

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

   
   The function \var{strchopr} should be used if it is desired to have
   the string chopped-up in the reverse order.
\seealso{strchopr, extract_element, strjoin, strtok}
\done

\function{strchopr}
\synopsis{Chop or split a string into substrings.}
\usage{String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)}
\description
  This routine performs exactly the same function as \var{strchop} except
  that it returns the substrings in the reverse order.  See the
  documentation for \var{strchop} for more information.
\seealso{strchop, extract_element, strtok, strjoin}
\done

\function{strcmp}
\synopsis{Compare two strings}
\usage{Interpret strcmp (String_Type a, String_Type b)}
\description
   The \var{strcmp} function may be used to perform a case-sensitive
   string comparison, in the lexicongraphic sense, on strings \var{a} and
   \var{b}.  It returns 0 if the strings are identical, a negative integer
   if \var{a} is less than \var{b}, or a positive integer if \var{a} is greater
   than \var{b}.
\example
   The \var{strup} function may be used to perform a case-insensitive
   string comparison:
#v+
    define case_insensitive_strcmp (a, b)
    {
      return strcmp (strup(a), strup(b));
    }
#v-
\notes
   One may also use one of the binary comparison operators, e.g.,
   \exmp{a > b}.
\seealso{strup, strncmp}
\done

\function{strcompress}
\synopsis{Remove excess whitespace characters from a string}
\usage{String_Type strcompress (String_Type s, String_Type white)}
\description
  The \var{strcompress} function compresses the string \var{s} by
  replacing a sequence of one or more characters from the set
  \var{white} by the first character of \var{white}. In addition, it
  also removes all leading and trailing characters from \var{s} that
  are part of \var{white}.
\example
  The expression
#v+
    strcompress (",;apple,,cherry;,banana", ",;");
#v-
  returns the string \exmp{"apple,cherry,banana"}.
\seealso{strtrim, strtrans}
\done

\function{string_match}
\synopsis{Match a string against a regular expression}
\usage{Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)}
\description
  The \var{string_match} function returns zero if \var{str} does not
  match regular expression specified by \var{pat}.  This function
  performs the match starting at position \var{pos} (numbered from 1) in
  \var{str}.  This function returns the position of the start of the
  match.  To find the exact substring actually matched, use
  \var{string_match_nth}.
\seealso{string_match_nth, strcmp, strncmp}
\done

\function{string_match_nth}
\synopsis{Get the result of the last call to string_match}
\usage{(Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)}
\description
  The \var{string_match_nth} function returns two integers describing
  the result of the last call to \var{string_match}.  It returns both
  the offset into the string and the length of characters matches by
  the \var{nth} submatch.

  By convention, \var{nth} equal to zero means the entire match.
  Otherwise, \var{nth} must be an integer with a value 1 through 9,
  and refers to the set of characters matched by the \var{nth} regular
  expression enclosed by the pairs \exmp{\\(, \\)}.
\example
  Consider:
#v+
     variable matched, pos, len;
     matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1);
     if (matched) (pos, len) = string_match_nth(2);
#v-
  This will set \var{matched} to 1 since a match will be found at the
  first position, \var{pos} to 6 since \var{w} is offset 6 characters
  from the beginning of the string, and \var{len} to 5 since
  \exmp{"world"} is 5 characters long.
\notes
  The position offset is \em{not} affected by the value of the offset
  parameter to the \var{string_match} function. For example, if the
  value of the last parameter to the \var{string_match} function had
  been 3, \var{pos} would still have been set to 6.

  Note also that \var{string_match_nth} returns the \em{offset} from
  the beginning of the string and not the position of the match.
\seealso{string_match}
\done

\function{strjoin}
\synopsis{Concatenate elements of a string array}
\usage{String_Type strjoin (Array_Type a, String_Type delim)}
\description
   The \var{strjoin} function operates on an array of strings by joining
   successive elements together separated with a delimiter \var{delim}.
   If \var{delim} is the empty string \exmp{""}, then the result will
   simply be the concatenation of the elements.
\example
   Suppose that
#v+
      days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];
#v-
   Then \exmp{strjoin (days,"+")} will produce
   \exmp{"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"}.  Similarly,
   \exmp{strjoin (["","",""], "X")} will produce \exmp{"XX"}.
\seealso{create_delimited_string, strchop, strcat}
\done

\function{strlen}
\synopsis{Compute the length of a string}
\usage{Integer_Type strlen (String_Type a)}
\description
   The \var{strlen} function may be used to compute the length of a string.
\example
   After execution of
#v+
   variable len = strlen ("hello");
#v-
   \var{len} will have a value of \exmp{5}.
\seealso{bstrlen, length, substr}
\done

\function{strlow}
\synopsis{Convert a string to lowercase}
\usage{String_Type strlow (String_Type s)}
\description
  The \var{strlow} function takes a string \var{s} and returns another
  string identical to \var{s} except that all upper case characters
  that comprise \var{s} will be converted to lower case.
\example
  The function
#v+
    define Strcmp (a, b)
    {
      return strcmp (strlow (a), strlow (b));
    }
#v-
  performs a case-insensitive comparison operation of two strings by
  converting them to lower case first.
\seealso{strup, tolower, strcmp, strtrim, define_case}
\done

\function{strncmp}
\synopsis{Compare the first few characters of two strings}
\usage{Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)}
\description
  This function behaves like \var{strcmp} except that it compares only the
  first \var{n} characters in the strings \var{a} and \var{b}.  See
  the documentation for \var{strcmp} for information about the return
  value.
\example
  The expression
#v+
     strcmp ("apple", "appliance", 3);
#v-
  will return zero since the first three characters match.
\seealso{strcmp, strlen}
\done

\function{strreplace}
\synopsis{Replace one or more substrings}
\usage{(new, n) = strreplace (a, b, c, max_n)}
#v+
   String_Type a, b, c, rep;
   Int_Type n, max_n;
#v-
\description
  The \var{strreplace} function may be used to replace one or more
  occurances of \var{b} in \var{a} with \var{c}.  If the integer
  \var{max_n} is positive, then the first \var{max_n} occurances of
  \var{b} in \var{a} will be replaced.  Otherwise, if \var{max_n} is
  negative, then the last \exmp{abs(max_n)} occurances will be replaced.
  
  The function returns the resulting string and an integer indicating
  how many replacements were made.
\example
  The following function illustrates how \var{strreplace} may be used
  to remove all occurances of a specified substring
#v+
  define delete_substrings (a, b)
  {
     (a, ) = strreplace (a, b, "", strlen (a));
     return a;
  }
#v-
\seealso{is_substr, strsub, strtrim, strtrans, str_delete_chars}
\done

\function{strsub}
\synopsis{Replace a character with another in a string.}
\usage{String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)}
\description
  The \var{strsub} character may be used to substitute the character
  \var{ch} for the character at position \var{pos} of the string
  \var{s}.  The resulting string is returned.
\example
#v+
    define replace_spaces_with_comma (s)
    {
      variable n;
      while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
      return s;
    }
#v-
  For uses such as this, the \var{strtrans} function is a better choice.
\notes
  The first character in the string \var{s} is specified by \var{pos}
  equal to 1.
\seealso{is_substr, strreplace, strlen}
\done

\function{strtok}
\synopsis{Extract tokens from a string}
\usage{String_Type[] strtok (String_Type str [,String_Type white])}
\description
  \var{strtok} breaks the string \var{str} into a series of tokens and
  returns them as an array of strings.  If the second parameter
  \var{white} is present, then it specifies the set of characters that
  are to be regarded as whitespace when extracting the tokens, and may
  consist of the whitespace characters or a range of such characters.
  If the first character of \var{white} is \exmp{'^'}, then the
  whitespace characters consist of all characters except those in
  \var{white}. For example, if \var{white} is \exmp{" \\t\\n,;."},
  then those characters specifiy the whitespace characters.  However,
  if \var{white} is given by \exmp{"^a-zA-Z0-9_"}, then any character
  is a whitespace character except those in the ranges \exmp{a-z},
  \exmp{A-Z}, \exmp{0-9}, and the underscore character.
  
  If the second parameter is not present, then it defaults to 
  \exmp{" \\t\\r\\n\\f"}.
\example
  The following example may be used to count the words in a text file:
#v+
    define count_words (file)
    {
       variable fp, line, count;
       
       fp = fopen (file, "r");
       if (fp == NULL) return -1;
       
       count = 0;
       while (-1 != fgets (&line, fp))
         {
           line = strtok (line, "^a-zA-Z");
           count += length (line);
         }
       () = fclose (fp);
       return count;
    }
#v-
\seealso{strchop, strcompress, extract_element, strjoin}
\done

\function{strtrans}
\synopsis{Replace characters in a string}
\usage{String_Type strtrans (str, old_set, new_set)}
#v+
   String_Type str, old_set, new_set;
#v-
\description
  The \var{strtrans} function may be used to replace all the characters
  from the set \var{old_set} with the corresponding characters from
  \var{new_set} in the string \var{str}.  If \var{new_set} is empty,
  then the characters in \var{old_set} will be removed from \var{str}.
  This function returns the result.
\example
#v+
    str = strtrans (str, "A-Z", "a-z");   % lower-case str
    str = strtrans (str, "^0-9", " ");    % Replace anything but 0-9 by space
#v-
\seealso{strreplace, strtrim, strup, strlow}
\done

\function{strtrim}
\synopsis{Remove whitespace from the ends of a string}
\usage{String_Type strtrim (String_Type s [,String_Type w])}
\description
  The \var{strtrim} function removes all leading and trailing whitespace
  characters from the string \var{s} and returns the result.  The
  optional second parameter specifies the set of whitespace
  characters.  If the argument is not present, then the set defaults
  to \exmp{" \\t\\r\\n"}.
\seealso{strtrim_beg, strtrim_end, strcompress}
\done

\function{strtrim_beg}
\synopsis{Remove leading whitespace from a string}
\usage{String_Type strtrim_beg (String_Type s [,String_Type w])}
\description
  The \var{strtrim_beg} function removes all leading whitespace
  characters from the string \var{s} and returns the result.  The
  optional second parameter specifies the set of whitespace
  characters.  If the argument is not present, then the set defaults
  to \exmp{" \\t\\r\\n"}.
\seealso{strtrim, strtrim_end, strcompress}
\done

\function{strtrim_end}
\synopsis{Remove trailing whitespace from a string}
\usage{String_Type strtrim_end (String_Type s [,String_Type w])}
\description
  The \var{strtrim_end} function removes all trailing whitespace
  characters from the string \var{s} and returns the result.  The
  optional second parameter specifies the set of whitespace
  characters.  If the argument is not present, then the set defaults
  to \exmp{" \\t\\r\\n"}.
\seealso{strtrim, strtrim_beg, strcompress}
\done

\function{strup}
\synopsis{Convert a string to uppercase}
\usage{String_Type strup (String_Type s)}
\description
  The \var{strup} function takes a string \var{s} and returns another
  string identical to \var{s} except that all lower case characters
  that comprise \var{s} will be converted to upper case.
\example
  The function
#v+
    define Strcmp (a, b)
    {
      return strcmp (strup (a), strup (b));
    }
#v-
  performs a case-insensitive comparison operation of two strings by
  converting them to upper case first.
\seealso{strlow, toupper, strcmp, strtrim, define_case, strtrans}
\done

\function{substr}
\synopsis{Extract a substring from a string}
\usage{String_Type substr (String_Type s, Integer_Type n, Integer_Type len)}
\description
  The \var{substr} function returns a substring with length \var{len}
  of the string \var{s} beginning at position \var{n}.  If \var{len} is
  \exmp{-1}, the entire length of the string \var{s} will be used for
  \var{len}.  The first character of \var{s} is given by \var{n} equal
  to 1.
\example
#v+
     substr ("To be or not to be", 7, 5);
#v-
  returns \exmp{"or no"}
\notes
  In many cases it is more convenient to use array indexing rather
  than the \var{substr} function.  In fact, \exmp{substr(s,i+1,strlen(s))} is
  equivalent to \exmp{s[[i:]]}.
\seealso{is_substr, strlen}
\done