ArraySTF-Node

Defines node type arraystf_node_t which can be stored in an array of type arraystf_t.  Defines also the internal node type arraystf_mwaybranch_t which is used in the implementation of arraystf_t.

Summary
ArraySTF-NodeDefines node type arraystf_node_t which can be stored in an array of type arraystf_t.
CopyrightThis program is free software.
Files
C-kern/api/ds/inmem/node/arraystf_node.hHeader file ArraySTF-Node
Types
struct arraystf_node_tExport arraystf_node_t.
struct arraystf_mwaybranch_tExports <arraystf_mwaybranch_t>i.
struct arraystf_unode_tExport arraystf_unode_t.
arraystf_node_tGeneric user node type stored by arraystf_t.
addrMemory start address of binary/string key.
sizeLength of key in memory in bytes.
lifetime
arraystf_node_INITStatic initializer with parameter length in bytes and address of key.
arraystf_node_INIT_CSTRStatic initializer with parameter cstr referencing a “constant string”.
conversion
stringcast_arraystfnodeCast string_t into arraystf_node_t.
generic
arraystf_node_EMBEDAllows to embed members of arraystf_node_t into another structure.
arraystf_mwaybranch_tInternal node to implement a multiway trie.
childA 4-way array of child nodes.
offsetMemory offset of first data byte of key used to branch.
shiftIndex of bit of key data byte at position offset used to branch.
usedThe number of entries in child which are not 0.
lifetime
init_arraystfmwaybranchInitializes a new branch node.
query
childindex_arraystfmwaybranchDetermines the index into the internal array arraystf_mwaybranch_t.childs.
change
setchild_arraystfmwaybranchChanges entries in arry arraystf_mwaybranch_t.child.
query
branch_arraystfunodeGets pointer to value arraystf_mwaybranch_t.
node_arraystfunodeGets pointer to value arraystf_node_t.
isbranchtype_arraystfunodeReturns true in case node is pointer to arraystf_mwaybranch_t.
conversion
nodecast_arraystfunodeCast arraystf_node_t into arraystf_unode_t.
branchcast_arraystfunodeCasts pointer to arraystf_mwaybranch_t into pointer to arraystf_unode_t.
inline implementation
arraystf_node_t
stringcast_arraystfnodeImplements arraystf_node_t.stringcast_arraystfnode.
arraystf_mwaybranch_t
childindex_arraystfmwaybranchImplements arraystf_mwaybranch_t.childindex_arraystfmwaybranch.
init_arraystfmwaybranchImplements arraystf_mwaybranch_t.init_arraystfmwaybranch.
setchild_arraystfmwaybranchImplements arraystf_mwaybranch_t.setchild_arraystfmwaybranch.
arraystf_unode_t
branch_arraystfunodeImplements <arraystf_unode_t.branch_arraystfunode>.
branchcast_arraystfunodeImplements <arraystf_unode_t.branchcast_arraystfunode>.
isbranchtype_arraystfunodeImplements <arraystf_unode_t.isbranchtype_arraystfunode>.
node_arraystfunodeImplements <arraystf_unode_t.node_arraystfunode>.
nodecast_arraystfunodeImplements <arraystf_unode_t.nodecast_arraystfunode>.

Copyright

This program is free software.  You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

Author

© 2011 Jörg Seebohn

Files

C-kern/api/ds/inmem/node/arraystf_node.h

Header file ArraySTF-Node

Types

struct arraystf_node_t

typedef struct arraystf_node_t arraystf_node_t

Export arraystf_node_t.  User supplied (external) type.

struct arraystf_mwaybranch_t

typedef struct arraystf_mwaybranch_t arraystf_mwaybranch_t

Exports <arraystf_mwaybranch_t>i.  Internal node type.

struct arraystf_unode_t

Export arraystf_unode_t.  Either internal or external type.

arraystf_node_t

struct arraystf_node_t

Generic user node type stored by arraystf_t.  See also string_t.

Summary
addrMemory start address of binary/string key.
sizeLength of key in memory in bytes.
lifetime
arraystf_node_INITStatic initializer with parameter length in bytes and address of key.
arraystf_node_INIT_CSTRStatic initializer with parameter cstr referencing a “constant string”.
conversion
stringcast_arraystfnodeCast string_t into arraystf_node_t.
generic
arraystf_node_EMBEDAllows to embed members of arraystf_node_t into another structure.

addr

const uint8_t * addr

Memory start address of binary/string key.

size

size_t size

Length of key in memory in bytes.

lifetime

arraystf_node_INIT

#define arraystf_node_INIT(length,
key) { .addr = key, .size = length }

Static initializer with parameter length in bytes and address of key.

