programmer's version || dataObject and other functions

## dSurvey functions: i/o, etc. functions

Quick list

String manipulation functions
cvalue = addCommas(avalue) | add commas to a number , in the proper positions (doesn't change decimal portion of number)
thewords = getWord(astring,nth,adelim) | parse string to array of words, or extract nth word
astring = manyDots(aval,amax,dastring)> | create a string of dots, the number cycling between 1 and amax
newstr = space(str,what) | remove/replace internal spaces
newstring = strip(astring,which) | strip spaces
atime = Seconds_ToTime(nseconds) | convert nseconds to time format (i.e.; `hh:mm:ss`
HTML Display and functions
displayDiv(adiv,todo) | adiv to toggle between block and none. Or, if todo specified, to the todo status
displayNextDiv(adiv,todo) | toggle display of the next element
Show_Variables() | Display current dSurvey global variables & arrays in a new window.
writeAlert(amessage) | Write a short, very transient alert message
writeFooter(amessage) | Write a message to the footer block at the bottom of the browser window
writeHeader(amessage) | Write a message to the (fixed) header block at the top of the browser window
writeMessage(amessage) | Write a transient message
Other functions
aval = svy_addth(arg1) | If arg1 is an integer, returns st,nd,rd, or th.
tstring=svy_currentTime(timeType,dateType) | Return current time and/or date.
dstring = svy_dollars(avalue) | return a $xx.yy string, given a value
avar2=svy_miss(avar,defval) | Returns value of avar, or defval if avar is not defiend
aval=svy_random(arg1,arg2,arg3) | Compute a uniform random number between arg1 and arg2
rstring=svy_randomExample(arg1,arg2,arg3,arg4,arg5,arg6) |
intVal=svy_toFixed(arg1,ndec) | Truncate value to ndec decimal places
istrue=svy_trueFalse(arg1,adefault) | Converts a 0/1 value to "false" or "true" text string.
aval=svy_whichOne(nvar,a0,a1..,a7) | Looks up the numeric value of the nvar argument, and returns the value of the appropriate a0,..,a7 arguments.

### Details....

### String manipulation functions

###

###

    addCommas

    newstring=addCommas(numval)

       Add commas to numval. Decimal component will not be changed.

    getWord

    thewords   =  getWord(astring,nth,adelim)

           Parse string to array of words, or extract nth word

          arguments:
              astring : a string containing words; by default seperated by one or more spaces.
              nth     : optional. Nth word to return. If not specified, or 0, array of all words returned
                        Thus, word "1" is the first word in the string.
              adelim  : optional. A delimiter. If not specified, a space (or spaces) is used

           If adelim =' ' (or ''), which is the default, then unique "words" are returned -- spaces are NOT
           considered to be words, nor are ever   part of a word.
           If adelim is anything else, then no attempt to shorten words (the delimiter is used as is).

            If nth is > # of words, a '' is returned.
            As noted above, if nth=0, an array containing all the words is used.
            Since this removes extaneous spaces, the results are more robust than .split(' ')

           Special case: if nth is an array, then return a string of words from nth[0] to nth[1], inclusive
           eg: toget=[2,3] ;
               foo=getWord("this is not very silly",toget)
               would return "not very"

          Examples:
              astring="this is my string of words "
                getWord(astring,1) = "this"
                getWord(astring) = array of 6 elements
                getWord(astring,7)=''
                toget=[3,4] ;  foo=getWord(astring,toget)  = "my string"

    manyDots

      astring=manyDots(aval,amax,dastring)

            Create a string of dots.
                 Aval : The length of the string to return. Required.
                 Amax : optional. The maximum length. If aval>amax, the remainder of aval/amax is used.
                          Default value=10
             dastring : optional. The default is ".................."
                          If you want to create a string of something else, specify dastring.

    seconds_ToTime

     atime=Seconds_ToTime(nseconds)

       Converts a number of seconds to a  hh:mm:ss time format.
       Example: atime=Seconds_ToTime(250)
                  yields "04:10" (without the quotes)
                atime=Seconds_ToTime(50)
                  yields ":50" (without the quotes)

    space

     newstr=space(str,what)

       Remove spaces (either shrink to 1 space, or remove altogether)
       what is a character string to replace spaces with. If not specified, ' ' (shrink to 1 space) is used.
       This does NOT strip leading and trailing spaces

    strip

     newstring=strip(astring,which)

         Strip leading and/or training spaces
            If which is L, then leading only (left),
                        R, then trailing (right) only
         Otherwise (if not specified), leading and trailing
         If astring is a number, it is converted into a string.
         If it is an object, nothing happens

    HTML Display and functions

    displayDiv

     displayDiv(adiv,todo)

       Toggle display of the adiv element (usually a span or a div) -- where adiv is a string containing the
       id of the element to be toggled.
       Todo is optional. If specified, insteadof toggling, the display style attribute will be set to todo.
       Recommended values of todo are "none" and "block"

    displayNextDiv

     displayNextDiv(athis,etype,clear1,howdo)

       displayNextElement is meant to be used in a clickable element. When clicked, it will (by default)
      turn on the display of the next element (following this clickable element)

       Example:
         <div> This is intro message </div>
         <a href="#" onClick="displayNextElement(this)">more...</a>
         <div style="display:none"> This is more message </div>

       When clicked, the 'This is more message' will displayed, and the 'more...' will be hidden

       Note that in this useage, you MUST include 'this' (without the quotes) as the argument

       Also, displayNextElement always returns false

     Arguments:
        athis: id of element to start with. typically, the "this" in inline attribute (required)
        etype: element type. Optional, * if not specified.  The element type to change the display of
               Thus, elements AND text inbetween the clickable element and the element that matches
               etype will not be effected.  * means "any match".
        clear1 : if 1, then hide this clickable element after it is clicked
        howdo  : how to change display of next (matching) element. Values can be:
                     'none' : hide the next element
                     'block' : display (as a DIV)
                     'inline'  : display (as a SPAN)
                     'toggle'  : toggle current display status (between 'none' and 'block')

        Notes:
          * registering displayNextElement to an object (say, using mybutton.onclick=displayNextElement),
            is equivalent to displayNextElement(this,'*',1,'toggle')
          * Text elements, between the clickable element and the matching element, are always skipped (there
            display is not effected
          * If clear1 is not set to 1, and howdo is 'toggle', the clickable element can be used to turn off and on
            the display of the next element

    Show_Variables

    Show_Variables(adiv,retstr)

      This is mostly used as a debugging tool.

      Display current dSurvey global variables & arrays in a new window.

      Alternate: Show_Variables(adiv)  -- display results in the div with an id of adiv.
      Alternate: Show_Variables(0,1)   -- return results in a string

    writeAlert

    writeAlert(amessage,duration)

      Write a message to the alert block.

      This is a fixed (same position on screen, always) block toward the bottom of the browser's window.
      When clicked, the box disappears.

      If duration is specified, the box will disappear in duration seconds.

    writeFooter

    writeFooter(amessage)

       Write a (short) message to the "description" block at the bottom of the browser window

    writeHeader

    writeHeader(amessage)

       Write a message to the header block (a fixed location at the top of the browser window)

    writeMessage

    writeMessage(amessage)

      Write a message to the message block.

      This is a fixed (same position on screen, always) block in the bottom third of the browser's window.
      When clicked, the box disappears.

     Other functions

    svy_addth

    aword=svy_addth(ith)

       If arg1 is an integer, returns st,nd,rd, or th.
       Arg1 can be number or a variable name.

    svy_currentTime)

    svy_currentTime(timeType,dateType)

     Return current time and/or date.

     If no arguments: return  hh:mm:ss xM

      timeType:
              0= javascript milliseconds
              1 =  mm:hh:ss xM

      dateType:
              1=  date Month Year
              2 = day-of-week, date Month Year

     if timeType and dateType ==2 : return as: xday Month date year hh:mm:ss GMT-xxxx (tz)

     if both time and date specified, format is date-string, time-string

    svy_dollars

    dstring = svy_dollars(avalue)

      Return a $xx.yy string, given a value

      Given a numeric value (avalue), returns a string of the format $nnnn.dd
      (preceded by a $ sign, with 2 digits to right of decimal point).

    svy_miss

    newval=svy_miss(avar,defval)

      Return value of avar. If no such avar, return defval.
      avar AND defval can be numbers or variables.

      If defval not specified, 0 is used.

      Caution: when called as function from a <SET> (or some other such dynamic extension) avar and
      defval should be 'quoted' --  otherwise the "value of avar and defval" will be sent to svy_miss.

    svy_random

    rval=svy_random(arg1,arg2,arg3)

      Compute a uniform random number between arg1 and arg2 (arg1 as the minumum and arg2 as the maximum).

      Arg3 is optional. If specified, it is number used as the "resolution" -- the random number will be
      rounded to this value.
            For example stats_random(10,5,1) will produce an integer between 5 and 15.

      Arg1, arg2, and arg3 can be numbers or variable names.
        If arg1 (or arg2) are NOT numbers (or are not variables that have a numeric value), a '' is returned.

    svy_randomExample

    rstring=svy_randomExample(arg1,arg2,arg3,arg4,arg5,arg6)

     Return  a string displaying possible draws from a uniform random distribution, using "v1,v2,...,vj,vk"
        arg1:  Low end. REQUIRED. This is always the first number displayed
        arg2 : High end. REQUIRED. This is always the last number displayed
        arg3:  Number of v1,v2  (if 3, v1,v3,v3 displayed, and vj,vk,vm). Optional: default is 1 (just the first and last values)
        arg4: resolution.   Optional. Default is 1 (move by ones)
        arg5:  # decimal points to display.  Optional, default is 0 (integer display)
        arg6: string to prepend to value.   Optional. Default is '' (no prepend)

      Example: svy_randomExample(100, 200, 2, 0.1, 2, $)
                  would yield:
              $100.10, $100.20, $100.30, ..., $199.80, $199.90, $200.00

      All of the arguments can be numbers of variables (though the variables must contain numeric values).

    svy_toFixed

    ntVal=svy_toFixed(arg1,ndec)

      Same as javascript function: avalue.toFixed(ndec) ; where avalue is the numeric value of arg1.

      Arg1 and ndec can be number or a variable name.

    svy_trueFalse

    istrue=svy_trueFalse(arg1,adefault)

       Converts a 0/1 value to "false" or "true" text string. If arg1 is not 0 or 1, returns the
       value of adefault

       Arg1 and adefault can be numbers, strings, or variable names.

           Example:  isItReal=svy_trueFalse(quest[1],'No answer')"

    svy_whichOne

    theval=svy_whichOne(nvar,a0,a1..,a7)

       Looks up the numeric value of the nvar argument, and returns the value of the
       appropriate a0,..,a7 arguments.

      Thus,
                     if nvar=0, then a0 (the 2nd argument) is returned.
                     if nvar=1, then a1 (the 3rd argument) is returned.
                           ...
                     if nvar=7, then a7 (the 9th argument) is returned.

      If nvar>7, or <0,  or nvar is evaulated to something other than an integer:  a '' is returned.

      Nvar be a number or a variable name.
      a0,...,a7 can be numbers, strings, or variable names.

      Example:
         If useMax can take values of 1,2, or 3...
         tmp3=svy_whichOne(useMax,max_offer,max_offer_group,max_offer_all2)