/* 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 for performing complex type conversion in LiveCode Builder.
*/

module com.livecode.typeconvert

public foreign handler MCTypeConvertExecSplitStringByDelimiter(in Target as String, in Delimiter as String) returns List binds to "<builtin>"
public foreign handler MCTypeConvertExecCombineListWithDelimiter(in Target as List, in Delimiter as String) returns String binds to "<builtin>"

--

/*
Summary:        Splits the string in <Target> into a list of strings, using <Delimiter>
                as the delimiter.

Target:         An expression that evaluates to a string container.
Delimiter:      An expression that evaluates to a string.

The result: 	The list of strings.

Example:
	variable tVar as String
    put "first,second,third,fourth,fifth" into tVar
    variable tSplit as List
    split tVar by ","
    put the result into tSplit
    put element 1 of tSplit into tFirstElement // tFirstElement contains "first"
    
Description:
Use the split command to convert a string representation of a list into a genuine (ordered) list.

Tags: Type conversion
*/

syntax StringSplitBy is statement
	"split" <Target: Expression> "by" <Delimiter : Expression>
begin
    MCTypeConvertExecSplitStringByDelimiter(Target, Delimiter)
end syntax

/*
Summary:        Combines the list of strings in <Target>, using <Delimiter>
                as the delimiter. 
                
Target:         An expression that evaluates to a list container.
Delimiter:      An expression that evaluates to a string.

The result: 	The combined string.

Example:
	variable tDigits as List
	put [1,2,3,4,5,6,7,8,9] into tDigits
	
	variable tString as String
    combine tDigits with "|" 
    put the result into tString // tString contains "1|2|3|4|5|6|7|8|9"
            
Description:
Use the combine command to convert a list into a string representation of the list.

>*Note:* The list *must* consist entirely of string elements, otherwise the combine command will throw an error.

Tags: Type conversion
*/

syntax CombineListWith is statement
    "combine" <Target: Expression> "with" <Delimiter : Expression>
begin
    MCTypeConvertExecCombineListWithDelimiter(Target, Delimiter)
end syntax

--

end module
