Documentation for Win32lib v0.60.6
Table of Contents

Series

Some utility routines to manange series of numbers.


A Series is just a set of numbers that you use when you need a set of sequential values.

Example:

    constant fldA = next_number("My Series")
    constant fldB = next_number("My Series")
    constant fldC = next_number("My Series")
    constant fldD = next_number("My Series")
    constant fldE = next_number("My Series")
    constant NumFlds = current_number("My Series")
This would give the constants fldA - fldE the values 1 to 5 respectively, and the NumFlds is set to 5 as well.

By default, a Series starts at 1 and increments by 1 with each call to next_number(). However, you may define a special series to suit particular needs. You can change the increment amount, the starting value, and whether the series wraps around when getting to the end.

Example:

      -- Define a set of angles from 0 to 2PI, incrementing by 0.1.
      -- And when the last angle is reached, start again at zero.
      define_series("angle", { {SValue,0}, {SFirst,0}, {SLast,2*PI},
                               {sIncr,0.1}, {SWrap,True} } )

If you have very special requirements, you can even define a routine_id that will be called when the user calls next_number and current_number. You can then make decisions about the value returned to the user; for example you may need to update a database whenever the user gets a new series value, or maybe you need to encrypt it before the user gets it, or convert it text, etc...

      define_series("special", { {sRtnId,routine_id("SeriesChecker")}, {SUserData,Tolerance} } )

The routine mentioned here will be called with five (5) parameters:

  • object pName : The name of the series.
  • integer pRequest : Either SCB_CurrentNum or SCB_NextNum which is the type of request that the user is asking for.
  • atom pValue : The series' current value.
  • integer pHasWrapped : Either 0 (false) or 1 (true) indicating whether or not the series just wrapped around to the start again.
  • object pUserData : The user data stored in the series by the last define_series() call to it.

    The value returned by this routine will be passed directly to the user.

  • func current_number(object pName)    Returns the current value in the series but does not increment it.
  • proc define_series(object pName, sequence pAttributes)   Defines a new series.
  • func get_series(object pName)   Fetches an entire definition for a series.
  • func next_number(object pName)   Increments the series and returns the next value in it.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    current_number
    (object pName)

    Returns the current value in the series but does not increment it.

    Returns: ATOM: The current value in the series.

    Category: Series

    Example:

        constant CUSTREC      = next_number("Record Layouts")
        constant C_Id         = next_number(CUSTREC)
        constant C_GivenName  = next_number(CUSTREC)
        constant C_FamilyName = next_number(CUSTREC)
        constant C_Address    = next_number(CUSTREC)
        constant C_Email      = next_number(CUSTREC)
        constant CUSTREC_SIZEOF = current_number(CUSTREC)
    

    constant INVOICE = next_number("Record Layouts") constant I_Id = next_number(INVOICE) constant I_Date = next_number(INVOICE) constant I_CustId = next_number(INVOICE) constant I_Terms = next_number(INVOICE) constant I_Address = next_number(INVOICE) constant INVOICE_SIZEOF = current_number(INVOICE)

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

    See Also: define_series, get_series, next_number


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    define_series
    (object pName, sequence pAttributes)

    Defines a new series.

    Category: Series

    Normally one doesn't need to define a series as a default series is created one the first call of next_number(). However, if you have special requirements this routine will help customize a series for you.

    pName is the user-defined name for this series. pAttributes is a set of zero or more attribute/value pairs to apply to this series.

    Valid attributes are :

  • SValue : Only used when resetting a series to a defined value.
  • SIncr : The amount to increment the series by. Default is 1.
  • SWrap : Indicator that the series can wrap from last to first. Default is 0 (no wrap).
  • SFirst : The first value in the series. Default is 1.
  • SLast : The last value in the series. Default is 0. If wrapping, this is the value that triggers the wrap.
  • SRtnId : A routine_id that is called when next_number() and current_number() are just about to return a value to the user.
  • SUserData : Any user data you wish to be passed back to the routine_id. Default is {}. Example:
          -- Define a set of angles from 0 to 2PI, incrementing by 0.1.
          -- And when the last angle is reached, start again at zero.
          define_series("angle", { {SValue,0}, {SFirst,0}, {SLast,2*PI},
                                   {sIncr,0.1}, {SWrap,True} } )
    

    See Also: current_number, get_series, next_number


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    get_series
    (object pName)

    Fetches an entire definition for a series.

    Returns: SEQUENCE: A Series definition.

    Category: Series

    The returned value could be used as input to define_series() if you wish.

    The attributes are returned in this order as a set of attribute/value pairs:

  • SValue : The current value of the series.
  • SIncr : The amount to increment the series by.
  • SWrap : Indicator that the series can wrap from last to first.
  • SFirst : The first value in the series.
  • SLast : The last value in the series.
  • SRtnId : The stored routine_id, if any
  • SUserData : Any user data you wish to be passed back to the routine_id.

    Example:

          sequence lDef
          lDef = get_series("Record Layouts")
    
    ---------------------------------------------

    See Also: current_number, define_series, next_number


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    next_number
    (object pName)

    Increments the series and returns the next value in it.

    Returns: ATOM: The next value in the series.

    Category: Series

    Example:

        constant CUSTREC      = next_number("Record Layouts")
        constant C_Id         = next_number(CUSTREC)
        constant C_GivenName  = next_number(CUSTREC)
        constant C_FamilyName = next_number(CUSTREC)
        constant C_Address    = next_number(CUSTREC)
        constant C_Email      = next_number(CUSTREC)
        constant CUSTREC_SIZEOF = current_number(CUSTREC)
    

    constant INVOICE = next_number("Record Layouts") constant I_Id = next_number(INVOICE) constant I_Date = next_number(INVOICE) constant I_CustId = next_number(INVOICE) constant I_Terms = next_number(INVOICE) constant I_Address = next_number(INVOICE) constant INVOICE_SIZEOF = current_number(INVOICE)

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

    See Also: current_number, define_series, get_series