/* --------------------------------
** FUNCTION:
**   fnAddTextToList
** DESCRIPTION:
**   Adds a specified text string either to the
**   start or to the end of each element of a string list.
** DEPENDENCIES:
**   none.
** DATE:
** 
   -------------------------------- */

function fnAddTextToList(
  sList, sDivisor, sAppend, bAddAtBeginning)
{
  var sReturn = new String("");
  var aaReturn = new Array();

  if (sList == null)
  {
    var sErrorMessage =
      "ERROR:      \n" +
      "------      \n" +
      "  function:  fnAddTextToList                 \n" +
      "  Parameter: sList                      \n\n" +
      "    A required parameter was omitted from \n" +
      "    the function.                         \n";
    document.write(sErrorMessage);
    return -1;
  } //-- if

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

  if (sAppend == null)
  {
    var sErrorMessage =
      "ERROR:      \n" +
      "------      \n" +
      "  function:  fnAddTextToList                 \n" +
      "  Parameter: sAppend                      \n\n" +
      "    A required parameter was omitted from \n" +
      "    the function.                         \n";
    document.write(sErrorMessage);
    return -1;
  } //-- if

  if (bAddAtBeginning == null)
    { bAddAtBeginning = true; }

  var aaList  = sList.split(sDivisor);

  for (var ii = 0; ii < aaList.length; ii++)
  {
    //-->-->-->
    //-- But what if some elements aren't strings??
    if (bAddAtBeginning)
      { aaReturn[ii] = sAppend + aaList[ii]; }
    else
      { aaReturn[ii] = aaList[ii] + sAppend; }
  } //--for 

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

  return sReturn;

} //-- fnAddTextToList