This file documents the intrinsic functions provided for SLirc by
the module utils-module.so.  They are mostly string manipulation functions.
Some are just intrinsic versions of similarly named unix libc functions.
Others, like chomp() are inspired by perl; or like cut_list_element(),
just seem like natural extensions to existing SLang intrinsics.

This is not really a general purpose group of functions, it is just
a collection of functions which happened to be convenient for a
SLang program dealing with the IRC protocol.

To use them, your .sl scripts must first load the utils-module by
doing:
          insmod("utils");

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

chomp

 SYNOPSIS
   Chop off any trailing "\r\n" or "\n" from a string.

 USAGE
   String_Type chomp (String_Type a)

 DESCRIPTION
   The `chomp' function returns the argument string less any terminating
   "\n" or "\r\n".  If `a' does not terminate in "\n" or "\r\n", then
   it returns the input string unaltered.

 EXAMPLE
          a = chomp("bring\r\n");
          returns a == "bring"
          b = chomp("bring");
          returns b == "bring"

 SEE ALSO
   chop_1st, chop_last
--------------------------------------------------------------

chop_1st

 SYNOPSIS
   Chop the 1st character from a string.

 USAGE
   String_Type chop_1st (String_Type a)

 DESCRIPTION
   The `chop_1st' function returns the argument string with its
   first character removed.  It returns NullString on the NullString.

 EXAMPLE
          b = chop_1st("bring");
   returns b == "ring"

 SEE ALSO
   chop_last, chomp
--------------------------------------------------------------

chop_last

 SYNOPSIS
   Chop the last character from a string.

 USAGE
   String_Type chop_last (String_Type a)

 DESCRIPTION
   The `chop_last' function returns the argument string with its
   last character removed.  It returns NullString on the NullString.

 EXAMPLE
          b = chop_1st("bring");
    returns b == "brin"

 SEE ALSO
   chop_1st, chomp
--------------------------------------------------------------

cut_list_element

 SYNOPSIS
   Delete an element from a delimited string.

 USAGE
   String_Type cut_list_element (String_Type list, String_Type elem, Integer_Type delim)

 DESCRIPTION
  The `cut_list_element' function may be used to delete an element `elem'
  from a delimited list of strings `list'.

 EXAMPLE
  The expression

        cut_list_element ("alpha,beta,gamma", "beta", ',');

  returns "alpha,gamma"

 NOTES
   All occurrences of the `elem' are deleted from the list,
   not just the 1st.

 SEE ALSO
   extract_element, is_substr, is_list_element, create_delimited_string
--------------------------------------------------------------

index

 SYNOPSIS
   Test for a specified character within a string.

 USAGE
   Integer_Type index (String_Type a, Integer_Type c)

 DESCRIPTION
  This function may be used to determine if `a' contains the
  character `c'.  If it does not, the function returns 0; otherwise it
  returns the position of the first occurance of `c' in `a'.

 NOTES
  It is important to remember that the first character of a string
  corresponds to a position value of `1'.

 SEE ALSO
   rindex, substr, string_match, str_replace
--------------------------------------------------------------

is_alnums

 SYNOPSIS
   Test whether a string is entirely alphanumeric characters.

 USAGE
   Interpret is_alnums (String_Type a)

 DESCRIPTION
   The `is_alnums' function tests a string to see whether it consists
   entirely of alphanumeric characters.  It returns 1 if yes, a 0 if no.
   It returns 0 on the NullString.

 EXAMPLE

 NOTES
   The meaning of 'alphanumeric' is that of the C-function isalnum(),
   which is dependant on the C locale.

 SEE ALSO
   is_lowers, is_uppers, is_alnums, is_digits
--------------------------------------------------------------

