!fnordmap.bsi [100] - ORDMAP related utility functions
!------------------------------------------------------------------------
!EDIT HISTORY
! [100] 29-Jul-25 / jdm / created
!------------------------------------------------------------------------
!REQUIREMENTS
!
!NOTES
!------------------------------------------------------------------------
!PUBLIC FUNCTIONS
!   Fn'Ordmap'GE$($map(), key$) - rtn value for key >= key$  - ordmap(varstr;varstr)
!   Fn'OrdmapX'GE$($map(), key$) - rtn value for key >= key$ - ordmap(varstr;varx)
!   Fn'OrdmapM'GE$($map(), key$) - rtn value for key >= key$  - ordmapm(varstr;varstr)
!   Fn'OrdmapMX'GE$($map(), key$) - rtn value for key >= key$ - ordmapm(varstr;varx)
!   Fn'Ordmap'LE$($map(), key$) - rtn value for key <= key$  - ordmap(varstr;varstr)
!   Fn'OrdmapX'LE$($map(), key$) - rtn value for key <= key$ - ordmap(varstr;varx)
!   Fn'OrdmapM'LE$($map(), key$) - rtn value for key <= key$  - ordmapm(varstr;varstr)
!   Fn'OrdmapMX'LE$($map(), key$) - rtn value for key <= key$ - ordmapm(varstr;varx)
!------------------------------------------------------------------------
! Keywords: ordmap iter
!------------------------------------------------------------------------


!*****************************************************************************
! ORDMAP(varstr;varstr) variations ******************************************
!*****************************************************************************


!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match >= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'Ordmap'GE$($map() as ordmap(varstr;varstr), key$ as s0) as s0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
EndFunction

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match <= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'Ordmap'LE$($map() as ordmap(varstr;varstr), key$ as s0) as s0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach'reverse $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
EndFunction

!*****************************************************************************
! ORDMAP(varstr;varx) variations *********************************************
!*****************************************************************************


!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match >= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapX'GE$($map() as ordmap(varstr;varx), key$ as s0) as x0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
EndFunction

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match <= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapX'LE$($map() as ordmap(varstr;varstr), key$ as s0) as x0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach'reverse $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
EndFunction


!*****************************************************************************
! ORDMAPM(varstr;varstr) variations ******************************************
!*****************************************************************************

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match >= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapM'GE$($map() as ordmapm(varstr;varstr), key$ as s0) as s0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
    
EndFunction

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match <= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapM'LE$($map() as ordmapm(varstr;varstr), key$ as s0) as s0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach'reverse $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
    
EndFunction

!*****************************************************************************
! ORDMAPM(varstr;varx) variations ********************************************
!*****************************************************************************

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match >= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapMX'GE$($map() as ordmapm(varstr;varx), key$ as s0) as x0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
    
EndFunction

!---------------------------------------------------------------------
!Function:
!   Return value from ordered map based on a match <= specified key
!Params:
!   $map()  [in, byref] - ordmap(varstr;varstr)
!   key$ (str) [in/out] - reference key on input, updated on output
!Returns:
!   value from map with key >= key$
!Globals:
!Notes:
!---------------------------------------------------------------------
Function Fn'OrdmapMX'LE$($map() as ordmapm(varstr;varx), key$ as s0) as x0

    map1 key2$,s,0, .NULL 

    .fn = .NULL 
    
    foreach'reverse $$i in $map(key$)
        .fn = $$i
        key2$ = .key($$i)
        exit
    next $$i
    
    xputarg @key$=key2$
    trace.print (99,"ordmap") ABC_CURRENT_ROUTINE$, key$, key2$, .fn
    
EndFunction