12.18 Low level string operations

The arguments str to these operations must be references to strings, the arguments fx must be fixnums in the appropriate range, the arguments ch must be characters. The following bindings are exported by the library (vicare system $strings).

Constructors

Unsafe Operation: $make-string fx

Allocate a new string capable of holding fx characters and return a reference to it.

Unsafe Operation: $string ch …

Allocate a new string and initialise it with the given characters.

Function: $string-copy str

Build and return a newly allocated string holding the same characters of str.

Function: $string-copy! src.str src.start dst.str dst.start src.end

Copy the characters of src.str from src.start inclusive to src.end exclusive, to dst.str starting at dst.start inclusive.

Function: $string-copy!/count src.str src.start dst.str dst.start count

Copy count characters from src.str starting at src.start inclusive to dst.str starting at dst.start inclusive.

Function: $string-self-copy-forwards!/count str src.start dst.start count

Copy count characters of str from src.start inclusive to str itself starting at dst.start inclusive. The copy happens forwards, so it is suitable for the case src.start > dst.start.

Function: $string-self-copy-backwards!/count str src.start dst.start count

Copy count characters of str from src.start inclusive to str itself starting at dst.start inclusive. The copy happens backwards, so it is suitable for the case src.start < dst.start.

Function: $substring str start end

Build and return a newly allocated string holding the range of character between start (inclusive) and end (exclusive).

Function: $string-concatenate total-len strs

Concatenate the strings in the list strs, return the result. The resulting string must have length total-len. Assume the arguments have been already validated.

Function: $string-reverse-and-concatenate total-len strs

Reverse the list of strings strs and concatenate its items; return the result. The resulting string must have length total-len. Assume the arguments have been already validated.

Accessors and mutators

Unsafe Operation: $string-ref str fx

Return the character at offset fx in str.

Unsafe Operation: $string-set! str fx ch

Store ch at index fx of str.

Function: $string-fill! str start end fill

Fill the positions in str from start inclusive to end exclusive with fill.

Inspection

Unsafe Operation: $string-length str

Return a fixnum representing the length of the operand.

Function: $string-total-length init-len strs

Given the list of strings strs: compute the total length of the strings, add it to init-len and return the result. If init-len is zero: the returned value is the total length of the strings in strs. The returned value may or may not be in the range of the maximum string size.

Unsafe Operations: $string-empty? str

Return #t if the string str is empty, otherwise return #f.

Comparison

Unsafe Operation: $string= str1 str2

Return #t if str1 and str2 represent the same string; otherwise return #f.

Function: $string!=? str1 str2

The arguments must be booleans. Return #t if the arguments are different; otherwise return #f.

Unsafe Operation: $string< str1 str2

Unsafe Operation: $string> str1 str2

Unsafe Operation: $string<= str1 str2

Unsafe Operation: $string>= str1 str2

Dyadic lexicographic comparison functions for strings. Return #t if str1 and str2 compare as the name implies; otherwise return #f.

Function: $string-max str1 str2

Function: $string-min str1 str2

Return the maximal or minimal string argument according to $string<.

Conversion function

Unsafe Operation: $fixnum->string fx base

Return a string object representing fx in base. base must be one among: 2, 8, 10, 16.

Function: $string->latin1 string

Function: $latin1->string bytevevctor

Convert to and from a Scheme string and a Scheme bytevector holding the Latin-1 encoding of the characters. If a character in string is out of range: raise an exception; this validation is not removed when arguments validation is disabled.

Function: $string->octets string

Function: $octets->string bytevector

Convert to and from a Scheme string and a Scheme bytevector holding the raw octets encoding of the characters. Octets are converted to characters with $fixnum->char; characters are converted to octets with $char->fixnum. Raise an exception if the conversion is not possible; this validation is not removed when arguments validation is disabled.

Function: $string->ascii string

Function: $ascii->string bytevevctor

Convert to and from a Scheme string and a Scheme bytevector holding the ASCII encoding of the characters. If a character in string is out of range: raise an exception; this validation is not removed when arguments validation is disabled.

Function: $octets-encoded-string? string

Return #t if string can be interpreted as an octets encoded string, otherwise return #f. A character is considered octets–encoded if its integer representation chi satisfies:

(<= 0 chi 255)      ⇒ #t

Function: $ascii-encoded-string? string

Return #t if string can be interpreted as an ASCII encoded string, otherwise return #f. A character is considered an ASCII code point if its integer representation chi satisfies:

(<= #x00 chi #x7F)      ⇒ #t

Function: $latin1-encoded-string? string

Return #t if string can be interpreted as a Latin1 encoded string, otherwise return #f. A character in the string is considered a Latin1 code point if its integer representation chi satisfies:

(or (<= #x20 chi #x7E)
    (<= #xA0 chi #xFF))
⇒ #t

Function: $string-base64->bytevector string

Function: $bytevector->string-base64 bytevector

Convert to and from a Scheme string and a Scheme bytevector. The input string contains the ASCII Base64 representation of the octets. The output string contains the ASCII Base64 representation of octets. If an error occurs in the conversion: an exception is raised.

Function: $uri-encoded-string? string

Function: $percent-encoded-string? string

Return #t if the argument is correctly percent–encoded string according to RFC 3986. This means every character in the string is associated to a character in the ASCII encoding and additionally the constraints of RFC 3986 are satisfied.

If the characters in string are invalid: raise an exception; this validation is not removed when arguments validation is disabled.

Miscellaneous functions

Unsafe Operation: $interned-strings

Return a vector holding the currently interned strings.