string Class Reference

The class string defines the kind of storage needed to contain arrays of characters and the methods needed to manipulate them.

Unicode characters are stored in UTF-8 encoding, ie using one to six bytes for each character other than plain ASCII. Each string is represented by a wwlisp cell, which contains in its "car" part a pointer to the text of the string on a special segment (the string space). On the string space, each string (or symbolic atom name) is delimited like in C by a 0x0 byte.

The string space is submitted to a copying garbage collection when exhausted.

string-<

string-=

string->

string-scan-unsignedinteger

List of all Inherited Classes

class

string-<

(< arg1 arg2)

Function Type	subr
Arguments	a string, a string
Return Value	t or nil
Description	returns t if the second string is lexically greater than the first
Example	(< "alphabet" "arthritis") => t

string-=

(= arg1 arg2 )

Function Type	subr
Arguments	a string, a string
Return Value	t or nil
Description	returns t if the two strings are lexically equal
Example	(= "hello" "hello" ) => t

string->

(> arg1 arg2)

Function Type	subr
Arguments	a string, a string
Return Value	t or nil
Description	returns t if the second string is lexically before the first
Example	(> "alphabet" "alpaga") => t

string-base64tobin

(base64tobin arg )

Function Type	subr
Arguments	a string
Return Value	a binary block
Description	returns a binary block where the content is the translation of a base64 string to byte values
Example	(ord(base64tobin "AAAAAAAAAAAAAAA" )) => (0 0 0 0 0 0 0 0 0 0 0)

string-base64toint

(base64toint arg )

Function Type	subr
Arguments	a string
Return Value	an integer
Description	returns an integer containing the value which was translated as base64;
Example	(base64toint "wA") => 192

string-base64touint

(base64toint arg )

Function Type	subr
Arguments	a string
Return Value	an unsignedinteger
Description	returns an unsignedinteger containing the value which was translated as base64;
Example	(base64touint "wA") => 0xc0

string-binary

(binary arg )

Function Type	subr
Arguments	a string
Return Value	a binary
Description	returns a binary containing the same characters as the input string
Example	(binary "hello" )

string-concat

(concat arg1 arg2 ... argn )

Function Type	subr
Arguments	a string, an unlimited number of strings
Return Value	a string
Description	returns a string made of a concatenated copy of all the strings given as argument
Example	(concat "hello" ", " "world" ) => "hello, world"

string-constructor

(make-instance string arg1 arg2 )

Function Type	subr
Arguments	the symbol string, an integer, an optional string
Return Value	a string
Description	returns a string made by repeating the string given as second argument as many times as stated in the first argument; if the second argument is missing, it is assumed equal to one space character
Example	(make-instance string 5 "ab" ) => "ababababab"

string-copy

