# Reserved objects

This chapter is a reference of the reserved objects with their respective builtin methods. The reserved objects are those objects defined in the global interpreter nameset and bind as reserved names.

All literal have a string representation. The `to-string` method is always available for these reserved objects. A literal object has a default constructor. Generally, it can also be constructed by a same type object or by a string object.

Literal

The `Literal` object is a base object for all literal object. The sole purpose of a literal object is to provide to methods named `to-string` and `to-literal` that return a string representation of the literal object.

literal-p
Serial
to-string
String
none

The `to-string` method returns a string representation of the literal. The string is expected to represent at best the literal.

to-literal
String
none

The `to-literal` method returns a string representation of the literal. The string differs from the `to-string` method in the sense that the string is a literal representation. For example the literal representation of a string is the quoted string.

Nameable

The `Nameable` object is a base object that support name definition. The sole purpose of a literal object is to provide to method named `get-name` that returns the object name.

nameable-p
Object
get-name
String
none

The `get-name` method returns the associated object name. The object name defined here is a name that the class wishes to associate with the object. For example, the `InputFile` is a nameable class and the name is the file name.

Item

The `Item` reserved object is an enumeration item. The item is bound to an enumeration object. An item object is created during the evaluation of an enumeration object. An enumeration item cannot be constructed directly.

item-p
Literal
==
Boolean
Boolean

The `==` operator returns true if the calling object is equal to the boolean argument.

!=
Boolean
Boolean

The `==` operator returns true if the calling object is not equal to the boolean argument.

get-enum
Enum
none

The `get-enum` method returns the enumeration object bound to the item. The item must be a dynamic item or an exception is thrown.

Boolean

The `Boolean` reserved object implements the behavior of a native boolean type. Two builtin symbols, namely true and false are used to represent the value of a boolean instance. The `Boolean` type is primarily used for test expression.

boolean-p
Literal
Boolean
none

The `Boolean` constructor create a boolean object those default value is false.

Boolean
Boolean

The `Boolean` constructor create a boolean object with the boolean object argument.

Boolean
String

The `Boolean` constructor create a boolean object with the string object argument. The string `"true"` denotes the true value while the string `"false"` denotes the false value.

==
Boolean
Boolean

The `==` operator returns true if the calling object is equal to the boolean argument.

!=
Boolean
Boolean

The `==` operator returns true if the calling object is not equal to the boolean argument.

Number

The `Number` reserved objectis a base class for all number objects. The number base object is used by the `Integer`, `Real` and `Relatif` objects. The class provides essentially the methods needed to format a number.

number-p
Literal
format
String
none|Integer

The `format` method format the calling number instance with a certain number of digits after the decimal point. In the first form without argument, the default formating representation is performed with a null precision. In the second format, a number is represented with a certain precision given by the calling argument.

to-hexa
String
none

The `to-hexa` method returns a signed hexadecimal representation of a number. This method works well with `Integer` and `Relatif` objects.

to-hexa-string
String
none

The `to-hexa-string` method returns a hexadecimal representation of a number without a prefix. The number is always considered positive. This method works well with `Integer` and `Relatif` objects.

Integer

The `Integer` reserved object implements the behavior of a native 64 bits signed integer type. Standard decimal notation is used to construct integer object from a literal. The integer object can also be constructed from a string. Standard operators are provided for this class. The `Integer` object is a literal object derived from the `Number` object.

integer-p
Number
Integer
none

The `Integer` constructor create an integer object those default value is 0.

Integer
Real

The `Integer` constructor create an integer object with the real object argument those value is truncated to an integer value.

Integer
Integer

The `Integer` constructor create an integer object with the integer object argument.

Integer
Character

The `Integer` constructor create an integer object with the character object argument. The character encoding value is used as the integer value.

==
Boolean
Integer|Real

The `==` operator returns true if the calling object is equal to the integer or real argument.

!=
Boolean
Integer|Real

The `!=` operator returns true if the calling object is not equal to the integer or real argument.

+
Integer
Integer|Real

The `+` operator returns the sum of the calling integer with an integer or a real object.

-
Integer
Integer|Real

The `-` operator returns the subtraction of the calling integer with an integer or a real object.

*
Integer
Integer|Real

The `*` operator returns the multiplication of the calling integer with an integer or a real object.

/
Integer
Integer|Real