arraystf_node_INIT_CSTR

#define arraystf_node_INIT_CSTR(
   cstr
) { .addr = (const uint8_t*)(cstr), .size = (sizeof(cstr)?sizeof(cstr)-1:0) }

Static initializer with parameter cstr referencing a “constant string”.

conversion

stringcast_arraystfnode

arraystf_node_t * stringcast_arraystfnode(struct string_t *str)

Cast string_t into arraystf_node_t.

generic

arraystf_node_EMBED

#define arraystf_node_EMBED(
   name_addr,
   name_size
) const uint8_t * name_addr ; size_t name_size

Allows to embed members of arraystf_node_t into another structure.

Parameter

name_addrThe name of the embedded arraystf_node_t.addr member.
name_sizeThe name of the embedded arraystf_node_t.size member.

Your object must inherit or embed arraystf_node_t to be manageable by arraystf_t.  With macro arraystf_node_EMBED you can do

struct object_t {
   ... ;
   // declares: const uint8_t * keyaddr ; size_t keysize ;
   arraystf_node_EMBED(keyaddr, keysize)
}

// instead of
struct object_t {
   ... ;
   arraystf_node_t arraystfnode ;
}

arraystf_mwaybranch_t

struct arraystf_mwaybranch_t

Internal node to implement a multiway trie.  Currently this node type supports only a 4-way tree.

Summary
childA 4-way array of child nodes.
offsetMemory offset of first data byte of key used to branch.
shiftIndex of bit of key data byte at position offset used to branch.
usedThe number of entries in child which are not 0.
lifetime
init_arraystfmwaybranchInitializes a new branch node.
query
childindex_arraystfmwaybranchDetermines the index into the internal array arraystf_mwaybranch_t.childs.
change
setchild_arraystfmwaybranchChanges entries in arry arraystf_mwaybranch_t.child.
query
branch_arraystfunodeGets pointer to value arraystf_mwaybranch_t.
node_arraystfunodeGets pointer to value arraystf_node_t.
isbranchtype_arraystfunodeReturns true in case node is pointer to arraystf_mwaybranch_t.
conversion
nodecast_arraystfunodeCast arraystf_node_t into arraystf_unode_t.
branchcast_arraystfunodeCasts pointer to arraystf_mwaybranch_t into pointer to arraystf_unode_t.

child

arraystf_unode_t * child[4]

A 4-way array of child nodes.

offset

size_t offset

Memory offset of first data byte of key used to branch.  The key value at this offset is then shifted right according to value shift and masked to get an index into array child.

shift

uint8_t shift

Index of bit of key data byte at position offset used to branch.  The two bits at position shift and shift+1 are used as index into array child.  To get the correct child pointer use the following formula;

uint8_t               pos = key[offset] ; // array index
arraystf_mwaybranch_t * branch ;           // current branch node
branch->child[(pos >> branch->shift) & 0x03]

used

uint8_t used

The number of entries in child which are not 0.

lifetime

init_arraystfmwaybranch

void init_arraystfmwaybranch(/*out*/arraystf_mwaybranch_t *branch,
size_t offset,
unsigned shift,
size_t data1,
arraystf_unode_t *childnode1,
size_t data2,
arraystf_unode_t *childnode2)

Initializes a new branch node.  A branch node must point to at least two child nodes.  This is the reason two pointers and their corresponding index key has to be provided as parameter.

query

childindex_arraystfmwaybranch

unsigned childindex_arraystfmwaybranch(arraystf_mwaybranch_t *branch,
size_t data)

Determines the index into the internal array arraystf_mwaybranch_t.childs.  The index is calculated from parameter data which is the key value at offset arraystf_mwaybranch_t.offset.

change

setchild_arraystfmwaybranch

void setchild_arraystfmwaybranch(arraystf_mwaybranch_t *branch,
unsigned childindex,
arraystf_node_t *childnode)

Changes entries in arry arraystf_mwaybranch_t.child.

query

branch_arraystfunode

arraystf_mwaybranch_t * branch_arraystfunode(arraystf_unode_t *node)

Gets pointer to value arraystf_mwaybranch_t.

node_arraystfunode

arraystf_node_t * node_arraystfunode(arraystf_unode_t *node)

Gets pointer to value arraystf_node_t.

isbranchtype_arraystfunode

int isbranchtype_arraystfunode(const arraystf_unode_t *node)

Returns true in case node is pointer to arraystf_mwaybranch_t.

conversion

nodecast_arraystfunode

static inline arraystf_unode_t * nodecast_arraystfunode(arraystf_node_t *node)

Cast arraystf_node_t into arraystf_unode_t.  You need to call this function to make isbranchtype_arraystfunode working properly.