is_digits

 SYNOPSIS
   Test whether a string is entirely decimal digits.

 USAGE
   Interpret is_digits (String_Type a)

 DESCRIPTION
   The `is_digits' function tests a string to see whether it consists
   entirely of digits 0-9.  It returns 1 if yes, a 0 if no.
   It returns 0 on the NullString.

 EXAMPLE

 NOTES

 SEE ALSO
   is_alnums, is_digits, is_lowers, is_uppers
--------------------------------------------------------------

is_lowers

 SYNOPSIS
   Test whether a string is entirely lowercase alphabetic characters.

 USAGE
   Interpret is_lowers (String_Type a)

 DESCRIPTION
   The `is_lowers' function tests a string to see whether it consists
   entirely of lowercase alphabetic characters.  It returns 1 if yes,
   a 0 if no.  It returns 0 on the NullString.

 EXAMPLE

 NOTES
   The meaning of uppercase/lowercase is that defined by the SLang.
   The meaning of 'alpha' is that of the C-function isalpha(), which
   is dependant on the C locale.

 SEE ALSO
   is_uppers, is_alnums, is_digits
--------------------------------------------------------------

is_uppers

 SYNOPSIS
   Test whether a string is entirely uppercase alphabetic characters.

 USAGE
   Interpret is_uppers (String_Type a)

 DESCRIPTION
   The `is_uppers' function tests a string to see whether it consists
   entirely of uppercase alphabetic characters.  It returns 1 if yes,
   a 0 if no.  It returns 0 on the NullString.

 EXAMPLE

 NOTES
   The meaning of uppercase/lowercase is that defined by the SLang.
   The meaning of 'alpha' is that of the C-function isalpha(), which
   is dependant on the C locale.

 SEE ALSO
   is_lowers, is_alnums, is_digits
--------------------------------------------------------------

is_prefix

 SYNOPSIS
   Check whether the one string has another as a prefix.

 USAGE
   Interpret is_prefix (String_Type a, String_Type b)

 DESCRIPTION
   It returns 1 if `b' is a prefix to `a', otherwise 0.

 EXAMPLE
     is_prefix("shoestore","shoe")
     returns 1

     is_prefix("shoestore","store")
     returns 0

 SEE ALSO
   is_prefix, is_prefix_i, is_substr
--------------------------------------------------------------

is_prefix_i

 SYNOPSIS
   Check whether the one string has another as a prefix,
   ignoring upper/lower case distinctions.

 USAGE
   Interpret is_prefix_i (String_Type a, String_Type b)

 DESCRIPTION
   Like is_prefix, ignoring case differences.

 EXAMPLE
     is_prefix_i("ShoeStore","shoE")
     returns 1

     is_prefix_i("ShoeStore","hoeS")
     returns 0

 SEE ALSO
   is_prefix, is_prefix_i, is_substr
--------------------------------------------------------------