The `/` operator returns the division of the calling integer with an integer or a real object.

<
Boolean
Integer|Real

The `<` operator returns true if the calling integer is less than the integer or real object.

<=
Boolean
Integer|Real

The `<=` operator returns true if the calling integer is less equal than the integer or real object.

>
Boolean
Integer|Real

The `>` operator returns true if the calling integer is greater than the integer or real object.

>=
Boolean
Integer|Real

The `>=` operator returns true if the calling integer is greater equal than the integer or real object.

++
Integer
Integer|Real

The `++` operator increments the calling integer by 1.

--
Integer
Integer|Real

The `--` operator decrements the calling integer by 1.

+=
Integer
Integer|Real

The `+=` operator add and assign the calling integer with an integer or real argument object.

-=
Integer
Integer|Real

The `-=` operator subtracts and assign the calling integer with an integer or real argument object.

*=
Integer
Integer|Real

The `*=` operator multiply and assign the calling integer with an integer or real argument object.

/=
Integer
Integer|Real

The `/=` operator divide and assign the calling integer with an integer or real argument object.

or
Integer
Integer

The `or` method returns the binary or between the integer and the integer argument.

abs
Integer
none

The `abs` method returns the absolute value of the calling integer instance.

not
Integer
none

The `not` method returns the binary negation of the calling integer instance.

shl
Integer
Integer

The `shl` method returns a new integer corresponding to the calling integer instance shifted left by the integer argument.

shr
Integer
Integer

The `shr` method returns a new integer corresponding to the calling integer instance shifted right by the integer argument.

and
Integer
Integer

The `and` method returns a new integer corresponding to the binary and between the calling integer instance and the integer argument.

xor
Integer
Integer

The `xor` method returns a new integer corresponding to the binary xor between the calling integer instance and the integer argument.

mod
Integer
Integer

The `mod` method returns the modulo between the integer instance and the integer argument. A `type-error` exception is raised if the argument is not an argument.

odd-p
Boolean
none

The `odd-p` method returns true if the integer instance is odd, false otherwise.

even-p
Boolean
none

The `even-p` method returns true if the integer instance is even, false otherwise.

zero-p
Boolean
none

The `zero-p` method returns true if the integer instance is null, false otherwise.

Relatif

The `Relatif` reserved object implements the behavior of an unlimited signed integer type. Standard decimal notation followed by the 'r' or 'R' character is used to construct relatif object from a literal. The relatif object can also be constructed from a string. This class is similar to the `Integer` class. The `Relatif` is a literal object derived from the `Number` object.

relatif-p
Number
Relatif
none

The `Relatif` constructor create a relatif object those default value is 0.

Relatif
Real

The `Relatif` constructor create an relatif object with the real object argument those value is truncated to an integer value.

Relatif
Relatif

The `Relatif` constructor create an relatif object with the relatif object argument.

Relatif
Integer

The `Relatif` constructor create an relatif object with the integer object argument.

Relatif
Character

The `Relatif` constructor create an relatif object with the character object argument. The character encoding value is used as the relatif value.

==
Boolean
Relatif|Integer

The `==` operator returns true if the calling object is equal to the relatif or integer argument.

!=
Boolean
Relatif|Integer

The `==` operator returns true if the calling object is not equal to the relatif or integer argument.

+
Relatif
Relatif|Integer

The `+` operator returns the sum of the calling relatif with an relatif or a integer object.

-
Relatif
Relatif|Integer

The `-` operator returns the subtraction of the calling relatif with an relatif or a integer object.

*
Relatif
Relatif|Integer

The `*` operator returns the multiplication of the calling relatif with an relatif or a integer object.

/
Relatif
Relatif|Integer

The `/` operator returns the division of the calling relatif with an relatif or a integer object.

<
Boolean
Relatif|Integer

The `<` operator returns true if the calling relatif is less than the relatif or integer object.

<=
Boolean
Relatif|Integer

The `<=` operator returns true if the calling relatif is less equal than the relatif or integer object.

>
Boolean
Relatif|Integer

The `>` operator returns true if the calling relatif is greater than the relatif or integer object.

>=
Boolean
Relatif|Integer

The `>=` operator returns true if the calling relatif is greater equal than the relatif or integer object.

++
Relatif
Relatif|Integer

The `++` operator increments the calling relatif by 1.

