Contents page

Rules for Tools/stringtolength()

     long stringtolength(struct Clip *clip, long start,
                    char *string, long oldlength)

    `struct Clip  *clip'
          Clip for conversion.

    `long start'
          Time conversion occurs.

    `char *string'
          String to convert.

    `long oldlength'
          Original length.

     Use `stringtolength()' to convert user input in the
     measure.beat.clock format into a duration in clocks.  Use this
     when the user needs to input a duration in beats & measures,
     rather than an absolute time in beats & measures.  Durations start
     counting from measure and beat 0, rather than measure 1, beat 1.
     For example, `stringtolength()' converts "2.01.05" into 1733

     Because the time signature may change at different points in the
     song, we need to know the time at which the conversion occurs as
     well as the string to convert.

     If the user types in an illegal string, `stringtolength()' traps
     the error and returns oldlength instead.

     The clip pointer determines the time signature used for the
     conversion. If you set clip to 0, `stringtolength()' will consult
     the master Song Parameters.

     The string is a standard C ASCII text string, not a Bars&Pipes
     dynamic string.

     If you need to convert to an absolute time ("The Event occurs at
     this time in the song," rather than, "The Event lasts this long,")
     use `stringtotime()' .

     See stringtotime(), timetostring(), lengthtostring().