rindex

 SYNOPSIS
   Find last occurence of specified character within a string.

 USAGE
   Integer_Type rindex (String_Type a, Integer_Type c)

 DESCRIPTION
  This function may be used to find the last occurence of a character `c'
  in a string `a'.  If the character does not occur in the string, the
  function returns 0; otherwise it returns the position of the last
  occurence of `c' in `a'.

 NOTES
  It is important to remember that the first character of a string
  corresponds to a position value of `1'.

 SEE ALSO
   index, substr, string_match, str_replace
--------------------------------------------------------------

s_split

 SYNOPSIS
   Split a string into substrings.

 USAGE
   Integer_Type s_split (String_Type str, Integer_Type delim)

 DESCRIPTION
     The `s_split' function may be used to split-up a string
     `str' that consists of substrings delimited by the character
     specified by `delim'.
     The function returns to the stack a variable number
     of objects.  The top stack object represents the number of
     substrings that are on the stack.  For example,

             s_split ("apples,oranges,pears", ',');

     will return the integer `3' to the top of the stack followed
     by the three strings:  `"apples"', `"oranges"', and
     `"pears"'.

 NOTES
   This function is equivalent to the builtin SLang intrinsic
   strchop(str,delim,0), therefore somewhat redundant.  It was
   written originally for use with slang-0.99-38 which did not
   (apparantly) have strchop().

 SEE ALSO
   v_split, strchop, strchopr, extract_element, create_delimited_string
--------------------------------------------------------------

url_encode

 SYNOPSIS
   Do escaping of certain characters for sending www-form-urlencoded
   HTTP queries.

 USAGE
   String_Type url_encode (String_Type str)

 DESCRIPTION
     Does escaping of certain special characters for sending
     HTTP requests.  Escape sequences map, for example, '.' to %2E.
     Or something like that.

 SEE ALSO
   url_decode
--------------------------------------------------------------

url_decode

 SYNOPSIS
   Unencode a string encoded by url_encode.

 USAGE
   String_Type url_decode (String_Type str)

 DESCRIPTION
   Translates escape sequences of form %HH in the input string
   to the corresponding ascii value.  (H is a hexdigit, one of
   0-9, A-F, a-f.)

 SEE ALSO
   url_encode
--------------------------------------------------------------

v_split

 SYNOPSIS
   Split a string into substrings.

 USAGE
   v_split (String_Type str, String_Type delims)

 DESCRIPTION
     The `v_split' function may be used to split-up a string
     `str' that consists of substrings delimited by different
     characters specified by `delims'.
     The function will return to the stack a number of strings
     which is 1 more than the number of characters in `delims'.

             v_split ("Shorty!guest@yoyo.com", "!@");

     will return the the string "Shorty" to the top of the stack
     followed by the strings:  "guest" and "oranges".

             v_split ("Shorty!guest+yoyo.com", "!@");

     will return the 3 strings "Shorty" , "guest+yoyo.com", "". 
     That is, when a delim char is not found, then the strings
     which 'would have followed it' are returned as NullStrings.

 NOTES
   This function was mainly written as a convenient way to split
   apart a typical IRC "nick!user@host" into the respective parts.

 SEE ALSO
   s_split, strchop, strchopr, extract_element, create_delimited_string
--------------------------------------------------------------

streq

 SYNOPSIS
   Compare two strings

 USAGE
   Interpret streq (String_Type a, String_Type b)

 DESCRIPTION
   The `streq' does a case-sensitive comparison of 2 strings.
   It returns 1 if the strings are identical, otherwise 0.

 EXAMPLE

 NOTES
   One may also use one of the binary comparison operators, e.g.,
   `a == b'.  These functions exist mainly to speed up list searches.

 SEE ALSO
   streq_i, is_prefix, is_prefix_i
--------------------------------------------------------------

streq_i

 SYNOPSIS
   Case-insensitive compare two strings for equality.

 USAGE
   Interpret streq_i (String_Type a, String_Type b)

 DESCRIPTION
   The `streq_i' does a case-insensitive comparison of 2 strings.
   It returns 1 if the strings are identical (except for case),
   otherwise 0.

 EXAMPLE

 NOTES
   The meaning of case-equivalence is that of SLang, see define_case().

 SEE ALSO
   streq, is_prefix, is_prefix_i, define_case, strup, strlow
--------------------------------------------------------------

strspn

 SYNOPSIS
   Find initial part of a string which is from a specified set
   of characters.

 USAGE
   Interpret strspn (String_Type a, String_Type b)

 DESCRIPTION
   The `strspn' examines string `a', advancing over each character
   which appears in string `b'.  It returns the length of the prefix
   of `a' which consists only of characters from `b'.

 EXAMPLE
            strspn("case","abcde") returns 2

 SEE ALSO
   strcspn
--------------------------------------------------------------

strcspn

 SYNOPSIS
   Find initial part of a string which is not from a specified set
   of characters.

 USAGE
   Interpret strcspn (String_Type a, String_Type b)

 DESCRIPTION
   The `strspn' examines string `a', advancing over each character
   which is not in string `b'.  It returns the length of the prefix
   of `a' which consists only of characters not from `b'.

 EXAMPLE
            strspn("case","eor") returns 3

 SEE ALSO
   strspn
--------------------------------------------------------------

unix_time

 SYNOPSIS
   Return time in seconds since 0:00:00 GMT Jan 1, 1970, cast to integer.

 USAGE
   Interpret unix_time ()

 DESCRIPTION

 EXAMPLE

 NOTES
   The integer value will roll over into negatives sometime in year 2038,
   on machines using 32-bit integers.

 SEE ALSO
   unix_ctime

