2002-07-20 Han-Wen <hanwen@cs.uu.nl>
[bpt/guile.git] / libguile / strop.c
index a7f2911..f42046b 100644 (file)
@@ -1,6 +1,6 @@
 /* classes: src_files */
 
-/*     Copyright (C) 1994, 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* Copyright (C) 1994,1996,1997,1999,2000,2001 Free Software Foundation, Inc.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -15,10 +15,32 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this software; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307 USA */
+02111-1307 USA
+
+As a special exception, the Free Software Foundation gives permission
+for additional uses of the text contained in its release of GUILE.
+
+The exception is that, if you link the GUILE library with other files
+to produce an executable, this does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+Your use of that executable is in no way restricted on account of
+linking the GUILE library code into it.
+
+This exception does not however invalidate any other reasons why
+the executable file might be covered by the GNU General Public License.
+
+This exception applies only to the code released by the
+Free Software Foundation under the name GUILE.  If you copy
+code from other Free Software Foundation releases into a copy of
+GUILE, as the General Public License permits, the exception does
+not apply to the code that you add in this way.  To avoid misleading
+anyone as to the status of such modified files, you must delete
+this exception notice from them.
+
+If you write modifications of your own for GUILE, it is your choice
+whether to permit this exception to apply to your modifications.
+If you do not wish that, delete this exception notice.  */
 
-/* Software engineering face-lift by Greg J. Badros, 11-Dec-1999,
-   gjb@cs.washington.edu, http://www.cs.washington.edu/homes/gjb */
 
 
 \f
@@ -40,22 +62,22 @@ Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 \f
 
 /*
-xSCM_DEFINE (scm_i_index, "i-index", 2, 2, 0, 
+xSCM_DEFINE (scm_i_index, "i-index", 2, 2, 0,
            (SCM str, SCM chr, SCM frm, SCM to),
-          "@deftypefn {Internal C Function} {static int} scm_i_index (SCM *@var{str}, \n"
+          "@deftypefn {Internal C Function} {static int} scm_i_index (SCM *@var{str},\n"
           "SCM @var{chr}, int @var{direction}, SCM @var{sub_start}, SCM @var{sub_end}, char *@var{why})
           "This is a workhorse function that performs either an @code{index} or\n"
           "@code{rindex} function, depending on the value of @var{direction}."
 */
 /* implements index if direction > 0 otherwise rindex.  */
-static int
-scm_i_index (SCM *str, SCM chr, int direction, SCM sub_start, 
+static long
+scm_i_index (SCM *str, SCM chr, int direction, SCM sub_start,
             SCM sub_end, const char *why)
 {
   unsigned char * p;
-  int x;
-  int lower;
-  int upper;
+  long x;
+  long lower;
+  long upper;
   int ch;
 
   SCM_ASSERT (SCM_STRINGP (*str), *str, SCM_ARG1, why);
@@ -98,30 +120,26 @@ scm_i_index (SCM *str, SCM chr, int direction, SCM sub_start,
   return -1;
 }
 
-SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0, 
+SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
            (SCM str, SCM chr, SCM frm, SCM to),
            "Return the index of the first occurrence of @var{chr} in\n"
            "@var{str}.  The optional integer arguments @var{frm} and\n"
            "@var{to} limit the search to a portion of the string.  This\n"
            "procedure essentially implements the @code{index} or\n"
-           "@code{strchr} functions from the C library.\n (qdocs:) Returns\n"
-           "the index of @var{char} in @var{str}, or @code{#f} if the\n"
-           "@var{char} isn't in @var{str}. If @var{frm} is given and not\n"
-           "@code{#f}, it is used as the starting index; if @var{to} is\n"
-           "given and not @code{#f}, it is used as the ending index\n"
-           "(exclusive).\n\n"
-           "@example\n"
+           "@code{strchr} functions from the C library.\n"
+           "\n"
+           "@lisp\n"
            "(string-index \"weiner\" #\\e)\n"
            "@result{} 1\n\n"
            "(string-index \"weiner\" #\\e 2)\n"
            "@result{} 4\n\n"
            "(string-index \"weiner\" #\\e 2 4)\n"
            "@result{} #f\n"
-           "@end example")
+           "@end lisp")
 #define FUNC_NAME s_scm_string_index
 {
-  int pos;
-  
+  long pos;
+
   if (SCM_UNBNDP (frm))
     frm = SCM_BOOL_F;
   if (SCM_UNBNDP (to))
@@ -133,26 +151,25 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
 }
 #undef FUNC_NAME
 
-SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0, 
+SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0,
            (SCM str, SCM chr, SCM frm, SCM to),
-           "Like @code{string-index}, but search from the right of the string rather\n"
-           "than from the left.  This procedure essentially implements the\n"
-           "@code{rindex} or @code{strrchr} functions from the C library.\n\n"
-           "(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance\n"
-           "of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to\n"
-           "the entire string.\n\n"
-           "@example\n"
+           "Like @code{string-index}, but search from the right of the\n"
+           "string rather than from the left.  This procedure essentially\n"
+           "implements the @code{rindex} or @code{strrchr} functions from\n"
+           "the C library.\n"
+           "\n"
+           "@lisp\n"
            "(string-rindex \"weiner\" #\\e)\n"
            "@result{} 4\n\n"
            "(string-rindex \"weiner\" #\\e 2 4)\n"
            "@result{} #f\n\n"
            "(string-rindex \"weiner\" #\\e 2 5)\n"
            "@result{} 4\n"
-           "@end example")
+           "@end lisp")
 #define FUNC_NAME s_scm_string_rindex
 {
-  int pos;
-  
+  long pos;
+
   if (SCM_UNBNDP (frm))
     frm = SCM_BOOL_F;
   if (SCM_UNBNDP (to))
@@ -164,168 +181,92 @@ SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0,
 }
 #undef FUNC_NAME
 
-
-SCM_REGISTER_PROC(s_substring_move_left_x, "substring-move-left!", 5, 0, 0, scm_substring_move_x);
-SCM_REGISTER_PROC(s_substring_move_right_x, "substring-move-right!", 5, 0, 0, scm_substring_move_x);
-
-/*
-@defun substring-move-left! str1 start1 end1 str2 start2
-@end defun
-@deftypefn {C Function} SCM scm_substring_move_left_x (SCM @var{str1}, SCM @var{start1}, SCM @var{end1}, SCM @var{str2}, SCM @var{start2})
-[@strong{Note:} this is only valid if you've applied the strop patch].
-
-Moves a substring of @var{str1}, from @var{start1} to @var{end1}
-(@var{end1} is exclusive), into @var{str2}, starting at
-@var{start2}. Allows overlapping strings.
-
-@example
-(define x (make-string 10 #\a))
-(define y "bcd")
-(substring-move-left! x 2 5 y 0)
-y
-@result{} "aaa"
-
-x
-@result{} "aaaaaaaaaa"
-
-(define y "bcdefg")
-(substring-move-left! x 2 5 y 0)
-y
-@result{} "aaaefg"
-
-(define y "abcdefg")
-(substring-move-left! y 2 5 y 3)
-y
-@result{} "abccccg"
-@end example
-*/
-
-/*
-@defun substring-move-right! str1 start1 end1 str2 start2
-@end defun
-@deftypefn {C Function} SCM scm_substring_move_right_x (SCM @var{str1}, SCM @var{start1}, SCM @var{end1}, SCM @var{str2}, SCM @var{start2})
-[@strong{Note:} this is only valid if you've applied the strop patch, if
-it hasn't made it into the guile tree].
-
-Does much the same thing as @code{substring-move-left!}, except it
-starts moving at the end of the sequence, rather than the beginning.
-@example
-(define y "abcdefg")
-(substring-move-right! y 2 5 y 0)
-y
-@result{} "ededefg"
-
-(define y "abcdefg")
-(substring-move-right! y 2 5 y 3)
-y
-@result{} "abccdeg"
-@end example
-*/ 
-
-SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0, 
+SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0,
            (SCM str1, SCM start1, SCM end1, SCM str2, SCM start2),