branchcast_arraystfunode

static inline arraystf_unode_t * branchcast_arraystfunode(
   arraystf_mwaybranch_t *branch
)

Casts pointer to arraystf_mwaybranch_t into pointer to arraystf_unode_t.  You need to call this function to make isbranchtype_arraystfunode working properly.

inline implementation

Summary
arraystf_node_t
stringcast_arraystfnodeImplements arraystf_node_t.stringcast_arraystfnode.
arraystf_mwaybranch_t
childindex_arraystfmwaybranchImplements arraystf_mwaybranch_t.childindex_arraystfmwaybranch.
init_arraystfmwaybranchImplements arraystf_mwaybranch_t.init_arraystfmwaybranch.
setchild_arraystfmwaybranchImplements arraystf_mwaybranch_t.setchild_arraystfmwaybranch.
arraystf_unode_t
branch_arraystfunodeImplements <arraystf_unode_t.branch_arraystfunode>.
branchcast_arraystfunodeImplements <arraystf_unode_t.branchcast_arraystfunode>.
isbranchtype_arraystfunodeImplements <arraystf_unode_t.isbranchtype_arraystfunode>.
node_arraystfunodeImplements <arraystf_unode_t.node_arraystfunode>.
nodecast_arraystfunodeImplements <arraystf_unode_t.nodecast_arraystfunode>.

arraystf_node_t

stringcast_arraystfnode

#define stringcast_arraystfnode(
   str
) ( __extension__ ({ struct string_t * _str1 = (str) ; (arraystf_node_t*) (_str1) ; }))

Implements arraystf_node_t.stringcast_arraystfnode.

arraystf_mwaybranch_t

childindex_arraystfmwaybranch

#define childindex_arraystfmwaybranch(
   branch,
   data
) (0x03u & ((data) >> (branch)->shift))

Implements arraystf_mwaybranch_t.childindex_arraystfmwaybranch.

init_arraystfmwaybranch

#define init_arraystfmwaybranch(
   branch,
   _offset,
   _shift,
   data1,
   childnode1,
   data2,
   childnode2
) do { memset((branch)->child, 0, sizeof((branch)->child)) ; (branch)->child[0x03u & ((data1) >> (_shift))] = childnode1 ; (branch)->child[0x03u & ((data2) >> (_shift))] = childnode2 ; (branch)->offset = _offset ; (branch)->shift = (uint8_t) _shift ; (branch)->used = 2 ; } while(0)

Implements arraystf_mwaybranch_t.init_arraystfmwaybranch.

setchild_arraystfmwaybranch

#define setchild_arraystfmwaybranch(
   branch,
   childindex,
   childnode
) do { (branch)->child[childindex] = (childnode) ; } while(0)

Implements arraystf_mwaybranch_t.setchild_arraystfmwaybranch.

arraystf_unode_t

branch_arraystfunode

#define branch_arraystfunode(
   node
) ( __extension__ ({ arraystf_unode_t * _node1 = (node) ; (arraystf_mwaybranch_t*) (0x01 ^ (uintptr_t)(_node1)); }))

Implements <arraystf_unode_t.branch_arraystfunode>.

branchcast_arraystfunode

static inline arraystf_unode_t * branchcast_arraystfunode(
   arraystf_mwaybranch_t *branch
)

Implements <arraystf_unode_t.branchcast_arraystfunode>.

isbranchtype_arraystfunode

#define isbranchtype_arraystfunode(
   node
) ( __extension__ ({ const arraystf_unode_t * _node3 = (node) ; ((uintptr_t)(_node3) & 0x01) ; }))

Implements <arraystf_unode_t.isbranchtype_arraystfunode>.

node_arraystfunode

#define node_arraystfunode(
   node
) ( __extension__ ({ arraystf_unode_t * _node2 = (node) ; (arraystf_node_t*) _node2 ; }))

Implements <arraystf_unode_t.node_arraystfunode>.

nodecast_arraystfunode

static inline arraystf_unode_t * nodecast_arraystfunode(arraystf_node_t *node)

Implements <arraystf_unode_t.nodecast_arraystfunode>.