--
Relatif
Relatif|Integer

The `--` operator decrements the calling relatif by 1.

+=
Relatif
Relatif|Integer

The `+=` operator add and assign the calling relatif with an relatif or integer argument object.

-=
Relatif
Relatif|Integer

The `-=` operator subtracts and assign the calling relatif with an relatif or integer argument object.

*=
Relatif
Relatif|Integer

The `*=` operator multiply and assign the calling relatif with an relatif or integer argument object.

/=
Relatif
Relatif|Integer

The `/=` operator divide and assign the calling relatif with an relatif or integer argument object.

or
Relatif
Relatif

The `or` method returns the binary or between the relatif and the relatif argument.

abs
Relatif
none

The `abs` method returns the absolute value of the calling relatif instance.

not
Relatif
none

The `not` method returns the binary negation of the calling relatif instance.

shl
Relatif
Integer

The `shl` method returns a new relatif corresponding to the calling relatif instance shifted left by the integer argument.

shr
Relatif
Integer

The `shr` method returns a new relatif corresponding to the calling relatif instance shifted right by the integer argument.

pow
Relatif
Integer|Relatif|Integer Integer|Relatif Relatif

The `pow` method returns a new relatif corresponding to the power of the calling relatif instance with the integer or relatif argument. With one argument, the power is computed directly. With two arguments, a fast modular exponentiation is performed with the second argument as the modulus.

mmi
Relatif
Integer|Relatif

The `mmi` method returns the multiplicative modular inverse of the calling relatif. The argument is the modulus to use for the inverse calculation.

and
Relatif
Relatif

The `and` method returns a new relatif corresponding to the binary and between the calling relatif instance and the relatif argument.

xor
Relatif
Relatif

The `xor` method returns a new relatif corresponding to the binary xor between the calling relatif instance and the relatif argument.

mod
Relatif
Relatif|Integer

The `mod` method returns the modulo between the relatif instance and the relatif or integer argument. A `type-error` exception is raised if the argument is invalid.

odd-p
Boolean
none

The `odd-p` method returns true if the relatif instance is odd, false otherwise.

even-p
Boolean
none

The `even-p` method returns true if the relatif instance is even, false otherwise.

zero-p
Boolean
none

The `zero-p` method returns true if the relatif instance is null, false otherwise.

get-msb
Integer
none

The `get-msb` method returns the most significnd bit position for the calling relatif. If the number is null, 0 is returned. The msb position is thus counted from 1.

Real

The `Real` reserved object implements the behavior of a double floating point number type. Standard decimal dot notation or scientific notation is used to construct real object from a literal. The real object can also be constructed from an integer, a character or a string. The `Real` object is a literal object derived from the `Number` object.

real-p
Number
Real
none

The `Real` constructor create an real object those default value is 0.0.

Real
Real

The `Real` constructor create an real object with the real object argument.

Real
Integer

The `Real` constructor create an real object with the integer object argument.

Real
Character

The `Real` constructor create an real object with the character object argument. The character encoding value is used as the integer value.

==
Boolean
Integer|Real

The `==` operator returns true if the calling object is equal to the integer or real argument.

!=
Boolean
Integer|Real

The `==` operator returns true if the calling object is not equal to the integer or real argument.

+
Real
Integer|Real

The `+` operator returns the sum of the calling real with an integer or a real object.

-
Real
Integer|Real

The `-` operator returns the subtraction of the calling real with an integer or a real object.

*
Real
Integer|Real

The `*` operator returns the multiplication of the calling real with an integer or a real object.

/
Real
Integer|Real

The `/` operator returns the division of the calling real with an integer or a real object.

<
Boolean
Integer|Real

The `<` operator returns true if the calling real is less than the integer or real object.

<=
Boolean
Integer|Real

The `<=` operator returns true if the calling real is less equal than the integer or real object.

>
Boolean
Integer|Real

The `>` operator returns true if the calling real is greater than the integer or real object.

>=
Boolean
Integer|Real

The `>=` operator returns true if the calling real is greater equal than the integer or real object.

++
Real
Integer|Real

The `++` operator increments the calling real by 1.

--
Real
Integer|Real

The `--` operator decrements the calling real by 1.

+=
Real
Integer|Real

The `+=` operator add and assign the calling real with an integer or real argument object.

-=
Real
Integer|Real