-           "@deffnx primitive substring-move-left! str1 start1 end1 str2 start2\n"
-           "@deffnx primitive substring-move-right! str1 start1 end1 str2 start2\n"
            "Copy the substring of @var{str1} bounded by @var{start1} and @var{end1}\n"
-           "into @var{str2} beginning at position @var{end2}.\n"
-           "@code{substring-move-right!} begins copying from the rightmost character\n"
-           "and moves left, and @code{substring-move-left!} copies from the leftmost\n"
-           "character moving right.\n\n"
-           "It is useful to have two functions that copy in different directions so\n"
-           "that substrings can be copied back and forth within a single string.  If\n"
-           "you wish to copy text from the left-hand side of a string to the\n"
-           "right-hand side of the same string, and the source and destination\n"
-           "overlap, you must be careful to copy the rightmost characters of the\n"
-           "text first, to avoid clobbering your data.  Hence, when @var{str1} and\n"
-           "@var{str2} are the same string, you should use\n"
-           "@code{substring-move-right!} when moving text from left to right, and\n"
-           "@code{substring-move-left!}  otherwise.  If @code{str1} and @samp{str2}\n"
-           "are different strings, it does not matter which function you use.")
+           "into @var{str2} beginning at position @var{start2}.\n"
+           "@var{str1} and @var{str2} can be the same string.")
 #define FUNC_NAME s_scm_substring_move_x
 {
   long s1, s2, e, len;
 
-  SCM_VALIDATE_STRING (1,str1);
-  SCM_VALIDATE_INUM_COPY (2,start1,s1);
-  SCM_VALIDATE_INUM_COPY (3,end1,e);
-  SCM_VALIDATE_STRING (4,str2);
-  SCM_VALIDATE_INUM_COPY (5,start2,s2);
+  SCM_VALIDATE_STRING (1, str1);
+  SCM_VALIDATE_INUM_COPY (2, start1, s1);
+  SCM_VALIDATE_INUM_COPY (3, end1, e);
+  SCM_VALIDATE_STRING (4, str2);
+  SCM_VALIDATE_INUM_COPY (5, start2, s2);
   len = e - s1;
-  SCM_ASSERT_RANGE (3,end1,len >= 0);
-  SCM_ASSERT_RANGE (2,start1,s1 <= SCM_STRING_LENGTH (str1) && s1 >= 0);
-  SCM_ASSERT_RANGE (5,start2,s2 <= SCM_STRING_LENGTH (str2) && s2 >= 0);
-  SCM_ASSERT_RANGE (3,end1,e <= SCM_STRING_LENGTH (str1) && e >= 0);
-  SCM_ASSERT_RANGE (5,start2,len+s2 <= SCM_STRING_LENGTH (str2));
+  SCM_ASSERT_RANGE (3, end1, len >= 0);
+  SCM_ASSERT_RANGE (2, start1, s1 <= SCM_STRING_LENGTH (str1) && s1 >= 0);
+  SCM_ASSERT_RANGE (5, start2, s2 <= SCM_STRING_LENGTH (str2) && s2 >= 0);
+  SCM_ASSERT_RANGE (3, end1, e <= SCM_STRING_LENGTH (str1) && e >= 0);
+  SCM_ASSERT_RANGE (5, start2, len+s2 <= SCM_STRING_LENGTH (str2));
 
   SCM_SYSCALL(memmove((void *)(&(SCM_STRING_CHARS(str2)[s2])),
                      (void *)(&(SCM_STRING_CHARS(str1)[s1])),
                      len));
-  
+
   return scm_return_first(SCM_UNSPECIFIED, str1, str2);
 }
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0, 
+SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0,
            (SCM str, SCM start, SCM end, SCM fill),
