/* --------------------------------
** FUNCTION:
**   fnHeadList
** DESCRIPTION:
**   This function returns the first specified number
**   of elements from a string list as a new string
**   reference.
** DEPENDENCIES:
**   none.
** DATE:
** SEE ALSO:
**   fnHeadArray, fnPartitionArray,
**   fnPartitionList, fnTailArray,
**   fnTailList
** 
   -------------------------------- */

function fnHeadList(sList, sDivisor, iLength)
{
  var sReturn = "";
  var aaReturn = new Array();

  //-- Validate function parameters
  if (sList == null)
  {
    document.write(
      "ERROR: .... \n");
    return -1;
  } //-- if array null

  if (sDivisor == null)
    { sDivisor = "\n"; }

  aaArray = sList.split(sDivisor);

  if (iLength == null)
    { iLength = 1; }

  if (iLength > aaArray.length)
    { iLength = aaArray.length; }

  for (var ii = 0; ii < iLength; ii++)
    { aaReturn[ii] = aaArray[ii]; }

  for (var ii = 0; ii < aaReturn.length; ii++)
    { sReturn += aaReturn[ii] + sDivisor; }

  return sReturn;

} //-- fnHeadList