struct arraystf_node_t
Generic user node type stored by arraystf_t.
Defines node type arraystf_node_t which can be stored in an array of type arraystf_t.
typedef struct arraystf_node_t arraystf_node_t
Export arraystf_node_t.
typedef struct arraystf_mwaybranch_t arraystf_mwaybranch_t
Exports <arraystf_mwaybranch_t>i.
const uint8_t * addr
Memory start address of binary/string key.
size_t size
Length of key in memory in bytes.
#define arraystf_node_INIT(length,
key) { .addr = key, .size = length }
Static initializer with parameter length in bytes and address of key.
#define arraystf_node_INIT_CSTR(
   cstr
) { .addr = (const uint8_t*)(cstr), .size = (sizeof(cstr)?sizeof(cstr)-1:0) }
Static initializer with parameter cstr referencing a “constant string”.
arraystf_node_t * stringcast_arraystfnode(struct string_t *str)
Cast string_t into arraystf_node_t.
#define arraystf_node_EMBED(
   name_addr,
   name_size
) const uint8_t * name_addr ; size_t name_size
Allows to embed members of arraystf_node_t into another structure.
struct arraystf_mwaybranch_t
Internal node to implement a multiway trie.
arraystf_unode_t * child[4]
A 4-way array of child nodes.
size_t offset
Memory offset of first data byte of key used to branch.
uint8_t shift
Index of bit of key data byte at position offset used to branch.
uint8_t used
The number of entries in child which are not 0.
void init_arraystfmwaybranch(/*out*/arraystf_mwaybranch_t *branch,
size_t offset,
unsigned shift,
size_t data1,
arraystf_unode_t *childnode1,
size_t data2,
arraystf_unode_t *childnode2)
Initializes a new branch node.
unsigned childindex_arraystfmwaybranch(arraystf_mwaybranch_t *branch,
size_t data)
Determines the index into the internal array arraystf_mwaybranch_t.childs.
void setchild_arraystfmwaybranch(arraystf_mwaybranch_t *branch,
unsigned childindex,
arraystf_node_t *childnode)
Changes entries in arry arraystf_mwaybranch_t.child.
arraystf_mwaybranch_t * branch_arraystfunode(arraystf_unode_t *node)
Gets pointer to value arraystf_mwaybranch_t.
arraystf_node_t * node_arraystfunode(arraystf_unode_t *node)
Gets pointer to value arraystf_node_t.
int isbranchtype_arraystfunode(const arraystf_unode_t *node)
Returns true in case node is pointer to arraystf_mwaybranch_t.
static inline arraystf_unode_t * nodecast_arraystfunode(arraystf_node_t *node)
Cast arraystf_node_t into arraystf_unode_t.
static inline arraystf_unode_t * branchcast_arraystfunode(
   arraystf_mwaybranch_t *branch
)
Casts pointer to arraystf_mwaybranch_t into pointer to arraystf_unode_t.
#define stringcast_arraystfnode(
   str
) ( __extension__ ({ struct string_t * _str1 = (str) ; (arraystf_node_t*) (_str1) ; }))
Implements arraystf_node_t.stringcast_arraystfnode.
#define childindex_arraystfmwaybranch(
   branch,
   data
) (0x03u & ((data) >> (branch)->shift))
Implements arraystf_mwaybranch_t.childindex_arraystfmwaybranch.
#define init_arraystfmwaybranch(
   branch,
   _offset,
   _shift,
   data1,
   childnode1,
   data2,
   childnode2
) do { memset((branch)->child, 0, sizeof((branch)->child)) ; (branch)->child[0x03u & ((data1) >> (_shift))] = childnode1 ; (branch)->child[0x03u & ((data2) >> (_shift))] = childnode2 ; (branch)->offset = _offset ; (branch)->shift = (uint8_t) _shift ; (branch)->used = 2 ; } while(0)
Implements arraystf_mwaybranch_t.init_arraystfmwaybranch.
#define setchild_arraystfmwaybranch(
   branch,
   childindex,
   childnode
) do { (branch)->child[childindex] = (childnode) ; } while(0)
Implements arraystf_mwaybranch_t.setchild_arraystfmwaybranch.
#define branch_arraystfunode(
   node
) ( __extension__ ({ arraystf_unode_t * _node1 = (node) ; (arraystf_mwaybranch_t*) (0x01 ^ (uintptr_t)(_node1)); }))
Implements arraystf_unode_t.branch_arraystfunode.
static inline arraystf_unode_t * branchcast_arraystfunode(
   arraystf_mwaybranch_t *branch
)
Implements arraystf_unode_t.branchcast_arraystfunode.
#define isbranchtype_arraystfunode(
   node
) ( __extension__ ({ const arraystf_unode_t * _node3 = (node) ; ((uintptr_t)(_node3) & 0x01) ; }))
Implements arraystf_unode_t.isbranchtype_arraystfunode.
#define node_arraystfunode(
   node
) ( __extension__ ({ arraystf_unode_t * _node2 = (node) ; (arraystf_node_t*) _node2 ; }))
Implements arraystf_unode_t.node_arraystfunode.
static inline arraystf_unode_t * nodecast_arraystfunode(arraystf_node_t *node)
Implements arraystf_unode_t.nodecast_arraystfunode.
Close