String Class

String Creation

The following creates a string in Carapace script:

    "Hello there!"

The create function can be used to create a string of a given length e.g.

    (create String 20)

creates a string containing 20 spaces.

Similarly,

    (create String 20 "a")

creates a string containing 20 letter 'a' characters.

Finally,

    (create String 20 "copy me!")

creates a copy of the supplied string -- in this case a returns a new string also containing copy me!

String Properties

property name	property type	description
`length`	Integer	the length of the string

String Methods

method name	description
`upcase`	convert the string to upper case
`downcase`	convert the string to lower case
`format`	format the string according to the supplied format specification
`+`	return a new string which is the concatenation of this string with the supplied ones
`toFile`	write the contents of this string to the supplied file
`fromFile`	fill this string from the contents of the supplied file
`replace`	replace substrings of this strings with another string
`search`	search this string for an occurrence of the supplied data
`translate`	surgically modify this string data to translate the given characters
`substring`	return a substring of this string
`trim`	return a new string created by trimming this string ie. by removing characters from the beginning and the end of this string
`parse`	assuming this string holds a valid Carapace script, parse the expressions and return them
`evaluate`	assuming this string holds a valid Carapace script, parse the expressions and evaluate them
`+=`	surgically update this string by appending the supplied object (after converting that object to string form)
`==`	test if this string is equal to the supplied one
`!=`	test if this string is not equal to the supplied one
`<`	test whether this string is less than the supplied one
`>`	test whether this string is greater than the supplied one
`<=`	test whether this string is less than or equal to the supplied one
`>=`	test whether this string is greater than or equal to the supplied one
`integer`	convert this string to an integer - assumes the string holds a sequence of digits
`real`	convert this string to a real number - assumes the string holds a sequence of digits and a decimal point
`split`	split this string into fragments, depending on the supplied arguments
`string`	convert this string to a string - in fact, a new copy is made
`symbol`	convert this string to a symbol
`chopFrom`	return a new string formed by chopping the end of this string - the chop point is determined by searching for the supplied substring
`binary`	create a binary equivalent of this string
`copy`	create a new copy of this string
`set`	set a character within this string - treating the string as an array of characters
`get`	get a character from this string - treating the string as an array of characters
`hexify`	surgically update this string, replacing any characters in the supplied string with their hex equivalents - useful when dealing with HTTP
`dehexify`	surgically update this string, replacing any characters in the supplied string with their hex equivalents - useful when dealing with HTTP
`htmlRow`	turn this string into a row for an HTML table, where each table cell contains a single character
`digest`	create the MD5 digest (see RFC 1321) for the string
`hash`	calculate a simple hash of the string given the supplied modulo
`base64`	encode/decode this object using the Base 64 (MIME RFC 2045) encoding scheme
`quotedPrintable`	encode/decode this object using the `quoted-printable` (MIME RFC 2045) encoding scheme

`upcase`

Convert the string to upper case. A new string is returned, the original is unchanged.

Arguments: none

Return type: String

`downcase`

Convert the string to lower case. A new string is returned, the original is unchanged.

Arguments: none

Return type: String

`format`

Format the string according to the supplied format specification. The format spec is the standard C printf spec. The following are valid examples:


    "%-6s"
    "%*s"

If the format spec requires additional integer arguments, then these must be supplied

This returns a new String and does not modify the contained one.

Arguments:

formatSpec	`String`
...	one or two `Integer`s to match the `formatSpec`

Return type: an appropriately formatted String

`+`

Return a new string which is the concatenation of this string with all the supplied ones. The supplied strings can be passed as a single List or as a sequence of Strings.

Arguments: a List of Strings or one one or more String values.

Return type: String

`toFile`

Write the contents of this string to the supplied file.

Arguments:

filename String

Return type: List - the empty list () is returned.

`fromFile`

Fill this string from the contents of the supplied file. Surgically modifies this string.

Arguments:

filename String

Return type: List - the empty list () is returned.

`replace`

Replace substrings of this strings with another string. Surgically modifies this string.

Arguments:

toChange	`String`
replacementValue	`String`

Return type: List - the empty list () is returned.

`search`

Search this string for an occurrence of the supplied data. If found, the integer offset is returned otherwise the empty list () is returned.

By default, the search is case sensitive. If the (optional) 3rd argument is (), then the search is case insensitive.

Arguments:

toFind	`String`
offset - optional	`Integer`
caseSensitivity - optional	`Object`

Return type: Integer or the empty List () is returned.

`translate`

Surgically modify this string data to translate the given characters. All characters in the from argument are translated to corresponding entries in the to argument. The arguments must be the same length.

Arguments:

from	`String`
to	`String`

Return type: the empty List

`substring`

Return a substring of this string. If the length is omitted or is negative, then the substring goes to the end of this string.

Arguments:

offset	`Integer`
length - optional	`Integer`

Return type: String

`trim`

Return a new string created by trimming this string ie. by removing characters from the beginning and the end of this string. Any character in the supplied string is removed from the beginning and the end so that the resulting string does not start or end with any character in the supplied string.

Arguments:

charsToRemove String

Return type: String

`parse`

Assuming this string holds a valid Carapace script, parse the expressions and return them.

Arguments: none

Return type: List

`evaluate`

Assuming this string holds a valid Carapace script, parse the expressions and evaluate them. The result of the evaluation is returned.

Arguments: none

Return type: Object

`+=`

Surgically update this string by appending the supplied object (after converting that object to string form).

Arguments:

obj Object

Return type: the empty List () is returned.

`==`

Test whether this string is equal to the supplied one.

