sasstringbtreeenum.h File Reference

An enumeration over a Shared Address Space, C String BTree index for shared memory multi-thread/multi-core applications. More...

`#include "sastype.h"`
`#include "sasstringbtree.h"`

Go to the source code of this file.

## Typedefs

typedef void * | SASStringBTreeEnum_t
| Handle to an instance of String BTree Enumeration. More...

## Functions

__C__ SASStringBTreeEnum_t | SASStringBTreeEnumCreate (SASStringBTree_t btree)
| Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a StringBtree or name Context. More...
__C__ SASStringBTreeEnum_t | SASStringBTreeEnumCreateStartAt (SASStringBTree_t btree, char *start_key)
| Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a StringBtree or name Context, starting at a specific key value. More...
__C__ void | SASStringBTreeEnumDestroy (SASStringBTreeEnum_t sbtenum)
| Destroy an instance of SASStringBTreeEnum_t enumeration. More...
__C__ int | SASStringBTreeEnumHasMore (SASStringBTreeEnum_t sbtenum)
| Return status of a SASStringBTreeEnum_t enumeration. More...
__C__ long | SASStringBTreeEnumCount (SASStringBTreeEnum_t sbtenum)
| Return number of entries a SASStringBTreeEnum_t enumeration contains. More...
__C__ char * | SASStringBTreeEnumCurrent (SASStringBTreeEnum_t sbtenum)
| Return the C string pointer for the current enumeration key value. More...
__C__ void * | SASStringBTreeEnumNext (SASStringBTreeEnum_t sbtenum)
| Move the enumeration to the next String BTree key entry and return the associated address value. More...
__C__ void * | SASStringBTreeEnumNext_nolock (SASStringBTreeEnum_t sbtenum)
| Move the enumeration to the next String BTree key entry and return the associated address value. More...

## Detailed Description

An enumeration over a Shared Address Space, C String BTree index for shared memory multi-thread/multi-core applications.

Create enumerations that manage iterations over the keys and associated values of sasstringbtree.h. Iteration is in key order from minimum to maximum contained keys.

SASStringBTreeEnum_t senum;
senum = SASStringBTreeEnumCreate (stringBTree);
if (senum)
{
while (SASStringBTreeEnumHasMore (senum))
{
void *addr_val;
char *key;
addr_val = SASStringBTreeEnumNext (senum);
if (addr_val)
{
key = SASStringBTreeEnumCurrent (senum)
printf ("Key<%s> Value<%p>\n", key, addr_value);
}
}
SASStringBTreeEnumDestroy (senum);
}
SASStringBTreeEnumDestroy
__C__ void SASStringBTreeEnumDestroy(SASStringBTreeEnum_t sbtenum)
Destroy an instance of SASStringBTreeEnum_t enumeration.
SASStringBTreeEnumCreate
__C__ SASStringBTreeEnum_t SASStringBTreeEnumCreate(SASStringBTree_t btree)
Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a String...
SASStringBTreeEnumHasMore
__C__ int SASStringBTreeEnumHasMore(SASStringBTreeEnum_t sbtenum)
Return status of a SASStringBTreeEnum_t enumeration.
SASStringBTreeEnum_t
void * SASStringBTreeEnum_t
Handle to an instance of String BTree Enumeration.
Definition: sasstringbtreeenum.h:113
SASStringBTreeEnumCurrent
__C__ char * SASStringBTreeEnumCurrent(SASStringBTreeEnum_t sbtenum)
Return the C string pointer for the current enumeration key value.
SASStringBTreeEnumNext
__C__ void * SASStringBTreeEnumNext(SASStringBTreeEnum_t sbtenum)
Move the enumeration to the next String BTree key entry and return the associated address value.

There is an option (via SASStringBTreeEnumCreateStartAt) to create a enumeration starting at a key value any where between the minimum and maximum keys.

SASStringBTreeEnum_t senum;
senum = SASStringBTreeEnumCreateStartAt (stringBTree, "/mykeys/");
if (senum)
{
while (SASStringBTreeEnumHasMore (senum))
{
void *addr_val;
char *key;
addr_val = SASStringBTreeEnumNext (senum);
if (addr_val)
{
key = SASStringBTreeEnumCurrent (senum)
printf ("Key<%s> Value<%p>\n", key, addr_value);
}
}
SASStringBTreeEnumDestroy (senum);
}
SASStringBTreeEnumCreateStartAt
__C__ SASStringBTreeEnum_t SASStringBTreeEnumCreateStartAt(SASStringBTree_t btree, char *start_key)
Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a String...

It is simple to iterate over a subrange of the BTree by checking for a stop_key and exiting the SASStringBTreeEnumNext search when the stop value is met or exceeded.

