/** -*-C-*-ish
    Kaya standard library
    Copyright (C) 2004, 2005 Edwin Brady

    This file is distributed under the terms of the GNU Lesser General
    Public Licence. See COPYING for licence.
*/
"<summary>String processing functions</summary>
<prose>This module contains string processing functions.</prose>"
module Strings;

import Regex;
import Prelude;

%include "string.h";
%include "stdlib.h";

foreign "stdfuns.o" {
    String b64enc(String block, Int len) = b64enc;
    String b64dec(String str, intval len) = b64dec;
    "<argument name='c'>The character to check for</argument>
     <argument name='str'>The string to check</argument>
     <summary>Check if a character appears in a string</summary>
     <prose>Returns true if the character appears in the String, false otherwsie.</prose>
     <related><functionref>Array::elem</functionref></related>
     <related><functionref>firstOccurs</functionref></related>"
    public Bool elem(Char c, String str) = do_wcschr;
    "<argument name='c'>The character to check for</argument>
     <argument name='str'>The string to check</argument>
     <summary>Return the position of the first occurence of a character</summary>
     <prose>Returns the position of the first occurence of the character in the string (or the length of the string if the character is not in the string).</prose>
     <example>str = \"abcdefgabcde\";
i = firstOccurs('a',str); // i = 0
i = firstOccurs('d',str); // i = 3
i = firstOccurs('h',str); // i = 12</example>
    <related><functionref>elem</functionref></related>
    <related><functionref index='1'>firstOccurs</functionref></related>"
    public Int firstOccurs(Char c, String str) = do_wcscspn;


    Int do_firstOccurs(String needle, String haystack) = do_wcsstr;

    Void str_offset(str x, Int inc) = str_offset;
    Void str_chop(str x, Int inc) = str_chop;
}

