Strings

method s '' position -> c arg Str s ; arg Int position ; arg_C Char c

maps one character of the string.
In a string, the first character's position is zero.

An example:

var Str s := "abc" s 1 := "B" console s eol

would display 'aBc'

method s len -> l arg Str s ; arg Int l

return the lenth of the string.

method s '' first maximum -> sub arg Str s ; arg Int first maximum ; arg Str sub

returns the substring of 's' that starts at character with position 'first' and constains 'maximum' characters.
'first' must be positive but can be greater than the string length.
'maximum' must also be positive. If less that 'maximum' characters are available starting form 'first' position, the returned string will truncated, but it's ok.

method s search pattern if_not_found -> position arg Str s pattern ; arg Int if_not_found position method s search_last pattern if_not_found -> position arg Str s pattern ; arg Int if_not_found position

searches for the first (or last) occurrence of 'pattern' and returns its position.
if 'pattern' was not found, then 'if_not_found' is return instead.

function replace original pattern with -> changed arg Str original pattern with changed

replaces all the occurrences of 'pattern' in 'original' by 'with'.

function repeat times pattern -> repeted arg Int times ; arg Str pattern repeted

repeats 'pattern' 'times' times.

function left original minimal_length pattern -> aligned arg Str original ; Int length ; arg Str pattern aligned

if 'original' length is greater or equal than 'minimal_length', then 'original' is returned unmodified,
elsewhere 'original' length is extended to 'minimal_length' by repeating 'pattern' at the end of the string.
Please notice that 'pattern' length must be 1.

function right original minimal_length pattern -> aligned arg Str original ; Int length ; arg Str pattern aligned

same, but 'pattern' is repeated at the beginning of the string.

function upper original -> upper_cased arg Str original upper_cased function lower original -> lower_cased arg Str original lower_cased

Returns a copy of 'original' where all unaccented characters have been turned to upper case (or lower case).

method string parse ... -> matching arg Str string ; arg CBool matching method string eparse ... -> matching arg Str string ; arg CBool matching

Tests if the string matches the given pattern.
If 'parse' is used, the spaces or tabulations between the recognized items are removed, whereas they are not if 'eparse' is used.

The following elements may appear in the pattern:

"a_pattern"	expects to find the extact sequence a_pattern next
pattern:a_string_value	idem
word:a_string_value	idem, but the pattern must be a full word in the string; it means that it must not be preceded or followed by a a..z A..Z 0..9 or _ character
any	what ever we find next will be discarded
any:string_variable	what ever we find next will be stored in 'string_variable'
variable	expect to find something compatible with the type of the variable next, and store it in the variable
_	expect to find some spaces or tabulations next (at least one)
spaces:string_variable	if there are spaces and tabulations next, they will be stored in the variable
offset:integer_variable	While parsing the string, the 'parse' and 'eparse' functions use a cursor that will forward in the string. This enables you to get the value of the cursor at a given point of the parsing process.

This is an example:

var Str a := "abc def 12" var Str s ; var Int i if (a parse "abc" any:s i) console "s = " s eol console "i = " i eol

Since Pliant is perfectly orthogonal, you can also write it as:

if ("abc def 12" parse "abc" any:(var Str s) (var Int i)) console "s = " s eol console "i = " i eol

A string variable, if not put in an 'any' statement, is expected to be encoded with double quotes:

if ("abc [dq]def[dq] 12" parse "abc" (var Str s) (var Int i)) console "s = " s eol console "i = " i eol

function string data [options] -> str arg Universal data ; arg Str options str

Converts the value of the data to a string.

This is only possible if the 'to string' generic method is defined for data type.
Please notice that:

console string:"abc" eol

will display

"abc"

not

abc

Moreover, some special characters in 'original' are replaced by bracketed sequences as listed below:

original character	replacement sequence
[	[lb]
]	[rb]
"	[dq]
character zero	[0]
carriage return	[cr]
line feed	[lf]

So the quoted string may be used in an ascii file without any trouble whatever special character the original string may contain.

requires to include module "/pliant/language/unsafe.pli"

method s characters -> adr arg Str s ; arg address adr

returns the address of the string characters.

method s set characters length allocated arg Str s ; arg address characters ; arg Int length ; arg CBool allocated

sets the string value.
If 'allocated' is true, then the 'characters' area has been allocated using 'memory_allocate' function, whereas if 'allocated' is false, then 'characters' is pointing to an area belonging to another object.