-           "Change every character in @var{str} between @var{start} and @var{end} to\n"
-           "@var{fill-char}.\n\n"
-           "(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.\n\n"
-           "@example\n"
+           "Change every character in @var{str} between @var{start} and\n"
+           "@var{end} to @var{fill}.\n"
+           "\n"
+           "@lisp\n"
            "(define y \"abcdefg\")\n"
            "(substring-fill! y 1 3 #\\r)\n"
            "y\n"
            "@result{} \"arrdefg\"\n"
-           "@end example")
+           "@end lisp")
 #define FUNC_NAME s_scm_substring_fill_x
 {
   long i, e;
   char c;
-  SCM_VALIDATE_STRING (1,str);
-  SCM_VALIDATE_INUM_COPY (2,start,i);
-  SCM_VALIDATE_INUM_COPY (3,end,e);
-  SCM_VALIDATE_CHAR_COPY (4,fill,c);
-  SCM_ASSERT_RANGE (2,start,i <= SCM_STRING_LENGTH (str) && i >= 0);
-  SCM_ASSERT_RANGE (3,end,e <= SCM_STRING_LENGTH (str) && e >= 0);
+  SCM_VALIDATE_STRING (1, str);
+  SCM_VALIDATE_INUM_COPY (2, start, i);
+  SCM_VALIDATE_INUM_COPY (3, end, e);
+  SCM_VALIDATE_CHAR_COPY (4, fill, c);
+  SCM_ASSERT_RANGE (2, start, i <= SCM_STRING_LENGTH (str) && i >= 0);
+  SCM_ASSERT_RANGE (3, end, e <= SCM_STRING_LENGTH (str) && e >= 0);
   while (i<e) SCM_STRING_CHARS (str)[i++] = c;
   return SCM_UNSPECIFIED;
 }
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_null_p, "string-null?", 1, 0, 0, 
+SCM_DEFINE (scm_string_null_p, "string-null?", 1, 0, 0,
            (SCM str),
-           "Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}\n"
-           "otherwise.\n\n"
-           "(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}.\n\n"
-           "@example\n"
-           "(string-null? \"\")\n"
-           "@result{} #t\n\n"
-           "(string-null? y)\n"
-           "@result{} #f\n"
-           "@end example")
+           "Return @code{#t} if @var{str}'s length is zero, and\n"
+           "@code{#f} otherwise.\n"
+           "@lisp\n"
+           "(string-null? \"\")  @result{} #t\n"
+           "y                    @result{} \"foo\"\n"
+           "(string-null? y)     @result{} #f\n"
+           "@end lisp")
 #define FUNC_NAME s_scm_string_null_p
 {
-  SCM_VALIDATE_STRING (1,str);
-  return SCM_NEGATE_BOOL (SCM_STRING_LENGTH (str));
+  SCM_VALIDATE_STRING (1, str);
+  return SCM_BOOL (SCM_STRING_LENGTH (str) == 0);
 }
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_to_list, "string->list", 1, 0, 0, 
+SCM_DEFINE (scm_string_to_list, "string->list", 1, 0, 0,
            (SCM str),
-           "@samp{String->list} returns a newly allocated list of the\n"
-           "characters that make up the given string.  @samp{List->string}\n"
-           "returns a newly allocated string formed from the characters in the list\n"
-           "@var{list}, which must be a list of characters. @samp{String->list}\n"
-           "and @samp{list->string} are\n"
-           "inverses so far as @samp{equal?} is concerned.  (r5rs)")
+           "Return a newly allocated list of the characters that make up\n"
+           "the given string @var{str}. @code{string->list} and\n"
+           "@code{list->string} are inverses as far as @samp{equal?} is\n"
+           "concerned.")
 #define FUNC_NAME s_scm_string_to_list
 {
   long i;
   SCM res = SCM_EOL;
   unsigned char *src;
-  SCM_VALIDATE_STRING (1,str);
+  SCM_VALIDATE_STRING (1, str);
   src = SCM_STRING_UCHARS (str);
   for (i = SCM_STRING_LENGTH (str)-1;i >= 0;i--) res = scm_cons (SCM_MAKE_CHAR (src[i]), res);
   return res;
@@ -338,13 +279,17 @@ SCM_DEFINE (scm_string_to_list, "string->list", 1, 0, 0,
 static SCM
 string_copy (SCM str)
 {
-  return scm_makfromstr (SCM_STRING_CHARS (str), SCM_STRING_LENGTH (str), 0);
+  const char* chars = SCM_STRING_CHARS (str);
+  size_t length = SCM_STRING_LENGTH (str);
+  SCM new_string = scm_mem2string (chars, length);
+  scm_remember_upto_here_1 (str);
+  return new_string;
 }
 
 
-SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0, 
+SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0,
            (SCM str),
-           "Returns a newly allocated copy of the given @var{string}. (r5rs)")
+           "Return a newly allocated copy of the given @var{string}.")
 #define FUNC_NAME s_scm_string_copy
 {
   SCM_VALIDATE_STRING (1, str);
@@ -356,21 +301,21 @@ SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0,
 
 SCM_DEFINE (scm_string_fill_x, "string-fill!", 2, 0, 0,
            (SCM str, SCM chr),
-           "Stores @var{char} in every element of the given @var{string} and returns an\n"
-           "unspecified value.  (r5rs)")
+           "Store @var{char} in every element of the given @var{string} and\n"
+           "return an unspecified value.")
 #define FUNC_NAME s_scm_string_fill_x
 {
   register char *dst, c;
   register long k;
-  SCM_VALIDATE_STRING_COPY (1,str,dst);
-  SCM_VALIDATE_CHAR_COPY (2,chr,c);
+  SCM_VALIDATE_STRING_COPY (1, str, dst);
+  SCM_VALIDATE_CHAR_COPY (2, chr, c);
   for (k = SCM_STRING_LENGTH (str)-1;k >= 0;k--) dst[k] = c;
   return SCM_UNSPECIFIED;
 }
 #undef FUNC_NAME
 
 
