/* 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 chars included in the standard library of LiveCode Builder.
*/

module com.livecode.char

use com.livecode.foreign

public foreign handler MCCharFetchCharOf(in Index as LCIndex, in Target as String, out Value as String) returns nothing binds to "<builtin>"
public foreign handler MCCharStoreCharOf(in Value as String, in Index as LCIndex, inout Target as String) returns nothing binds to "<builtin>"
public foreign handler MCCharFetchCharRangeOf(in Start as LCIndex, in Finish as LCIndex, in Target as String, out Value as String) returns nothing binds to "<builtin>"
public foreign handler MCCharStoreCharRangeOf(in Value as String, in Start as LCIndex, in Finish as LCIndex, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCCharEvalNumberOfCharsIn(in Target as String, out Count as LCIndex) returns nothing binds to "<builtin>"

public foreign handler MCCharEvalIsAmongTheCharsOf(in Needle as String, in Target as String, out Value as CBool) returns nothing binds to "<builtin>"

/* No implementation
public foreign handler MCCharStoreBeforeCharOf(in Value as String, in Index as LCIndex, inout Target as String) returns nothing binds to "<builtin>"
public foreign handler MCCharStoreAfterCharOf(in Value as String, in Index as LCIndex, inout Target as String) returns nothing binds to "<builtin>"
*/

public foreign handler MCCharEvalOffsetOfChars(in IsLast as CBool, in Needle as String, in Target as String, out Offset as LCUIndex) returns nothing binds to "<builtin>"
public foreign handler MCCharEvalOffsetOfCharsBefore(in IsLast as CBool, in Needle as String, in Before as LCIndex, in Target as String, out Offset as LCUIndex) returns nothing binds to "<builtin>"
public foreign handler MCCharEvalOffsetOfCharsAfter(in IsFirst as CBool, in Needle as String, in After as LCIndex, in Target as String, out Offset as LCUIndex) returns nothing binds to "<builtin>"

public foreign handler MCCharEvalContains(in Source as String, in Needle as String, out Result as CBool) returns nothing binds to "<builtin>"
public foreign handler MCCharEvalBeginsWith(in Source as String, in Prefix as String, out Result as CBool) returns nothing binds to "<builtin>"
public foreign handler MCCharEvalEndsWith(in Source as String, in Suffix as String, out Result as CBool) returns nothing binds to "<builtin>"

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

public foreign handler MCCharRepeatForEachChar(inout Iterator as optional Pointer, out Iterand as String, in Container as String) returns CBool binds to "<builtin>"

public foreign handler MCCharFetchFirstCharOf(in Target as String, out Value as String) returns nothing binds to "<builtin>"
public foreign handler MCCharStoreFirstCharOf(in Value as String, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCCharFetchLastCharOf(in Target as String, out Value as String) returns nothing binds to "<builtin>"
public foreign handler MCCharStoreLastCharOf(in Value as String, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCCharExecDeleteCharOf(in Index as LCIndex, inout Target as String) returns nothing binds to "<builtin>"
public foreign handler MCCharExecDeleteCharRangeOf(in Start as LCIndex, in Finish as LCIndex, inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCCharExecDeleteLastCharOf(inout Target as String) returns nothing binds to "<builtin>"
public foreign handler MCCharExecDeleteFirstCharOf(inout Target as String) returns nothing binds to "<builtin>"

public foreign handler MCStringEvalCodeOfChar(in pChar as String, out pCode as LCUInt) returns nothing binds to "<builtin>"
public foreign handler MCStringEvalCharWithCode(in pCode as LCUInt, out pChar as String) returns nothing binds to "<builtin>"

--

/**
Summary:            Counts the number of chars in <Target>.

Target: 			An expression which evaluates to a string.

Returns:			The number of chars in <Target>.

Example: 			

	variable tVar as Number
	variable tSource as String
	put "hello" into tString
	put the number of chars in tString into tVar
	
	variable tString as String
	put the empty string into tString	
	repeat tVar times
		put "a" after tString
	end repeat
	
	// tString contains "aaaaa"
	
Description:
>*Note:* The number of chars returns the number of codeunits of the target string. It does not perform any grapheme boundary analysis.

Tags: Strings
*/

syntax CountCharsOf is prefix operator with function chunk precedence
	"the" "number" "of" "chars" "in" <Target: Expression>
begin
	MCCharEvalNumberOfCharsIn(Target, output)
end syntax

--

/**
Summary:            Designates the char at index <Index> in <Target>.
Index: 				An expression which evaluates to a valid integer index of <Target>.
Target:				An expression which evaluates to a string.           

Example: 			put the empty string into char 5 of tString // Locates char 5 and removes it from tString
Example: 			get char 5 of tString // Evaluates char 5

Description:
Either locates the char at the given index for use as the target container of another operation, or evaluates the char at the given index as the source of another operation.

>*Note:* It is an error if <Index> is out of range.

Tags: Strings
*/

syntax SingletonCharOf is prefix operator with subscript chunk precedence
	"char" <Index: Expression> "of" <Target: Expression>
begin
	MCCharFetchCharOf(Index, Target, output)
	MCCharStoreCharOf(input, Index, Target)
end syntax

/**
Summary:            Designates the chars between indices <Start> and <Finish> in <Target>.

Start:              An expression which evaluates to a valid integer index of <Target>.
Finish:             An expression which evaluates to a valid integer index of <Target>.
Target:             An expression which evaluates to a string.        
                    
Example: 			put tChars into char 5 to 10 of tString // Locates chars 5 to 10 of tString and replace them with tChars
Example: 			get char 5 to 10 of tString // Evaluates chars 5 to 10

Description:
Either locates the chars between the given indices for use as the target container of another operation, or evaluates the chars at the given indices as the source of another operation.

>*Note:* It is an error if either <Start> or <Finish> are out of range.

Tags: Strings
*/

syntax RangeCharOf is prefix operator with subscript chunk precedence
	"char" <Start: Expression> "to" <Finish: Expression> "of" <Target: Expression>
begin
	MCCharFetchCharRangeOf(Start, Finish, Target, output)
	MCCharStoreCharRangeOf(input, Start, Finish, Target)
end syntax

/**
Summary:            Designates the first char in <Target>.
Target:				An expression which evaluates to a string.

Example:
	variable tVar as String
	put "char" into tVar
	
	variable tFirst as String
	put the first char of tVar into tFirst -- tFirst contains "c"

Description:
Either locates the first char for use as the target container of another operation, or evaluates the first char as the source of another operation.

>*Note:* It is an error if <Target> is empty.

Tags: Strings
*/

syntax FirstCharOf is prefix operator with subscript chunk precedence
	"the" "first" "char" "of" <Target: Expression>
begin
	MCCharFetchFirstCharOf(Target, output)
	MCCharStoreFirstCharOf(input, Target)
end syntax

/**
Summary:            Designates the last char in <Target>.
Target:				An expression which evaluates to a string.

Example:
	variable tVar as String
	put "char" into tVar
	
	variable tLast as String
	put the last char of tVar into tLast -- tLast contains "r"

Description:
Either locates the last char for use as the target container of another operation, or evaluates the last char as the source of another operation.

>*Note:* It is an error if <Target> is empty.

Tags: Strings
*/

syntax LastCharOf is prefix operator with subscript chunk precedence
	"the" "last" "char" "of" <Target: Expression>
begin
	MCCharFetchLastCharOf(Target, output)
	MCCharStoreLastCharOf(input, Target)
end syntax

--

/**
Summary:            Deletes the char at index <Index> in <Target>.
Index: 				An expression which evaluates to a valid integer index of <Target>.
Target:				A string container.

Example:
	variable tVar as String
	put "thorough" into tVar
	delete char 3 of tVar -- tVar contains "through"

Description:
Replaces the char at the given index with the empty string.

>*Note:* It is an error if <Index> is out of range.

Tags: Strings
*/

syntax DeleteSingletonCharOf is statement
	"delete" "char" <Index: Expression> "of" <Target: Expression>
begin
	MCCharExecDeleteCharOf(Index, Target)
end syntax

/**
Summary:            Deletes the chars between indices <Start> and <Finish> in <Target>.

Start:              An expression which evaluates to a valid integer index of <Target>.
Finish:             An expression which evaluates to a valid integer index of <Target>.
Target:             A string container.

Example:
	variable tVar as String
	put "surround" into tVar
	delete char 2 to 4 of tVar -- tVar contains "sound"

Description:
Replaces the chars between the given indices with the empty string.

>*Note:* It is an error if either <Start> or <Finish> are out of range.

Tags: Strings
*/

syntax DeleteRangeCharOf is statement
	"delete" "char" <Start: Expression> "to" <Finish: Expression> "of" <Target: Expression>
begin
	MCCharExecDeleteCharRangeOf(Start, Finish, Target)
end syntax

/**
Summary:            Deletes the first char in <Target>.
Target:				A string container.

Example:
	variable tVar as String
	put "seven" into tVar
	delete the first char of tVar -- tVar contains "even"

Description:
Replaces the first char in <Target> with the empty string.

>*Note:* It is an error if <Target> is the empty string.

Tags: Strings
*/

syntax DeleteFirstCharOf is statement
	"delete" "the" "first" "char" "of" <Target: Expression>
begin
	MCCharExecDeleteFirstCharOf(Target)
end syntax

/**
Summary:            Deletes the last char in <Target>.
Target:				A string container.

Example:
	variable tVar as String
	put "deadliness" into tVar
	delete the last char of tVar -- tVar contains "deadlines"

Description:
Replaces the last char in <Target> with the empty string.

>*Note:* It is an error if <Target> is the empty string.

Tags: Strings
*/

syntax DeleteLastCharOf is statement
	"delete" "the" "last" "char" "of" <Target: Expression>
begin
	MCCharExecDeleteLastCharOf(Target)
end syntax

--

/**
Summary:            Determines whether <Needle> is in <Target>.
Needle: 			An expression which evaluates to a char.
Target: 			An expression which evaluates to a string.

Returns: 	True if <Needle> is among the chars of <Target>, and false otherwise.

Description:
>*Note:* It is an error if <Needle> evaluates to a string consisting of more than one char.

Tags: Strings
*/

syntax CharIsInString is neutral binary operator with comparison precedence
    <Needle: Expression> "is" "in" <Source: Expression>
begin
    MCCharEvalIsAmongTheCharsOf(Needle, Source, output)
end syntax

--

/**
Summary:            Finds the first or last occurrence of <Needle> within <Target>

Needle: 			An expression which evaluates to a string.
Target: 			An expression which evaluates to a string.

Returns: 	Returns the offset of <Needle> in <Target>.

Example:
	variable tVar as Number
	put the first offset of "art" in "cartoon" into tVar -- tVar contains 2

Example:
	variable tVar as Number
	variable tFilePath as String
	put "/Users/user/Documents/file.txt" into tFilePath
	put the last offset of "/" in tFilePath into tVar
	
	variable tFileName as String
	put char 1 to tVar of tFilePath into tFileName -- tVar contains "file.txt"

Description:
The first (respectively last) offset of <Needle> in <Target> is number of chars between the first char of <Target> and the first (respectively last) occurrence of <Needle>. If neither first or last is specified, then the first offset is found. If <Needle> does not occur in <Target>, then the output is 0.

Tags: Strings
*/

syntax CharOffset is prefix operator with function chunk precedence
    "the" ( "first" <IsLast=false> | "last" <IsLast=true> | <IsLast=false> ) "offset" "of" <Needle: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfChars(IsLast, Needle, Target, output)
end syntax
syntax CharIndex is prefix operator with function chunk precedence
    "the" ( "first" <IsLast=false> | "last" <IsLast=true> | <IsLast=false> ) "index" "of" <Needle: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfChars(IsLast, Needle, Target, output)
end syntax

/**
Summary:            Finds the first or last occurrence of <Needle> after a specified index in <Target>

Needle: 			An expression which evaluates to a string.
Target: 			An expression which evaluates to a string.
After:              An expression which evaluates to a valid integer index of Target.

Returns: 	Returns the offset of <Needle> after <After> in <Target>.

Example:
	variable tVar as Number
	put the offset of "nse" after 4 in "nonsense" into tVar -- tVar contains 2
	
Description:
The first (respectively last) offset of <Needle> in <Target> is number of chars between the first char of the substring of <Target> beginning at char <After> + 1, and the first (respectively last) occurrence of <Needle> in the substring. If neither first or last is specified, then the first offset is found. If <Needle> does not occur in the given substring of <Target>, then the output is 0.

Tags: Strings
*/
syntax CharOffsetAfter is prefix operator with function chunk precedence
    "the" ( "first" <IsLast=false> | "last" <IsLast=true> | <IsLast=false> ) "offset" "of" <Needle: Expression> "after" <After: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfCharsAfter(IsLast, Needle, After, Target, output)
end syntax
syntax CharIndexAfter is prefix operator with function chunk precedence
    "the" ( "first" <IsLast=false> | "last" <IsLast=true> | <IsLast=false> ) "index" "of" <Needle: Expression> "after" <After: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfCharsAfter(IsLast, Needle, After, Target, output)
end syntax

/**
Summary:            Finds the first or last occurrence of <Needle> before a specified index in <Target>.

Needle: 			An expression which evaluates to a string.
Target: 			An expression which evaluates to a string.
Before:              An expression which evaluates to a valid integer index of Target.

Returns: 	Returns the offset of <Needle> before <Before> in <Target>.

Example:
	variable tVar as Number
	variable tLastDot as Number
	variable tAddress as String
	variable tTLD as String
	put "http://www.livecode.com/index.html" into tAddress
	put the last offset of "." in tAddress into tLastDot
	put the offset of "." before tLastDot in tAddress into tVar
	put char tVar + 1 to tVar + 3 of tAddress into tTLD -- tTLD contains "com"
	
Description:
The first (respectively last) offset of <Needle> in <Target> is number of chars between the first char of <Target>, and the first (respectively last) occurrence of <Needle> in the substring of <Target> ending at char <Before> - 1. If neither first or last is specified, then the last offset is found. If <Needle> does not occur in the given substring of <Target>, then the output is 0.

Tags: Strings
*/

syntax CharOffsetBefore is prefix operator with function chunk precedence
    "the" ( "first" <IsFirst=true> | "last" <IsFirst=false> | <IsFirst=false> ) "offset" "of" <Needle: Expression> "before" <Before: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfCharsBefore(IsFirst, Needle, Before, Target, output)
end syntax
syntax CharIndexBefore is prefix operator with function chunk precedence
    "the" ( "first" <IsFirst=true> | "last" <IsFirst=false> | <IsFirst=false> ) "index" "of" <Needle: Expression> "before" <Before: Expression> "in" <Target: Expression>
begin
    MCCharEvalOffsetOfCharsBefore(IsFirst, Needle, Before, Target, output)
end syntax

/**
Summary:            Determines whether <Source> contains <Needle>.
Needle: 			An expression which evaluates to a string.
Source: 			An expression which evaluates to a string.

Returns: 	Returns true if <Source> contains <Needle>.

Description:
<Source> contains <Needle> if and only if the chars of <Needle> occur as a subsequence of the chars of <Source>.

>*Note:* Since "" is a substring of every string, every string contains the empty string.

Tags: Strings
*/

syntax ContainsChars is neutral binary operator with comparison precedence
    <Source: Expression> "contains" <Needle: Expression>
begin
    MCCharEvalContains(Source, Needle, output)
end syntax

--

/**
Summary:            Determines whether <Source> begins with <Prefix>
Prefix: 			An expression which evaluates to a string.
Source: 			An expression which evaluates to a string.

Returns: 	Returns true if <Source> begins with <Prefix>.

Example:
	variable tVar as String
	variable tResult as String
	put "abcde" into tVar
	if tVar begins with "abc" then
		put "success" into tResult
	end if	

Description:
<Source> begins with <Prefix> if and only if the chars of <Prefix> occur as an initial subsequence of the chars of <Source>.

>*Note:* Since "" is an initial substring of every string, every string begins with the empty string.

Tags: Strings
*/

syntax StringBeginsWithString is neutral binary operator with comparison precedence
    <Source: Expression> "begins" "with" <Prefix: Expression>
begin
    MCCharEvalBeginsWith(Source, Prefix, output)
end syntax

/**
Summary:            Determines whether <Source> ends with <Suffix>
Suffix: 			An expression which evaluates to a string.
Source: 			An expression which evaluates to a string.

Returns: 	Returns true if <Source> ends with <Suffix>.

Example:
	variable tVar as String
	variable tResult as String
	put "abcde" into tVar
	if tVar ends with "cde" then
		put "success" into tResult
	end if	
	
Description:
<Source> ends with <Suffix> if and only if the chars of <Suffix> occur as a final subsequence of the chars of <Source>.

>*Note:* Since "" is a final substring of every string, every string ends with the empty string.

Tags: Strings
*/

syntax StringEndsWithString is neutral binary operator with comparison precedence
    <Source: Expression> "ends" "with" <Suffix: Expression>
begin
    MCCharEvalEndsWith(Source, Suffix, output)
end syntax

--

/**
Summary:			The new line character

Example:
	variable tList as List
	push "line 1" onto tList
	push "line 2" onto tList
	push "line 3" onto tList
	
	variable tLines as String
	combine tList with newline into tLines -- tLines has 3 lines

Description:
Use the <newline> constant to add new lines to a string variable.

Tags: Strings
*/

syntax NewLineCharacter is expression
    "newline"
begin
    MCCharEvalNewlineCharacter(output)
end syntax

/**
Summary:        Repeat over the chars of a string
Iterand:        A string container.

Example:
	variable tChar as String
	variable tSpaceCount as Number
	repeat for each char tChar in \
			"the quick brown fox jumps over the lazy dog"
		if tChar is " " then
			add 1 to tSpaceCount
		end if
	end repeat
	expect that tSpaceCount is 8

Description:
Use repeat for each to perform an operation on each char of a string. On each iteration, the <Iterand> will contain the next char of the string being iterated over.

Tags: Strings, Control structures
*/

syntax RepeatForEachChar is iterator
    "char" <Iterand: Expression>
begin
    MCCharRepeatForEachChar(iterator, Iterand, container)
end syntax

--

public foreign handler MCStringExecReverseCharsOf(inout Target as String) \
		returns nothing binds to "<builtin>"

/**
Summary:	Reverse a string
Target:	A string

Example:
	variable tString
	put "abcdef" into tString
	reverse tString
	expect that tString is "fedcba"

Description:
Reverses the order of characters in the <Target>.

Tags: Strings
*/
syntax ReverseCharsOf is statement
	"reverse" <Target: Expression>
begin
	MCStringExecReverseCharsOf(Target)
end syntax

----------------------------------------------------------------

/**
Summary:	Get the numeric value of a single char

Target:	A string containing one character

Description:
Returns the Unicode codepoint index of a single character.

Tags: Strings
*/

syntax CodeOfChar is prefix operator with function chunk precedence
    "the" "code" "of" <Target: Expression>
begin
    MCStringEvalCodeOfChar(Target, output)
end syntax

/**
Summary:	Create a 1-char string from a number

Value:		A Unicode codepoint index

Description:
Returns a string containing one Unicode character created using the
given value.

Tags: Strings
*/

syntax CharWithCode is prefix operator with function chunk precedence
    "the" "char" "with" "code" <Index: Expression>
begin
    MCStringEvalCharWithCode(Index, output)
end syntax

end module