"<argument name='needle'>The string to check for</argument>
<argument name='haystack'>The string to check</argument>
<summary>Return the position of the first occurence of a substring</summary>
<prose>Returns the position of the first occurence of the <variable>needle</variable> substring in the <variable>haystack</variable> string (or the length of the string if the substring is not in the string).</prose>
<example>str = \"abcdefgabcde\";
i = firstOccurs(\"ab\",str); // i = 0
i = firstOccurs(\"de\",str); // i = 3
i = firstOccurs(\"efa\",str); // i = 12</example>
<related><functionref>firstOccurs</functionref></related>"
public Int firstOccurs(String needle, String haystack) {
  i = do_firstOccurs(needle,haystack);
  if (i == -1) {
    return length(haystack);
  }
  return i;
}





// Is this used/useful? (ECB 14/1/07)
// not any more - only head() ever used it and that doesn't now
// Exception EmptyString();

// is there any reason not to use Regex::split(R"\s+") instead?
R"<argument name='x'>The string to split</argument>
<summary>Split a String into words.</summary>
<prose>Splits a String into whitespace separated words.</prose>
<example>x = \"The quick brown    fox jumps\n\tover the lazy dog\";
ws = words(x); // [\"The\",\"quick\",\"brown\",\"fox\",\"jumps\",
               //  \"over\",\"the\",\"lazy\",\"dog\"];</example>
<related><functionref>lines</functionref></related>
<related><functionref>Regex::split</functionref></related>
<related><functionref>unwords</functionref></related>"
public [String] words(String x)
{
    [String] all = [];
    str = x;
    current = "";
    while (str!="") {
	c = head(str);
	str = tail(str);
	if (isSpace(c)) {
	    if (current!="") {
		all[size(all)]=current;
		current = "";
	    }
	}
	else {
	    current = current + String(c);
	}
    }
    if (current!="") {
	all[size(all)]=current;
    }
    return all;
}

r"<argument name='x'>The string to split</argument>
<argument name='d'>A function to select characters to split on, that returns true if it should split at this point, and false otherwise. Defaults to <functionref>Prelude::isLineEnding</functionref> if omitted (though in this case the <functionref>lines</functionref> function should probably be used).</argument>
<summary>Split a String into substrings</summary>
<prose>Split a String into substrings by a given delimiter predicate or newline if none is given. Consecutive delimiters will give empty substrings.</prose>
<example>x = \"abc\n\ndef\";
xs = splitBy(x,isLineEnding); // [\"abc\",\"\",\"def\"]</example>
<related><functionref>join</functionref></related>
<related><functionref>lines</functionref></related>
<related><functionref>words</functionref></related>"
[String] splitBy(String x, Bool(Char) d=isLineEnding)
{
    [String] all = [];
    str = x;
    current = "";
    while (str!="") {
	c = head(str);
	str = tail(str);
	if (d(c)) {
	    all[size(all)]=current;
	    current = "";
	}
	else {
	    current = current + String(c);
	}
    }
    if (current!="") {
	all[size(all)]=current;
    }
    return all;
}

"<argument name='x'>The String to split</argument>
<summary>Splits a string into lines</summary>
<prose>Split a String into lines. This function correctly processes Windows, Unix and Mac line-ending conventions.</prose>
<related><functionref>join</functionref></related>"
public [String] lines(String x) {
  // otherwise windows line endings get split wrongly
  replace("\r\n","\n",x,[Global]);
  return splitBy(x,isLineEnding);
}

"<argument name='xs'>A list of Strings</argument>
<summary>Join a list of words into a String.</summary>
<prose>Join a list of words into a String.</prose>
<example>xs = [\"Hello\",\"World!\"];
x = unwords(xs); // \"Hello World!\"</example>
<related><functionref>join</functionref></related>
<related><functionref>words</functionref></related>"
public String unwords([String] xs) = Strings::join(xs,' ');

"<argument name='xs'>A list of words</argument>
<argument name='c'>The separator to use. This may be omitted and defaults to a newline.</argument>
<summary>Join a list of words into a String with the specified separator</summary>
<prose>Join a list of words into a String with the given separator
or newline if none is given.</prose>
<related><functionref index='1'>join</functionref></related>
<related><functionref>unwords</functionref></related>"
public String join([String] xs, Char c='\n')
{
  if (size(xs) == 0) { 
    return "";
  } // needed to avoid substr exception
    acc="";
    for x in xs {
	acc += x + String(c);
    }
    // since the separator is a single character, this trims the unwanted trailing separator
    return substr(acc,0,length(acc)-1);
}

"<argument name='xs'>A list of words</argument>
<argument name='c'>The separator to use. This may be omitted and defaults to a newline.</argument>
<summary>Join a list of words into a String with the specified separator</summary>
<prose>Join a list of words into a String with the given separator
or newline if none is given.</prose>
<related><functionref>join</functionref></related>
<related><functionref>unwords</functionref></related>"
public String join([String] xs, String s)
{
  if (size(xs) == 0) { 
    return "";
  } // needed to avoid substr exception
    acc="";
    for x in xs {
	acc += x + s;
    }
    // trims the unwanted trailing separator
    return substr(acc,0,length(acc)-length(s));
}


"<argument name='s'>The String</argument>
<summary>Get the first character in a String</summary>
<prose>Get the first character in a String</prose>
<related><functionref>tail</functionref></related>"
public Char head(String s) {
  /*  if (length(s) == 0) { // getIndex does this check
    throw(StringEmpty);
    }*/
  return getIndex(s,0);
}

"<argument name='s'>The String</argument>
<summary>Get the first character in a String</summary>
<prose>Get all but the first character in a String. Useful with <functionref>head</functionref> for iteration over strings.</prose>
<example>str = \"abcdef\";
i = 0;
do {
  i += Int(head(str));
  str = tail(str);
} while (length(str) > 0);</example>
<related><functionref>head</functionref></related>
<related><functionref>ltruncate</functionref></related>"
public String tail(String str) = strEnd(str,1);

"<argument name='p'>The predicate function.</argument>
<argument name='str'>The String to filter</argument>
<summary>Filter a string according to a predicate.</summary>
<prose>Each character in <variable>str</variable> is tested against the predicate <variable>p</variable>. The returned string contains those characters in <variable>str</variable> for which the predicate is true.</prose>"
public String filter(Bool(Char) p, String str) {
    newstr = "";
    for x in [0..length(str)-1] {
	c = getIndex(str,x);
	if (p(c)) newstr+=c;
    }
    return newstr;
}

"<argument name='i'>The number of characters to remove</argument>
<argument name='x'>The String to remove from</argument>
<summary>Remove characters from the left of a string, in-place.</summary>
<prose>Remove the first <variable>i</variable> characters from a string, in-place.</prose>
<related><functionref>behead</functionref></related>
<related><functionref>rtruncate</functionref></related>"
public Void ltruncate(Int i, String x) {
    if (i<0 || i > length(x)) {
	throw(OutOfBounds);
    }
    str_offset(x,i);
}

"<argument name='i'>The number of characters to remove</argument>
<argument name='x'>The String to remove from</argument>
<summary>Remove characters from the right of a string, in-place.</summary>
<prose>Remove the last <variable>i</variable> characters from a string, in-place.</prose>
<related><functionref>ltruncate</functionref></related>"
public Void rtruncate(Int i, String x) {
    if (i<0 || i > length(x)) {
	throw(OutOfBounds);
    }
    str_chop(x,i);
}

"<argument name='x'>The String to remove from</argument>
<summary>Remove the first character of a string, in-place.</summary>
<prose>Remove the first character of a string, in-place.</prose>
<related><functionref>ltruncate</functionref></related>"
public Void behead(String x) {
    ltruncate(1,x);
}

"<argument name='x'>The string to trim</argument>
<argument name='fn'>The trimming function. Returns true if characters should be trimmed, false otherwise. The default function is <functionref>Prelude::isSpace</functionref> which trims whitespace.</argument>
<summary>Trim selected characters from the end of a String</summary>
<prose>Remove characters in-place from the end of a String as determined by the trimming function.</prose>
<related><functionref>ltrim</functionref></related>
<related><functionref>trim</functionref></related>"
public Void rtrim(var String x, Bool(Char) fn=isSpace)
{
    while (length(x) > 0 && fn(getIndex(x,length(x)-1)))
    {
	x=substr(x,0,length(x)-1);
    }
}

"<argument name='x'>The string to trim</argument>
<argument name='fn'>The trimming function. Returns true if characters should be trimmed, false otherwise. The default function is <functionref>Prelude::isSpace</functionref> which trims whitespace.</argument>
<summary>Trim selected characters from the start of a String</summary>
<prose>Remove characters in-place from the start of a String as determined by the trimming function.</prose>
<related><functionref>rtrim</functionref></related>
<related><functionref>trim</functionref></related>"
public Void ltrim(var String x, Bool(Char) fn=isSpace)
{
    while (length(x) > 0 && fn(head(x)))
    {
	  behead(x);
    }
}

"<argument name='x'>The string to trim</argument>
<argument name='fn'>The trimming function. Returns true if characters should be trimmed, false otherwise. The default function is <functionref>Prelude::isSpace</functionref> which trims whitespace.</argument>
<summary>Trim selected characters from both ends of a String</summary>
<prose>Remove characters in-place from both ends of a String as determined by the trimming function.</prose>
<example>str = \"  this string needs trimming   \";
trim(str);
// str = \"this string needs trimming\";</example>
<related><functionref>ltrim</functionref></related>
<related><functionref>rtrim</functionref></related>"
public Void trim(var String x, Bool(Char) fn=isSpace) 
{
    ltrim(x,fn);
    rtrim(x,fn);
}

"<argument name='str'>The string to encode</argument>
<summary>Base64 encode a string</summary>
<prose>Encodes the input string in base64 encoding, and returns the encoded string.</prose>
<related><functionref>base64Decode</functionref></related>
<related><functionref>Binary::base64Encode</functionref></related>"
public String base64Encode(String str)
{
    return b64enc(str,length(str));
}

"<argument name='str'>The string to decode</argument>
<summary>Base64 decode a string</summary>
<prose>Decodes the input string, which must be in base64 encoding, and returns the original data.</prose>
<related><functionref>base64Encode</functionref></related>
<related><functionref>Binary::base64Decode</functionref></related>"
public String base64Decode(String str)
{
    len=0;
    return b64dec(str,len);
}

"<argument name='input'>The input string</argument>
<argument name='delimiters'>A list of characters that are treated as delimiters</argument>
<argument name='escape'>Characters that escape the string - i.e. delimiters between two escape characters are treated as literal characters.</argument>
<summary>Split a string into fields</summary>
<prose>This function splits a string into fields. For example, to split a CSV file, you could use <code>fields(input,[',','\\n'],['\"']);</code>. This will treat commas and newlines as field separators, except within quoted strings.</prose>
<related><functionref>Regex::split</functionref></related>"
public [String] fields(String input, [Char] delimiters, [Char] escape) {
  escstate = false;
  chars = array(input);
  strings = [];
  idx = 0;
  inited = false;
  for char in chars {
    if (elem(char,escape)) {
      escstate = !escstate;
    } else if (!escstate && elem(char,delimiters)) {
      if (!inited) {
	// initialise it here
	strings[idx] = createString(1);
      }
      idx++;
      inited = false;
    } else {
      if (!inited) {
	inited = true;
	strings[idx] = "";
      }
      strings[idx] += String(char);
    }
  }
  return strings;
}