-/* Helper function for the string uppercase conversion functions.  
+/* Helper function for the string uppercase conversion functions.
  * No argument checking is performed.  */
 static SCM
 string_upcase_x (SCM v)
@@ -384,16 +329,15 @@ string_upcase_x (SCM v)
 }
 
 
-SCM_DEFINE (scm_string_upcase_x, "string-upcase!", 1, 0, 0, 
+SCM_DEFINE (scm_string_upcase_x, "string-upcase!", 1, 0, 0,
            (SCM str),
-           "Destructively upcase every character in @code{str}.\n\n"
-           "(qdocs:) Converts each element in @var{str} to upper case.\n\n"
-           "@example\n"
-           "(string-upcase! y)\n"
-           "@result{} \"ARRDEFG\"\n\n"
-           "y\n"
-           "@result{} \"ARRDEFG\"\n"
-           "@end example")
+           "Destructively upcase every character in @var{str} and return\n"
+           "@var{str}.\n"
+           "@lisp\n"
+           "y                  @result{} \"arrdefg\"\n"
+           "(string-upcase! y) @result{} \"ARRDEFG\"\n"
+           "y                  @result{} \"ARRDEFG\"\n"
+           "@end lisp")
 #define FUNC_NAME s_scm_string_upcase_x
 {
   SCM_VALIDATE_STRING (1, str);
@@ -403,9 +347,10 @@ SCM_DEFINE (scm_string_upcase_x, "string-upcase!", 1, 0, 0,
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_upcase, "string-upcase", 1, 0, 0, 
+SCM_DEFINE (scm_string_upcase, "string-upcase", 1, 0, 0,
            (SCM str),
-           "Upcase every character in @code{str}.")
+           "Return a freshly allocated string containing the characters of\n"
+           "@var{str} in upper case.")
 #define FUNC_NAME s_scm_string_upcase
 {
   SCM_VALIDATE_STRING (1, str);
@@ -415,7 +360,7 @@ SCM_DEFINE (scm_string_upcase, "string-upcase", 1, 0, 0,
 #undef FUNC_NAME
 
 
-/* Helper function for the string lowercase conversion functions.  
+/* Helper function for the string lowercase conversion functions.
  * No argument checking is performed.  */
 static SCM
 string_downcase_x (SCM v)
@@ -429,18 +374,15 @@ string_downcase_x (SCM v)
 }
 
 
-SCM_DEFINE (scm_string_downcase_x, "string-downcase!", 1, 0, 0, 
+SCM_DEFINE (scm_string_downcase_x, "string-downcase!", 1, 0, 0,
            (SCM str),
-           "Destructively downcase every character in @code{str}.\n\n"
-           "(qdocs:) Converts each element in @var{str} to lower case.\n\n"
-           "@example\n"
-           "y\n"
-           "@result{} \"ARRDEFG\"\n\n"
-           "(string-downcase! y)\n"
-           "@result{} \"arrdefg\"\n\n"
-           "y\n"
-           "@result{} \"arrdefg\"\n"
-           "@end example")
+           "Destructively downcase every character in @var{str} and return\n"
+           "@var{str}.\n"
+           "@lisp\n"
+           "y                     @result{} \"ARRDEFG\"\n"
+           "(string-downcase! y)  @result{} \"arrdefg\"\n"
+           "y                     @result{} \"arrdefg\"\n"
+           "@end lisp")
 #define FUNC_NAME s_scm_string_downcase_x
 {
   SCM_VALIDATE_STRING (1, str);
@@ -450,9 +392,10 @@ SCM_DEFINE (scm_string_downcase_x, "string-downcase!", 1, 0, 0,
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_downcase, "string-downcase", 1, 0, 0, 
+SCM_DEFINE (scm_string_downcase, "string-downcase", 1, 0, 0,
            (SCM str),
-           "Downcase every character in @code{str}.")
+           "Return a freshly allocation string containing the characters in\n"
+           "@var{str} in lower case.")
 #define FUNC_NAME s_scm_string_downcase
 {
   SCM_VALIDATE_STRING (1, str);
@@ -462,18 +405,19 @@ SCM_DEFINE (scm_string_downcase, "string-downcase", 1, 0, 0,
 #undef FUNC_NAME
 
 
-/* Helper function for the string capitalization functions.  
+/* Helper function for the string capitalization functions.
  * No argument checking is performed.  */
 static SCM
 string_capitalize_x (SCM str)
 {
-  char *sz;
-  int i, len, in_word=0;
+  unsigned char *sz;
+  long i, len;
+  int in_word=0;
 
   len = SCM_STRING_LENGTH(str);
-  sz = SCM_STRING_CHARS (str);
+  sz = SCM_STRING_UCHARS (str);
   for(i=0; i<len;  i++) {
-    if(SCM_NFALSEP(scm_char_alphabetic_p(SCM_MAKE_CHAR(sz[i])))) {
+    if (!SCM_FALSEP (scm_char_alphabetic_p (SCM_MAKE_CHAR (sz[i])))) {
       if(!in_word) {
         sz[i] = scm_upcase(sz[i]);
         in_word = 1;
@@ -487,9 +431,16 @@ string_capitalize_x (SCM str)
 }
 
 
-SCM_DEFINE (scm_string_capitalize_x, "string-capitalize!", 1, 0, 0, 
+SCM_DEFINE (scm_string_capitalize_x, "string-capitalize!", 1, 0, 0,
            (SCM str),
-           "Destructively capitalize every character in @code{str}.")
+           "Upcase the first character of every word in @var{str}\n"
+           "destructively and return @var{str}.\n"
+           "\n"
+           "@lisp\n"
+           "y                      @result{} \"hello world\"\n"
+           "(string-capitalize! y) @result{} \"Hello World\"\n"
+           "y                      @result{} \"Hello World\"\n"
+           "@end lisp")
 #define FUNC_NAME s_scm_string_capitalize_x
 {
   SCM_VALIDATE_STRING (1, str);
@@ -499,9 +450,11 @@ SCM_DEFINE (scm_string_capitalize_x, "string-capitalize!", 1, 0, 0,
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_capitalize, "string-capitalize", 1, 0, 0, 
+SCM_DEFINE (scm_string_capitalize, "string-capitalize", 1, 0, 0,
            (SCM str),
-           "Capitalize every character in @code{str}.")
+           "Return a freshly allocated string with the characters in\n"
+           "@var{str}, where the first character of every word is\n"
+           "capitalized.")
 #define FUNC_NAME s_scm_string_capitalize
 {
   SCM_VALIDATE_STRING (1, str);
@@ -511,9 +464,61 @@ SCM_DEFINE (scm_string_capitalize, "string-capitalize", 1, 0, 0,
 #undef FUNC_NAME
 
 
-SCM_DEFINE (scm_string_ci_to_symbol, "string-ci->symbol", 1, 0, 0, 
-           (SCM str),
-           "Return the symbol whose name is @var{str}, downcased in necessary(???).")
+SCM_DEFINE (scm_string_split, "string-split", 2, 0, 0,
+           (SCM str, SCM chr),
+           "Split the string @var{str} into the a list of the substrings delimited\n"
+           "by appearances of the character @var{chr}.  Note that an empty substring\n"
+           "between separator characters will result in an empty string in the\n"
+           "result list.\n"
+           "\n"
+           "@lisp\n"
+           "(string-split \"root:x:0:0:root:/root:/bin/bash\" #\\:)\n"
+           "@result{}\n"
+           "(\"root\" \"x\" \"0\" \"0\" \"root\" \"/root\" \"/bin/bash\")\n"
+           "\n"
+           "(string-split \"::\" #\\:)\n"
+           "@result{}\n"
+           "(\"\" \"\" \"\")\n"
+           "\n"
+           "(string-split \"\" #\\:)\n"
+           "@result{}\n"
+           "(\"\")\n"
+           "@end lisp")
+#define FUNC_NAME s_scm_string_split
+{
+  long idx, last_idx;
+  char * p;
+  int ch;
+  SCM res = SCM_EOL;
+
+  SCM_VALIDATE_STRING (1, str);
+  SCM_VALIDATE_CHAR (2, chr);
+
+  idx = SCM_STRING_LENGTH (str);
+  p = SCM_STRING_CHARS (str);
+  ch = SCM_CHAR (chr);
+  while (idx >= 0)
+    {
+      last_idx = idx;
+      while (idx > 0 && p[idx - 1] != ch)
+       idx--;
+      if (idx >= 0)
+       {
+         res = scm_cons (scm_mem2string (p + idx, last_idx - idx), res);
+         idx--;
+       }
+    }
+  scm_remember_upto_here_1 (str);
+  return res;
+}
+#undef FUNC_NAME
+
+
+SCM_DEFINE (scm_string_ci_to_symbol, "string-ci->symbol", 1, 0, 0,
+           (SCM str),
+           "Return the symbol whose name is @var{str}.  @var{str} is\n"
+           "converted to lowercase before the conversion is done, if Guile\n"
+           "is currently reading symbols case-insensitively.")
 #define FUNC_NAME s_scm_string_ci_to_symbol
 {
   return scm_string_to_symbol (SCM_CASE_INSENSITIVE_P
@@ -525,9 +530,7 @@ SCM_DEFINE (scm_string_ci_to_symbol, "string-ci->symbol", 1, 0, 0,
 void
 scm_init_strop ()
 {
-#ifndef SCM_MAGIC_SNARFER
 #include "libguile/strop.x"
-#endif
 }
 
 /*