SASStringBTreeEnum_t senum;
myprefix = "/mykeys/";
mystop = "/mykeys0"; // ASCII '0' is the char after '/'
senum = SASStringBTreeEnumCreateStartAt (stringBTree, myprefix);
if (senum)
{
while (SASStringBTreeEnumHasMore (senum))
{
void *addr_val;
char *key;
addr_val = SASStringBTreeEnumNext (senum);
if (addr_val)
{
key = SASStringBTreeEnumCurrent (senum)
// check for stop value
if (strcmp(key, mystop) >= 0)
break;
printf ("Key<%s> Value<%p>\n", key, addr_value);
}
}
SASStringBTreeEnumDestroy (senum);
}

Todo:
  Create SASStringBTreeEnumCreateBetween SASStringBTreeEnumCreateStopBefore APIs

## Typedef Documentation

## SASStringBTreeEnum_t

typedef void* SASStringBTreeEnum_t

Handle to an instance of String BTree Enumeration.

Enumerations are allocated from dynamic (malloc) storage and can not be shared with other processes. This allows multiple threads, each with their own enumeration, to safely iterate over a shared String BTree index.

## Function Documentation

## SASStringBTreeEnumCount()

__C__ long SASStringBTreeEnumCount | ( | SASStringBTreeEnum_t | sbtenum | ) |

Return number of entries a SASStringBTreeEnum_t enumeration contains.

Report the number of entries associated with this enumeration. The count is derived from the underlying String BTree index when the enumeration was created and may not be accurate due to changes in the underly SASStringBTreeEnum_t. The count is decremented for each successful call to SASStringBTreeEnumNext, but may be reset if the underlying BTree has changed.

Note
  this value will not be accurate for StartAt enumeration until we implement a "count entries left from current" operation on the base SASStringBTree_t.

      @param sbtenum String BTree enumeration.
      @return number of the entries remaining in this enumeration.

## SASStringBTreeEnumCreate()

__C__ SASStringBTreeEnum_t SASStringBTreeEnumCreate | ( | SASStringBTree_t | btree | ) |

Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a StringBtree or name Context.

Create String BTree enumeration for the "C" string name index of specific BTree. The program can then use the SASStringBTreeEnum API to iterate over this name space and retrieve the associated address values.

    @param btree String BTree to create the name enumeration for.
    @return SASStringBTreeEnum_t enumeration pointer,
    NULL is returned for failure cases.

## SASStringBTreeEnumCreateStartAt()

__C__ SASStringBTreeEnum_t SASStringBTreeEnumCreateStartAt | ( | SASStringBTree_t | btree,
|  | char * | start_key
| ) |  |

Create a SASStringBTreeEnum_t enumeration that can be used to iterate over the name space of a StringBtree or name Context, starting at a specific key value.

Create String BTree enumeration for the "C" string name index of specific BTree. The program can then use the SASStringBTreeEnum API to iterate over this name space and

    @param btree String BTree to create the enumeration over
    @param start_key Starting key for iteration.
    @return SASStringBTreeEnum_t enumeration pointer,
    NULL is returned for failure cases (including start_key > max_key).

## SASStringBTreeEnumCurrent()

__C__ char * SASStringBTreeEnumCurrent | ( | SASStringBTreeEnum_t | sbtenum | ) |

Return the C string pointer for the current enumeration key value.

Note
  This may be a direct pointer into the internal storage of the SASStringBTree_t and should not be modified by the application.

      @param sbtenum String BTree enumeration.
      @return Pointer to the C string value of the current key position.

## SASStringBTreeEnumDestroy()

__C__ void SASStringBTreeEnumDestroy | ( | SASStringBTreeEnum_t | sbtenum | ) |

Destroy an instance of SASStringBTreeEnum_t enumeration.

    @param sbtenum String BTree enumeration to be destroyed.

## SASStringBTreeEnumHasMore()

__C__ int SASStringBTreeEnumHasMore | ( | SASStringBTreeEnum_t | sbtenum | ) |

Return status of a SASStringBTreeEnum_t enumeration.

    @param sbtenum String BTree enumeration.
    @return True if this enumeration has more entries.

## SASStringBTreeEnumNext()

__C__ void * SASStringBTreeEnumNext | ( | SASStringBTreeEnum_t | sbtenum | ) |

Move the enumeration to the next String BTree key entry and return the associated address value.

The corresponding C string key value can be obtained via SASStringBTreeEnumCurrent()

    @param sbtenum String BTree enumeration.
    @return the address value associated for the next String BTree enumeration.

## SASStringBTreeEnumNext_nolock()

__C__ void * SASStringBTreeEnumNext_nolock | ( | SASStringBTreeEnum_t | sbtenum | ) |

Move the enumeration to the next String BTree key entry and return the associated address value.

The corresponding C string key value can be obtained via SASStringBTreeEnumCurrent()

This nolock form should only be used when the referenced SASStringBTreeEnum_t is known to be locked by the application or contained within a larger structure with a controlling lock.

      @param sbtenum String BTree enumeration.
      @return the address value associated for the next String BTree enumeration.