(copy arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a new string containing the same characters as the original given as argument
Example	(copy "hello" ) => "hello"

string-count

(count arg1 arg2 )

Function Type	subr
Arguments	a string, a string
Return Value	an integer
Description	counts how many times the string given as second argument appears as a part of the string given as first argument
Example	(count "hello, world! said Orlando" "rl" ) => 2

string-delete

(delete arg1 arg2)

Function Type	subr
Arguments	a string, a string
Return Value	a string
Description	returns the string given as first argument where all the occurrences of the string given as second argument have been deleted; the original string is modified
Example	(delete "hello, world" "wo" ) => "hello, rld"

string-deposit

(deposit arg1 arg2 arg3 arg4 )

Function Type	subr
Arguments	mandatory string, mandatory string, mandatory integer, optional integer
Return Value	a string
Description	makes a new string where the second argument has been deposited in the first argument at the position stated in the third argument up to the position before that stated in the fourth argument, or the length of the string to deposit if the fourth argument is not given, or the length of the string to deposit
Example	(deposit string1 string2 pos-start pos-end+1)

string-format

(format arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	formats the string object passed as argument and returns another string; the double quotes embedded in the original string are doubled, and the result is enclosed in double quotes
Example	(format "hello") => """hello"""

string-hexatobin

(hexatobin arg )

Function Type	subr
Arguments	a string
Return Value	a binary block
Description	returns a binary block where the content is the translation of a hexadecimal string to byte values
Example	(ord(hexatobin "0123456789abcdef" )) => (1 35 69 103 137 171 205 239)

string-hexatoint

(hexatoint arg )

Function Type	subr
Arguments	a string
Return Value	an integer
Description	returns an integer with the value given in hexadecimal as argument
Example	(hexatoint "ffffffffffffffff" ) => -1

string-hexatouint

(hexatoint arg )

Function Type	subr
Arguments	a string
Return Value	an unsignedinteger
Description	returns an unsignedinteger with the value given in hexadecimal as argument
Example	(hexatouint "ffffffffffffffff" ) => 0xfffffffffffffffff

string-left-trim

(left-trim arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a string containing the same as the string given as argument, but all the spaces beginning from the left being stripped out; a string made entirely of spaces becomes an empty string
Example	(left-trim " hello" ) =>"hello"

string-length

(length arg )

Function Type	subr
Arguments	a string
Return Value	an integer
Description	returns the number of bytes composing the string given as argument; as UTF-8 encoded characters might take more than one byte, the result of length may be greater than the number of displayed characters
Example	(length "hello" ) => 5

string-lowercase

(lowercase arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a copy of the string given as argument where all the uppercase characters have been translated to their lowercase values; UTF-8 sequences are not modified
Example	(lowercase "HELLO" ) => "hello"

string-ndeposit

(ndeposit arg1 arg2 arg3 arg4 )

Function Type	subr
Arguments	mandatory string, mandatory string, mandatory integer, optional integer
Return Value	a string
Description	returns the string given as first argument, where the second argument has been deposited at the position stated in the third argument up to the position before that stated in the fourth argument, or the length of the string to deposit if the fourth argument is not given, or the length of the string to deposit
Example	(ndeposit string1 string2 pos-start pos-end+1)

string-ord

(ord arg )

Function Type	subr
Arguments	a string
Return Value	a list of integers or nil
Description	returns a list of integers containing each a Unicode character of the string; each integer has a value from 0 to the maximal value of Unicode;
Example	(ord "€" ) => (8364)

string-position

(position arg1 arg2 )

Function Type	subr
Arguments	a string, a string
Return Value	an integer or nil
Description	returns the position of the string given as second argument in the string given as first argument; returns nil if the second argument is not found in the first; the first position is zero
Example	(position "abcdefgh" "ef" ) => 4

string-remove

(remove arg1 arg2 )

Function Type	subr
Arguments	a string, a string
Return Value	a string
Description	returns a copy of the string given as first argument where all the occurrences of the string given as second argument have been deleted; the original string is not modified
Example	(remove "hello, world" "wo" ) => "hello, rld"

string-reverse

(reverse arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a string where the sequence of the bytes have been reversed, the first becoming the last; UTF-8 sequences are not respected and are hence destroyed; in order to respect UTF-8, do (chr(reverse(ord string1)))
Example	(reverse "Hello, World!" ) => "!dlroW ,olleH"

string-right-trim

(right-trim arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a string containing the same as the string given as argument, but all the spaces beginning from the right being stripped out; a string made entirely of spaces becomes an empty string
Example	(right-trim "hello " ) =>"hello"

string-scan-binary

(scan-binary arg )

Function Type	subr
Arguments	a string
Return Value	a binary block or nil
Description	scans the string passed as argument and tries to recognize a valid binary block in its text; if true returns a binary object; if not returns nil ; is the default recognizer for the class binary ; the text must begin by the string "[binary]" or "[binary/base64]" immediately followed by the value of the binary block MIME-base64 encoded (ie: base64 without "=" padding) the text may also begin with "[binary/hex]" followed by the value of the binary block encoded in hexadecimal; the text may also begin with "0x" followed by the value of the binary block encoded in hexadecimal;
Example	(scan-binary "[binary]AAAAAAAAAAAAAAAAAAAAAA" ) => [binary]AAAAAAAAAAAAAAAAAAAAAA (type [binary]AAAAAAAAAAAAAAAAAAAAAA) => binary (length [binary]AAAAAAAAAAAAAAAAAAAAAA) => 16

string-scan-float

(scan-float arg )

Function Type	subr
Arguments	a string
Return Value	a float or nil
Description	scans the string passed as argument and tries to recognize a valid float in its text; if true, returns it; if not returns nil; is the default recognizer for the class float
Example	(scan-float "33.0" ) => 33.000000

string-scan-integer

(scan-integer arg )

Function Type	subr
Arguments	a string
Return Value	an integer or nil
Description	scans the string passed as argument and tries to recognize a valid integer in its text; if true, returns it; if not returns nil; is the default recognizer for the class integer
Example	(scan-integer "33" ) => 33

string-scan-scalar

(scan-scalar arg )

Function Type	subr
Arguments	a string
Return Value	an integer, an unsignedinteger or a float, or nil
Description	scans the string passed as argument and tries to recognize a valid unsignedinteger, or a valid integer, or a valid float in its text; if true, returns the object; if not returns nil; is the default recognizer for the class scalar and one of the default recognizers configured at startup in readtable and stdin
Example	(scan-scalar "33" ) => 33

string-scan-unsignedinteger

(scan-unsignedinteger arg )

Function Type	subr
Arguments	a string
Return Value	an unsignedinteger or nil
Description	scans the string passed as argument and tries to recognize a valid unsignedinteger in its text; if true, returns it; if not returns nil; is the default recognizer for the class unsignedinteger
Example	(scan-unsignedinteger "0x33" ) => 0x33

string-search

(search arg1 arg2 )

Function Type	subr
Arguments	a string, a string
Return Value	an integer or nil
Description	returns the position of the string given as second argument in the string given as first argument; returns nil if the second argument is not found in the first; the first position is zero
Example	(search "abcdefgh" "ef" ) => 4

string-string

(string arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns the argument; needed when converting an argument which can be float, integer or string
Example	(string "33" ) => "33" (string 33) => "33"

string-subseq

(subseq arg1 arg2 arg3 )

Function Type	subr
Arguments	a string, an integer, an optional integer
Return Value	a string or nil
Description	returns a string extracted from the first argument starting at the position given as second argument, and ranging up to the position just before the one given as third argument; if no third argument is provided, the extraction goes up to the end of the first argument; returns nil if there is nothing to extract at the required positions ; first position is at 0
Example	(subseq "Hello, World!" 0 4) => "Hell"

string-substitute

(substitute arg1 arg2 arg3 )

Function Type	subr
Arguments	a string, a string, a string
Return Value	a string
Description	returns a copy of the string given as first argument where all occurences of the third argument have been replaced by the second argument; the total length of the resulting string can be modified, as the target and substitution can be of different lengths
Example	(substitute "Hello, World!" "Frien" "Worl" ) => "Hello, Friend!"

string-trim

(trim arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a string containing the same as the string given as argument, but all the spaces beginning from the left and all the spaces beginning from the right being stripped out; a string made entirely of spaces becomes an empty string
Example	(trim " hello " ) =>"hello"

string-uppercase

(uppercase arg )

Function Type	subr
Arguments	a string
Return Value	a string
Description	returns a copy of the string given as argument where all the lowercase characters have been translated to their uppercase values; UTF-8 sequences are not modified
Example	(uppercase "hello" ) => "HELLO"