strings.texi (7626B)
1 @c -*-texinfo-*- 2 @setfilename ../src/strings 3 4 @node Strings, Characters, Numbers, Top 5 @comment node-name, next, previous, up 6 7 @chapter Strings 8 @cindex strings 9 10 A string is an object that represent a sequence of characters (for 11 now, only ASCII is supported in klisp, in the future, full UNICODE 12 will be supported). The external representation of strings consists 13 of a leading ``"'', the characters of the string and a closing ``"''. 14 Both double quote and backslash should be escaped to appear withing 15 strings. Some other characters also have an escaped form for 16 convenience. All of these are written with a leading slash (``\''). 17 In klisp these are: double quote (``\"''), backslash (``\\''), null 18 (``\0''), alarm (``\a''), backspace (``\b''), tab (``\t''), newline 19 (``\n''), return (``\r''), vertical tab (``\v''), and formfeed 20 (``\f''). You can also use inline hex escapes to include arbitary 21 unicode codepoints (only ASCII range supported for now). The syntax 22 is ``\x<hex codepoint>;''. New lines can be escaped to simplify the 23 accomodation of literal strings in source code, to do this: use ``\'' 24 followed by any ammount of intraline whitespace, a new line and 25 another ammount of intraline whitespace. All of that intraline 26 whitespace and the newline, together with the leading slash is 27 discarded by the reader and doesn't end up in the string being read. 28 29 A string has a length that is fixed at creation time, and as many 30 characters, indexed from @code{0} to @code{length-1}. 31 32 Strings may be mutable or immutable. If an attempt is made to 33 mutate an immutable string, an error is signaled. Two immutable 34 strings are ``eq?'' iff they are ``equal?''. Two mutable strings are 35 ``eq?'' if they were created by the same constructor call. Two 36 mutable strings are ``equal?'' iff they are ``string=?''. For now it 37 is undefined if a mutable and an immutable strings that are 38 ``string=?'' are ``equal?'' or not. The only exception is the empty 39 string. There is only one empty string (all empty strings are ``eq?'' 40 to each other) and it should be considered immutable. Even if an 41 attempt is made to return a new empty string (like calling 42 @code{(string)}, the canonical immutable empty string is returned. 43 The string type is encapsulated. 44 45 SOURCE NOTE: This section is still missing from the report. The 46 features defined here were taken mostly from r7rs scheme. It is 47 possible that in the future, klisp only admits immutable strings (like 48 lua and java), and that operations for contructing strings are moved 49 to a new type (like Java's StringBuilder/StringBuffer). But for now, 50 compatibility with r7rs was preferred/simpler. 51 52 @deffn Applicative string? (string? . objects) 53 The primitive type predicate for type string. @code{string?} 54 returns true iff all the objects in @code{objects} are of type 55 string. 56 @end deffn 57 58 @deffn Applicative immutable-string? (immutable-string? objects) 59 @deffnx Applicative mutable-string? (mutable-string? objects) 60 The primitive type predicates for types immutable string and mutable 61 string. These return true iff all the objects in @code{objects} are of 62 type immutable string or mutable string respectively. 63 64 SOURCE NOTE: these aren't provided in the Kernel report, but added for 65 convenience. These can be implemented in standard kernel by using guards. 66 @end deffn 67 68 @deffn Applicative string=? (string=? . strings) 69 @deffnx Applicative string<? (string<? . strings) 70 @deffnx Applicative string<=? (string<=? . strings) 71 @deffnx Applicative string>? (string>? . strings) 72 @deffnx Applicative string>=? (string>=? . strings) 73 These predicates compare any number of strings by their 74 lexicographic order. 75 @end deffn 76 77 @deffn Applicative string-ci=? (string-ci=? . strings) 78 @deffnx Applicative string-ci<? (string-ci<? . strings) 79 @deffnx Applicative string-ci<=? (string-ci<=? . strings) 80 @deffnx Applicative string-ci>? (string-ci>? . strings) 81 @deffnx Applicative string-ci>=? (string-ci>=? . strings) 82 These predicates convert the strings to lowercase and then compare 83 them using their lexicographic order. 84 @end deffn 85 86 @deffn Applicative make-string (make-string k [char]) 87 Applicative @code{make-string} constructs and returns a new mutable 88 string of length @code{k}. If @code{char} is specified, then all 89 characters in the returned string are @code{char}, otherwise the 90 content of the string is unspecified. 91 @end deffn 92 93 @deffn Applicative string (string . chars) 94 Applicative @code{string} contructs and return a new mutable string 95 composed of the character arguments. 96 @end deffn 97 98 @deffn Applicative string-length (string-length string) 99 Applicative @code{string-length} returns the length of 100 @code{string}. 101 @end deffn 102 103 @deffn Applicative string-ref (string-ref string k) 104 Applicative @code{string-ref} returns the character of @code{string} 105 at position @code{k}. If @code{k} is out of bounds (i.e. less than 106 @code{0} or greater or equal than @code{(string-length string)}) an error is 107 signaled. 108 @end deffn 109 110 @deffn Applicative string-set! (string-set! string k char) 111 Applicative @code{string-set!} replaces the character with index 112 @code{k} in @code{string} with character @code{char}. If @code{k} is 113 out of bounds, or @code{string} is immutable, an error is signaled. 114 @end deffn 115 116 @deffn Applicative string-fill! (string-fill! string char) 117 Applicative @code{string-fill!} replaces all the characters in 118 @code{string} with character @code{char}. If @code{string} is an 119 immutable string, an error is signaled. 120 @end deffn 121 122 @deffn Applicative substring (substring string k1 k2) 123 Both @code{k1} & @code{k2-1} should be valid indexes in 124 @code{string}. Also it should be the case that @code{k1 <= k2}. 125 126 Applicative @code{substring} constructs and returns a new mutable 127 string with length @code{k2 - k1}, with the characters from 128 @code{string}, starting at index @code{k1} (inclusive) and ending at 129 index @code{k2} (exclusive). 130 @end deffn 131 132 @deffn Applicative string-append (string-append . strings) 133 Applicative @code{string-append} constructs and returns a new 134 mutable string consisting of the concatenation of all its arguments. 135 @end deffn 136 137 @deffn Applicative string-copy (string-copy string) 138 Applicative @code{string-copy} constructs and returns a new mutable 139 string with the same length and characters as @code{string}. 140 @end deffn 141 142 @deffn Applicative string->immutable-string (string->immutable-string string) 143 Applicative @code{string->immutable-string} constructs and returns a 144 new immutable string with the same length and characters as 145 @code{string}. 146 @end deffn 147 148 @deffn Applicative string->list (string->list string) 149 @deffnx Applicative list->string (list->string chars) 150 @deffnx Applicative string->vector (string->vector string) 151 @deffnx Applicative vector->string (vector->string vchars) 152 @deffnx Applicative string->bytevector (string->bytevector string) 153 @deffnx Applicative bytevector->string (bytevector->string bvchars) 154 These applicatives convert between strings and list of characters, 155 vectors of characters, and bytevectors of characters. The objects 156 returned by these applicatives are always mutable. 157 @end deffn 158 159 @deffn Applicative string-upcase (string-upcase string) 160 @deffnx Applicative string-downcase (string-downcase string) 161 @deffnx Applicative string-titlecase (string-titlecase string) 162 @deffnx Applicative string-foldcase (string-foldcase string) 163 These applicatives perform the respective case folding on the passed 164 @code{string} and return a new mutable strings as a result. The 165 original @code{string} is not modified. For now in klisp only ASCII 166 is implemented, and so @code{string-foldcase} is the same as 167 @code{string-downcase}. 168 @end deffn 169