The `-=` operator subtracts and assign the calling real with an integer or real argument object.

*=
Real
Integer|Real

The `*=` operator multiply and assign the calling real with an integer or real argument object.

/=
Real
Integer|Real

The `+=` operator divide and assign the calling real with an integer or real argument object.

nan-p
Boolean
none

The `nan-p` method returns true if the calling real number instance is not-a-number (nan).

ceiling
Real
none

The `ceiling` method returns the ceiling of the calling real number instance.

floor
Real
none

The `floor` method returns the floor of the calling real number instance.

abs
Real
none

The `abs` method returns the absolute value of the calling real number instance.

pow
Real
Real|Integer

The `pow` method returns the power of the calling real with the argument. The exponent argument can be either an integer or a real number.

sqrt
Real
none

The `sqrt` method returns the square root of the calling real number instance.

log
Real
none

The `log` method returns the natural logarithm of the calling real number instance.

exp
Real
none

The `exp` method returns the exponential of the calling real number instance.

sin
Real
none

The `sin` method returns the sine of the calling floating point instance. The angle is expressed in radian.

cos
Real
none

The `cos` method returns the cosine of the calling floating point instance. The angle is expressed in radian.

tan
Real
none

The `tan` method returns the tangent of the calling floating point instance. The angle is expressed in radian.

asin
Real
none

The `asin` method returns the arc sine of the calling floating point instance. The result is in radian.

acos
Real
none

The `acos` method returns the arc cosine of the calling floating point instance. The result is in radian.

atan
Real
none

The `atan` method returns the arc tangent of the calling floating point instance. The result is in radian.

sinh
Real
none

The `sinh` method returns the hyperbolic sine of the calling real number instance.

cosh
Real
none

The `cosh` method returns the hyperbolic cosine of the calling real number instance.

tanh
Real
none

The `atan` method returns the hyperbolic tangent of the calling real number instance.

asinh
Real
none

The `asinh` method returns the hyperbolic arc sine of the calling real number instance.

acosh
Real
none

The `acosh` method returns the hyperbolic arc cosine of the calling real number instance.

atanh
Real
none

The `atanh` method returns the hyperbolic arc tangent of the calling real number instance.

zero-p
Boolean
none

The `zero-p` method returns true if the calling real instance is null, false otherwise.

Character

The `Character` reserved object implements the behavior of an Unicode character type. A character can be constructed from a literal quoted notation, with a string or with the `U+` hexadecimal notation. The character class is designed to handle the full range of the Unicode character space by using an internal 32 bit quad representation with 31 bit valid. The `Character` class conform also with the ISO 10646 character representation.

character-p
Literal
Character
none

The `Character` constructor create a character object those default value is the null character.

Character
String

The `Character` constructor create a character object with the string object argument.

Character
Integer

The `Character` constructor create a character object with the integer object argument.

Character
Character

The `Character` constructor create a character object with the character object argument.

==
Boolean
Character

The `==` operator returns true if the calling object is equal to the character argument.

!=
Boolean
Character

The `!=` operator returns true if the calling object is not equal to the character argument.

<
Boolean
Character

The `<` operator returns true if the calling character is less than the character object.

<=
Boolean
Character

The `<=` operator returns true if the calling character is less equal than the character object.

>
Boolean
Character

The `>` operator returns true if the calling character is greater than the character object.

>=
Boolean
Character

The `>=` operator returns true if the calling character is greater equal than the character object.

++
Character
Character

The `++` operator increments the calling character by the next one in lexicographic order.

--
Character
Character

The `--` operator decrements the calling character by the previous one in lexicographic order.

+=
Character
Integer

The `+=` operator add the integer argument to the calling character.

-=
Character
Integer

The `-=` operator subtracts the integer argument to the calling character.

letter-p
Boolean
none

The `letter-p` predicate returns true if the character is a letter character, `false` otherwise.

digit-p
Boolean
none

The `digit-p` predicate returns true if the character is a digit character, false otherwise.

alpha-p
Boolean
none

The `alpha-p` predicate returns true if the character is an alphanumeric character, `false` otherwise.

blank-p
Boolean
none

The `blank-p` predicate returns true if the character is a blank or tab character, false otherwise.

eol-p
Boolean
none

The `eol-p` predicate returns true if the character is an end-of-line character, false otherwise.

