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.