Arguments:

x String

Return type: Object

`!=`

Test whether this string is not equal to the supplied one.

Arguments:

x String

Return type: Object

`<`

Test whether this string is less than the supplied one.

Arguments:

x String

Return type: Object

`>`

Test whether this string is greater than the supplied one.

Arguments:

x String

Return type: Object

`<=`

Test whether this string is less than or equals the supplied one.

Arguments:

x String

Return type: Object

`>=`

Test whether this string is greater than or equals the supplied one.

Arguments:

x String

Return type: Object

`integer`

Convert this string to an integer - assumes the string holds a sequence of digits.

Arguments: none

Return type: Integer

`real`

Convert this string to a real number - assumes the string holds a sequence of digits and a decimal point.

Arguments: none

Return type: Real

`split`

Split this string into fragments.

A nFragments count can be supplied so that the splitting will stop after this number of fragments has been created. If this value is negative, it is taken to mean all (the default).

A evaporateGaps flag can be supplied which -- a () value prevents gaps from being evaporated resulting in an empty string being split between two consecutive delimiters.

This string can be split into individual characters (ie. into a list of single-length strings) by making the boundary the empty string.

It is possible to split on an empty string eg. to break a word into letters:

    ("hello".split "") --> ( "h" "e" "l" "l" "o" )

It is more usual to split on a non-null string eg. to split a sentence into words:

    ("once   upon  a time".split " ") --> ( "once" "upon" "a" "time" )

A more complex example follows:

    ("a.b..c".split "." -1 ()) --> ( "a" "b" "" "c" )

Arguments:

boundary	`String`
nFragments (optional)	`Integer`
preserveGaps (optional)	`Object`

Return type: List

`string`

Convert this string to a string - in fact, a new copy is made.

This method is included for the sake of completion, since if every object has a string method to return a string representation of the object, it makes life a lot easier to print or log objects to a file etc.

Arguments: none

Return type: String

`symbol`

Convert this string to a symbol.

Arguments: none

Return type: Symbol

`chopFrom`

Return a new string formed by chopping the end of this string - the chop point is determined by searching for the supplied substring.

For example:

    ( chopFrom "abcdef..." "." ) --> "abcdef"

Arguments:

boundary	`String`
nFragments - optional	`Integer`

Return type: List

`binary`

Create a binary equivalent of this string.

For example:

    ( "ABC".binary ) --> 0x"414243"

Arguments: none

Return type: Binary

`copy`

Create a new copy of this string.

Arguments: none

Return type: String

`set`

Set a character within this string - treating the string as an array of characters. This surgically modifies this string.

For example, the following script

    (set greeting "Hello there!")
    (greeting.set 1 "a")
    (print greeting)

will print out the modified greeting

    "Hallo there!"

This set method is reasonably tolerant of the type of its second argument - which can be a String, Integer or a Binary value.

Note that when indexing into a string the initial index is 0 rather than 1

Arguments:

index	`Integer`
newCharacter	`String` or Integer or Binary

Return type: the empty List () is returned

`get`

Get a character from within this string - treating the string as an array of characters.

For example:

    ("Hello there!".get 0) --> 72
    ("Hello there!".get 1) --> 101
    ("Hello there!".get 2) --> 108

since 72, 101 and 108 are the ASCII values for H, e and l respectively.

Note that when indexing into a string the initial index is 0 rather than 1

Arguments:

index Integer

Return type: Integer

`hexify`

Surgically update this string, replacing any characters in the supplied string with their hex equivalents. In HTTP, there are only restricted characters which can appear in a URL. For example, to make the string /once more/unto the breach safe to be a URL, use the following:

    (set url "/once more/unto the breach")
    (url.hexify " ")

The modified value of the variable url is now:

    "/once%20more/unto%20the%20breach"

Arguments:

toReplace String

Return type: the empty List () is returned

`dehexify`

This is simply the reverse of the hexify function e.g.

    (set url "/once%20more/unto%20the%20breach")
    (url.dehexify)

The modified value of the variable url is now:

    "/once more/unto the breach"

Arguments: none

Return type: the empty List () is returned

`htmlRow`

Turn this string into a row for an HTML table, where each table cell contains a single character. Note that the space character (ASCII 32) is converted into an HTML non-breaking space ie.  

For example

    ("a b".htmlRow) --> "<tr><td>a</td><td>&nbsp;</td><td>b</td></tr>"

Arguments: none

Return type: String

`digest`

Create the MD5 digest (see RFC 1321) for the string. This is returned as a Binary item of length 16.

Arguments: none

Return type: Binary

`hash`

Scalculate a simple hash of the string given the supplied modulo. The integer returned is greater than or equal to zero and less than the modulo.

Arguments:

modulo Integer

Return type: Integer

`base64`

Encode/decode this data using the Base 64 (MIME RFC 2045) encoding scheme.

With no arguments, this string data is assumed to be base64 encoded and the decoded result is returned.

If a lineLength is supplied, then the result of base64 encoding this data is returned. A lineLength of -1 ensures that no new-lines or carriage-returns are inserted into the encoded data. Otherwise, the lineLength must be a multiple of 4.

Arguments:

lineLength - optional Integer

Return type: String

`quotedPrintable`

Encode/decode this data using the quoted-printable (MIME RFC 2045) encoding scheme.

With no arguments, this string data is assumed to be quoted-printable encoded and the decoded result is returned.

If an argument is supplied, then the result of the lineLength decoding this data is returned.

Arguments:

flag - optional Object

Return type: String

Contents

Index

Current topic: objects