eos-p
Boolean
none

The `eos-p` predicate returns true if the character is an end-of-stream character, false otherwise.

nil-p
Boolean
none

The `nil-p` predicate returns true if the character is the nil character, false otherwise.

to-integer
Integer
none

The `to-integer` method returns an integer representation of the characters.

Byte

The `Byte` reserved object implements the behavior of an 8 bit character type. A byte can be constructed from a integer or from another byte. The `Byte` class is similar to the `Character` class but is not a literal object because it does not have a literal representation. Most of the time, a byte object is created by another object like a stream, when using the `read` method for example.

byte-p
Serial
Byte
none

The `Byte` constructor create a byte object those default value is the null byte.

Byte
Integer

The `Byte` constructor create a byte object with the integer object argument. The integer value must be in the range of 0x00 to 0xFF.

Byte
Byte

The `Byte` constructor create a byte object with the byte object argument.

==
Boolean
Byte

The `==` operator returns true if the calling object is equal to the byte argument.

!=
Boolean
Byte

The `!=` operator returns true if the calling object is not equal to the byte argument.

<
Boolean
Byte

The `<` operator returns true if the calling byte is less than the byte object.

<=
Boolean
Byte

The `<=` operator returns true if the calling byte is less equal than the byte object.

>
Boolean
Byte

The `>` operator returns true if the calling byte is greater than the byte object.

>=
Boolean
Byte

The `>=` operator returns true if the calling byte is greater equal than the byte object.

++
Byte
Byte

The `++` operator increments the calling byte by one.

--
Byte
Byte

The `--` operator decrements the calling byte by one.

+=
Byte
Integer

The `+=` operator adds the integer argument to the calling byte.

-=
Byte
Integer

The `-=` operator subtracts the integer argument to the calling byte.

eos-p
Boolean
none

The `eos-p` predicate returns true if the character is an end-of-stream character, false otherwise.

nil-p
Boolean
none

The `nil-p` predicate returns true if the byte is the nil byte, false otherwise.

to-integer
Integer
none

The `to-integer` method returns an integer representation of the byte.

to-char
Character
none

The `to-char` method returns a character representing the byte.

String

The `String` reserved object implements the behavior of an internal character array. The double quote notation is the literal notation for a string. A string can also be constructed from the standard objects. Strings can be compared, transformed or extracted with the help of the methods listed below. Internally, the string is represented as an array of Unicode characters.

string-p
Literal
String
none

The `String` constructor create a string object those default value is the null string.

String
Literal

The `String` constructor create a string object with the literal object argument.

==
Boolean
String

The `==` operator returns true if the calling object is equal to the string argument.

!=
Boolean
String

The `!=` operator returns true if the calling object is not equal to the string argument.

<
Boolean
String

The `<` operator returns true if the calling string is less than the string argument.

<=
Boolean
String

The `<=` operator returns true if the calling string is less equal than the string argument.

>
Boolean
String

The `>` operator returns true if the calling string is greater than the string argument.

>=
Boolean
String

The `>=` operator returns true if the calling string is greater equal than the string argument.

+
String
String

The `+` operator returns the sum of the calling string with an string object.

+=
String
String

The `+=` operator add and assign the calling string with the string argument.

length
Integer
none

The `length` method returns the length of the string.

first
Character
none

The `first` method returns the first character in the string.

last
Character
none

The `last` method returns the last character in the string.

strip-left
String
none|String

The `strip-left` method removes the leading blanks and tabs and returns a new string. With a string argument, each character in the string is taken as a character separator that should be stripped.

strip-right
String
none|String

The `strip-right` method removes the trailing blanks and tabs and returns a new string.With a string argument, each character in the string is taken as a character separator that should be stripped.

strip
String
none|String

The `strip` method removes the leading, trailing blanks and tabs and returns a new string. With a string argument, each character in the string is taken as a character separator that should be stripped.

split
Vector
none|String

The `split` method split the string into one or more string according to break sequence. If no argument is passed to the call, the break sequence is assumed to be a blank, tab and eol characters.

extract
Vector
Character

The `extract` method extracts one or more string which are enclosed by a control character passed as an argument. The method returns a vector of strings.

to-upper
String
none

The `to-upper` converts all string characters to upper case and returns a new string.

to-lower
String
none

The `to-lower` method converts all string characters to lower case and returns a new string.

