/* Copyright (C) 2003-2013 Runtime Revolution 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>"

// 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 precedence 2
    <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 precedence 2
    <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 precedence 1
    "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 precedence 1
    "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 precedence 7
    <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 precedence 7
    <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 precedence 5
    <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 precedence 5
    <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
