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-base64tobin
  • string-base64toint
  • string-base64touint
  • string-binary
  • string-concat
  • string-constructor
  • string-copy
  • string-count
  • string-delete
  • string-deposit
  • string-format
  • string-hexatobin
  • string-hexatoint
  • string-hexatouint
  • string-left-trim
  • string-length
  • string-lowercase
  • string-ndeposit
  • string-ord
  • string-position
  • string-remove
  • string-reverse
  • string-right-trim
  • string-scan-binary
  • string-scan-float
  • string-scan-integer
  • string-scan-scalar
  • string-scan-unsignedinteger
  • string-search
  • string-string
  • string-subseq
  • string-substitute
  • string-trim
  • string-uppercase

  • 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"

    Updated 29/11/2008 Copyright © 2008 Walther Waeles
    SourceForge.net Logo