get
Character
Integer

The `get` method returns a the string character at the position given by the argument. If the index is invalid, an exception is raised.

sub-left
String
Integer

The `sub-left` method returns the left sub string of the calling string up-to the argument index. If the index is out of range, the string is returned.

sub-right
String
Integer

The `sub-right` method returns the right sub string of the calling string starting at the argument index. If the index is out of range, the string is returned.

fill-left
String
Character Integer

The `fill-left` method returns a string filled on the left with the character argument. The second argument is the desired length of the resulting string. If the calling is too long, the string is returned.

fill-right
String
Character Integer

The `fill-left` method returns a string filled on the right with the character argument. The second argument is the desired length of the resulting string. If the calling is too long, the string is returned.

substr
String
Integer Integer

The `substr` method returns a string starting at the first argument index and ending at the second argument index. If the indexes are out of range, an exception is raised.

Regex

The `Regex` object is a special object which is automatically instantiated by the interpreter when using the delimiter character `[` and `]`. The regex syntax involves the use of standard characters, meta characters and control characters. Additionally, a string can be use to specify a series of characters.

In its first form, the `[` and `]` characters are used as syntax delimiters. The lexical analyzer automatically recognizes this token as a regex and built the equivalent `Regex` object. The second form is the explicit construction of the `Regex` object. Note also that the `[` and `]` characters are also used as regex block delimiters.

Any character, except the one used as operators can be used in a regex. The `$` character is used as a meta-character -- or control character -- to represent a particular set of characters. For example, `[hello world]` is a regex which match only the `"hello world"` string. The `[$d+]` regex matches one or more digits. The following control characters are builtin in the regex engine.

## Regular expression meta-characters

Character | Description
--- | ---
$a | matches any letter or digit
$b | matches any blank characters
$c | matches any combining characters
$d | matches any digit
$e | matches eol, cr and eos
$l | matches any lower case letter
$n | matches eol or cr
$s | matches any letter
$u | matches any upper case letter
$v | matches any valid constituent
$w | matches any word constituent
$x | matches any hexadecimal characters

The uppercase version is the complement of the corresponding lowercase character set. A character which follows a `$` character and that is not a meta character is treated as a normal character. For example `$[` is the `[` character. A quoted string can be used to define character matching which could otherwise be interpreted as control characters or operator. A quoted string also interprets standard escaped sequences but not meta characters.

## Regular expression meta-characters complement

Character | Description
--- | ---
$A | any character except letter or digit
$B | any character except blank characters
$C | any character except combining characters
$D | any character except digit
$E | any character except eol, cr and eos
$L | any character except lower case letter
$N | any character except eol or cr
$S | any character except letter
$U | any character except upper case letter
$V | any character except constituent
$W | any character except word constituent
$X | any character except hex characters

A character set is defined with the `<` and `>` characters. Any enclosed character defines a character set. Note that meta characters are also interpreted inside a character set. For example, `<$d+->` represents any digit or a plus or minus. If the first character is the `^` character in the character set, the character set is complemented with regards to its definition.

The following unary operators can be used with single character, control characters and sub-expressions.

## Regular expression operators

Operator | Description
--- | ---
* | match 0 or more times
+ | match 1 or more times
? | match 0 or 1 time
| | alternation

Alternation is an operator which work with a secondary expression. Care should be taken when writing the right sub-expression. For example the following regex `[$d|hello]` is equivalent to `[[$d|h]ello]`. In other word, the minimal first sub-expression is used when compiling the regex.

regex-p
Literal
Regex
none

The `Regex` constructor create a regex object those default value is the null regex.

Regex
String

The `Regex` constructor create a regex object with the string object argument. The string argument is the regex specification.

==
Boolean
String

The `==` operator returns true if the argument is matched by the regex.

!=
Boolean
String

The `!=` operator returns true if the argument is not matched by the regex.

<
Boolean
String

The `<` operator returns true if the argument is partially matched by the regex.

length
Integer
none

The `length` method returns the length of the group vector when a regex match has been successful.

get
String
Integer

The `get` method returns by index the group sub-string when a regex match has been successful.

match
String
String

The `match` method returns the first matching string of the argument string.

replace
String
String String

The `replace` method returns a string constructed by replacing all matching sub-string -- from the first argument -- with the second argument string.