/* Copyright (C) 2003-2015 LiveCode Ltd.

This file is part of LiveCode.

LiveCode is free software; you can redistribute it and/or modify it under

the terms of the GNU General Public License v3 as published by the Free

Software Foundation.

LiveCode is distributed in the hope that it will be useful, but WITHOUT ANY

WARRANTY; without even the implied warranty of MERCHANTABILITY or

FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License

for more details.

You should have received a copy of the GNU General Public License

along with LiveCode. If not see <http://www.gnu.org/licenses/>. */

/**

This library consists of the operations on strings included in the standard library of LiveCode Builder.

*/

module com.livecode.string

use com.livecode.foreign

public foreign handler MCStringExecPutStringBefore(in Source as String, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCStringExecPutStringAfter(in Source as String, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCStringExecReplace(in Pattern as String, in Replacement as String, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalConcatenate(in Left as String, in Right as String, out Result as String) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalConcatenateWithSpace(in Left as String, in Right as String, out Result as String) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalLowercaseOf(in Source as String, out Result as String) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalUppercaseOf(in Source as String, out Result as String) returns nothing binds to "<builtin>"

/* No implementation

// The following all need some notion of context

public foreign handler MCStringEvalBeginsWith(in Source as String, in Prefix as String, out Result as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalEndsWith(in Source as String, in Suffix as String, out Result as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalOffset(in Needle as String, in Source as String, out Result as LCIndex) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalOffsetAfter(in Needle as String, in After as LCIndex, in Source as String, out Result as LCIndex) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalLastOffset(in Needle as String, in Source as String, out Result as LCIndex) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalLastOffsetBefore(in Needle as String, in Before as LCIndex, in Source as String, out Result as LCIndex) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalContainsChars(in Source as String, in Needle as String, out Result as CBool) returns nothing binds to "<builtin>"

*/

public foreign handler MCStringEvalIsEqualTo(in Left as String, in Right as String, out Value as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalIsNotEqualTo(in Left as String, in Right as String, out Value as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalIsLessThan(in Left as String, in Right as String, out Value as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalIsGreaterThan(in Left as String, in Right as String, out Value as CBool) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalEmpty(out Value as String) returns nothing binds to "<builtin>"

--

/**

Summary: Prepends <Source> to <Target>.

Source: An expression which evaluates to a string.

Target: An expression which evaluates to a string container.

Example:

variable tVar as String

put "" into tVar

put "abc" before tVar -- tVar contains "abc"

put "lpha" before char 2 of tVar

put "eti" before char -1 of tVar -- tVar contains "alphabetic"

Description:

Use to insert a string without replacement. Can be used either with a chunk expression to insert at a specified location, or without to prepend to the target string.

Tags: Strings

*/

syntax PutStringBefore is statement

"put" <Source: Expression> "before" <Target: Expression>

begin

MCStringExecPutStringBefore(Source, Target)

end syntax

/**

Summary: Appends <Source> to <Target>.

Source: An expression which evaluates to a string.

Target: An expression which evaluates to a string container.

Example:

variable tVar as String

put "" into tVar

put "rent" after tVar -- tVar contains "rent"

put "placeme" after char 2 of tVar -- tVar contains "replacement"

Description:

Use to insert a string without replacement. Can be used either with a chunk expression to insert at a specified location, or without to append to the target string.

Tags: Strings

*/

syntax PutStringAfter is statement

"put" <Source: Expression> "after" <Target: Expression>

begin

MCStringExecPutStringAfter(Source, Target)

end syntax

--

/**

Summary: Replaces occurrences of <Pattern> within <Target> in <Replacement>

Source: An expression which evaluates to a string.

Target: An expression which evaluates to a string container.

Replacement: An expression which evaluates to a string.

Example:

variable tString as String

put "purple" into tString

replace "p" with "t" in tString -- tString is "turtle"

Description:

Replaces each occurrence of the string <Pattern> in <Target> with <Replacement>.

Tags: Strings

*/

syntax ReplaceString is statement

"replace" <Pattern: Expression> "with" <Replacement: Expression> "in" <Target: Expression>

begin

MCStringExecReplace(Pattern, Replacement, Target)

end syntax

--

/**

Summary: Concatenates <Left> and <Right>.

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: The result of concatenating <Left> and <Right>.

Example:

variable tVar as String

put "car" & "pet" into tVar -- tVar contains "carpet"

Description:

The result consists of the chars of <Left> followed by those of <Right>.

Tags: Strings

*/

syntax ConcatenateStrings is left binary operator with concatenation precedence

<Left: Expression> "&" <Right: Expression>

begin

MCStringEvalConcatenate(Left, Right, output)

end syntax

/**

Summary: Concatenates <Left> and <Right> with a space between.

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: The result of concatenating <Left> and <Right> with a space between.

Example:

variable tVar as String

put "This" && "is" && "a" && "sentence." into tVar -- tVar contains "This is a sentence."

Description:

The result consists of the chars of <Left> followed by a space, and then the chars of <Right>.

Tags: Strings

*/

syntax ConcatenateStringsWithSpace is left binary operator with concatenation precedence

<Left: Expression> "&&" <Right: Expression>

begin

MCStringEvalConcatenateWithSpace(Left, Right, output)

end syntax

--

/**

Summary: Uppercases <Source>.

Source: An expression which evaluates to a string.

Returns: <Source> with each of its chars uppercased.

Description:

Lowercase letters, including special characters with diacritical marks, are converted to the uppercase equivalents. All other characters, including uppercase letters, numbers, punctuation, and special characters with no upper or lower case, are left unchanged.

Tags: Strings

*/

syntax UppercaseString is prefix operator with function chunk precedence

"the" "upper" "of" <Source: Expression>

begin

MCStringEvalUppercaseOf(Source, output)

end syntax

/**

Summary: Lowercases <Source>.

Source: An expression which evaluates to a string.

Returns: <Source> with each of its chars lowercased.

Description:

Uppercase letters, including special characters with diacritical marks, are converted to the lowercase equivalents. All other characters, including lowercase letters, numbers, punctuation, and special characters with no upper or lower case, are left unchanged.

Tags: Strings

*/

syntax LowercaseString is prefix operator with function chunk precedence

"the" "lower" "of" <Source: Expression>

begin

MCStringEvalLowercaseOf(Source, output)

end syntax

--

/**

Summary: Determines whether <Left> and <Right> are equal or not.

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: Returns true if <Left> is identical to <Right>.

Description:

The ```is``` operator is case sensitive.

Tags: Strings

*/

syntax StringIsString is neutral binary operator with comparison precedence

<Left: Expression> "is" <Right: Expression>

begin

MCStringEvalIsEqualTo(Left, Right, output)

end syntax

/**

Summary: Determines whether <Left> and <Right> are equal or not.

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: Returns true if <Left> is not identical to <Right>.

Description:

The ```is not``` operator is case sensitive.

Tags: Strings

*/

syntax StringIsNotString is neutral binary operator with comparison precedence

<Left: Expression> "is not" <Right: Expression>

begin

MCStringEvalIsNotEqualTo(Left, Right, output)

end syntax

/**

Summary: Determines whether <Left> is less than <Right> under a char by char comparison

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: Returns true if <Left> is less than <Right>

Description:

<Left> is greater than <Right> if and only if <Left> and <Right> are not equal, and the unicode codepoint of the first char in <Left> that is not equal to the corresponding char in <Right> is of greater value.

Tags: Strings

*/

syntax StringIsLessThanString is neutral binary operator with comparison precedence

<Left: Expression> "<" <Right: Expression>

begin

MCStringEvalIsLessThan(Left, Right, output)

end syntax

/**

Summary: Determines whether <Left> is greater than <Right> under a char by char comparison

Left: An expression which evaluates to a string.

Right: An expression which evaluates to a string.

Returns: Returns true if <Left> is greater than <Right>.

Description:

<Left> is greater than <Right> if and only if <Left> and <Right> are not equal, and the unicode codepoint of the first char in <Left> that is not equal to the corresponding char in <Right> is of greater value.

Tags: Strings

*/

syntax StringIsGreaterThanString is neutral binary operator with comparison precedence

<Left: Expression> ">" <Right: Expression>

begin

MCStringEvalIsGreaterThan(Left, Right, output)

end syntax

--

/**

Summary: Designates the string of length zero.

Example:

variable tVar as String

variable tCount as Number

put the empty string into tVar

put the number of chars in tVar into tCount -- tCount is 0

Description:

Use ```the empty string``` to initialise a string variable. The empty string is synonymous with the string literal ""

Tags: Strings

*/

syntax EmptyString is expression

"the" "empty" "string"

begin

MCStringEvalEmpty(output)

end syntax

end module