apiPWPUtils.cxx

Go to the documentation of this file.

/****************************************************************************
 *
 * Pointwise Plugin utility functions
 *
 * (C) 2021 Cadence Design Systems, Inc. All rights reserved worldwide.
 *
 ***************************************************************************/
 
#include <map>
#include <sstream>
#include <string>
#include <utility>
 
#include <string.h>
#include "apiPWP.h"
#include "apiPWPUtils.h"
 
typedef std::string PwuString;
 
 
/*------------------------------------*/
static PWU_RTITEM*
PwuFindAPI(const char api[], PWP_UINT32 cnt)
{
    PWU_RTITEM *ret = 0;
    if (api && api[0]) {
        PWP_UINT32 ii;
        for (ii=0; ii < cnt; ++ii) {
            if (0 == strcmp(pwpRtItem[ii].apiInfo.name, api)) {
                ret = &(pwpRtItem[ii]);
                break;
            }
        }
    }
    return ret;
}
 
/**************************************/
PWU_RTITEM*
PwuFindTotalAPI(const char api[])
{
    return PwuFindAPI(api, totalApiCnt);
}
 
/**************************************/
PWU_RTITEM*
PwuFindPublishedAPI(const char api[])
{
    return PwuFindAPI(api, publishedApiCnt);
}
 
/**************************************/
PWP_MESSAGECB
PwuFindApiMsgCB(const char api[])
{
    PWU_RTITEM *pApiInfo = PwuFindTotalAPI(api);
    return (pApiInfo? pApiInfo->msgCB : 0);
}
 
 
//***********************************************************************
//***********************************************************************
//        send a generic message back to framework
//***********************************************************************
//***********************************************************************
 
/**************************************/
PWP_UINT32
PwuSendMsg(const char api[], PWP_ENUM_MSGID id, void *pMsg)
{
    PWP_UINT32 ret = 0;
    PWP_MESSAGECB msgCB = PwuFindApiMsgCB(api);
    if (!msgCB) {
        // api does NOT have a CB, use default CB
        msgCB = PwuFindApiMsgCB(PWP_MESSAGECB_DEFAULT);
    }
 
    // invoke CB if defined
    if (msgCB) {
        ret = msgCB(api, id, pMsg);
    }
 
    // always invoke spy CB if defined. ignore ret.
    msgCB = PwuFindApiMsgCB(PWP_MESSAGECB_SPY);
    if (msgCB) {
        msgCB(api, id, pMsg);
    }
    return ret;
}
 
//***********************************************************************
//***********************************************************************
//        bundle and send a text message back to framework
//***********************************************************************
//***********************************************************************
 
/*------------------------------------*/
static void
PwuSendTextMsg(const char api[], PWP_ENUM_MSGID id, const char txt[], PWP_UINT32 code)
{
    PWP_MSG_TEXT msg;
    msg.code = code;
    msg.text = (txt ? txt : "");
    PwuSendMsg(api, id, (void*)&msg);
}
 
/**************************************/
void
PwuSendDebugMsg(const char api[], const char txt[], PWP_UINT32 code)
{
    PwuSendTextMsg(api, PWP_MSGID_DEBUG, txt, code);
}
 
/**************************************/
void
PwuSendInfoMsg(const char api[], const char txt[], PWP_UINT32 code)
{
    PwuSendTextMsg(api, PWP_MSGID_INFO, txt, code);
}
 
/**************************************/
void
PwuSendWarningMsg(const char api[], const char txt[], PWP_UINT32 code)
{
    PwuSendTextMsg(api, PWP_MSGID_WARNING, txt, code);
}
 
/**************************************/
void
PwuSendErrorMsg(const char api[], const char txt[], PWP_UINT32 code)
{
    PwuSendTextMsg(api, PWP_MSGID_ERROR, txt, code);
}
 
//***********************************************************************
//***********************************************************************
//        bundle and send a progress message back to framework
//***********************************************************************
//***********************************************************************
 
/*------------------------------------*/
static PWP_UINT32
PwuSendProgressMsg (const char api[], PWP_ENUM_MSGID id, PWP_UINT32 value)
{
    PWP_MSG_PROGRESS msg;
    msg.value = value;
    return PwuSendMsg(api, id, (void*)&msg);
}
 
/**************************************/
PWP_BOOL
PwuProgressBegin (const char api[], PWP_UINT32 totalSteps)
{
    //For Message id         msg.value =        return
    //--------------------   ----------------   ---------------------
    //PWP_MSGID_PROGBEGIN    total steps        >0 if op can continue
    return PwuSendProgressMsg (api, PWP_MSGID_PROGBEGIN, totalSteps)
             ? PWP_TRUE : PWP_FALSE;
}
 
/**************************************/
void
PwuProgressEnd (const char api[], PWP_BOOL ok)
{
    //For Message id         msg.value =        return
    //--------------------   ----------------   ---------------------
    //PWP_MSGID_PROGEND      0=fail/>0=ok       nothing
    PwuSendProgressMsg (api, PWP_MSGID_PROGEND, (ok ? 1 : 0));
}
 
/**************************************/
PWP_BOOL
PwuProgressStatus (const char api[], PWP_UINT32 complete, PWP_UINT32 total)
{
    //For Message id         msg.value =        return
    //--------------------   ----------------   ---------------------
    //PWP_MSGID_PROGSTATUS   0-100              >0 if op can continue
    PWP_UINT32 percent = 100;
    if ((0 != total) && (complete < total)) {
        percent = (PWP_UINT32)((PWP_FLOAT)100 * (PWP_FLOAT)complete
                                              / (PWP_FLOAT)total);
    }
    return PwuSendProgressMsg (api, PWP_MSGID_PROGSTATUS, percent)
             ? PWP_TRUE : PWP_FALSE;
}
 
/**************************************/
PWP_BOOL
PwuProgressNextStep (const char api[])
{
    //For Message id         msg.value =        return
    //--------------------   ----------------   ---------------------
    //PWP_MSGID_PROGSTATUS   -1                 >0 if op can continue
    return PwuSendProgressMsg (api, PWP_MSGID_PROGSTATUS, (PWP_UINT32)-1)
             ? PWP_TRUE : PWP_FALSE;
}
 
/**************************************/
PWP_BOOL
PwuProgressQuit (const char api[])
{
    //For Message id         msg.value =        return
    //--------------------   ----------------   ---------------------
    //PWP_MSGID_PROGQUIT     not used           >0 if op canceled
    return PwuSendProgressMsg (api, PWP_MSGID_PROGQUIT, 0)
             ? PWP_TRUE : PWP_FALSE;
}
 
 
//***********************************************************************
//***********************************************************************
//          Endian Data I/O helper functions
//***********************************************************************
//***********************************************************************
 
/**************************************/
PWP_ENDIANNESS
PwuGetOsEndianness(void)
{
    union endian_test_t {
        PWP_UINT32    uint;
        unsigned char ch[sizeof(PWP_UINT32)];
    }
    const etest = { 0xAABBCCDD };
    return (0xAA == etest.ch[0]) ? PWP_ENDIAN_BIG : PWP_ENDIAN_LITTLE;
}
 
 
const void*
PwuApplyEndianness(PWP_ENDIANNESS endianness, const void *buf, size_t size)
{
#   define ENDIAN_MAXSIZE 32
    const void *ret = 0;
    // buf size must be 1 or even
    if (0 == buf) {
        // bad
    }
    else if (1 == size) {
        ret = buf; // just write the byte
    }
    else if (!(size & 0x1) && (ENDIAN_MAXSIZE >= size)) {
        PWP_ENDIANNESS osEndianness = PwuGetOsEndianness();
        switch (endianness) {
            case PWP_ENDIAN_LITTLE:
            case PWP_ENDIAN_BIG:
                if (osEndianness == endianness) {
                    // no need to do swap
                    ret = buf;
                    break;
                }
                // drop through
 
            case PWP_ENDIAN_FOREIGN: {
                // must swap data order
                static unsigned char tmpBuf[ENDIAN_MAXSIZE];
                const char *cbuf = (const char *)buf;
                size_t hNdx = 0;
                size_t tNdx = size-1;
                while (hNdx < tNdx) {
                    tmpBuf[hNdx]   = cbuf[tNdx];
                    tmpBuf[tNdx--] = cbuf[hNdx++];
                }
                // ret only valid until next call to PwuApplyEndianness()
                ret = tmpBuf;
                break; }
 
            case PWP_ENDIAN_NATIVE:
                // no need to do swap
                ret = buf;
                break;
 
            case PWP_ENDIAN_ERROR:
            default:
                // huh?
                break;
        }
    }
    return ret;
#   undef ENDIAN_MAXSIZE
}
 
 
//***********************************************************************
//***********************************************************************
//          unformatted file I/O helper functions
//***********************************************************************
//***********************************************************************
 
#define STAT_MASK    ((PWP_UINT32)(0xFFFFFFF0))
#define STAT_BASE    ((PWP_UINT32)(0x9ABCDEF0))
#define STAT_OPEN    ((PWP_UINT32)(STAT_BASE | 0x1))
#define STAT_CLOSED  ((PWP_UINT32)(STAT_BASE | 0x0))
 
#define UDATA_ISINIT(pUD)   (STAT_BASE == (STAT_MASK & (pUD)->status))
#define UDATA_ISOPEN(pUD)   ((pUD) && (STAT_OPEN == (pUD)->status) && (pUD)->fp && !(pUD)->hadError)
#define UDATA_INREC(pUD)    (UDATA_ISOPEN(pUD) && (pUD)->inRec)
#define UDATA_ISCLOSED(pUD) ((pUD) && (STAT_CLOSED == (pUD)->status))
 
 
/*------------------------------------*/
static PWP_BOOL
unfUDataInit(PWU_UNFDATA *pUData)
{
    if (pUData) {
        memset(pUData, 0, sizeof(PWU_UNFDATA));
        pUData->status = STAT_OPEN;
        pUData->endianness = PWP_ENDIAN_NATIVE;
    }
    return pUData ? PWP_TRUE : PWP_FALSE;
}
 
/*------------------------------------*/
static PWP_BOOL
unfHdrLenWrite(PWU_UNFDATA *pUData)
{
    PWP_BOOL ret = PWP_FALSE;
    if (UDATA_INREC(pUData)) {
        const void *p = PwuApplyEndianness(pUData->endianness,
            &(pUData->recBytes), sizeof(pUData->recBytes));
        size_t cnt = pwpFileWrite(p, sizeof(pUData->recBytes), 1, pUData->fp);
        if (1 == cnt) {
            ret = PWP_TRUE;
        }
        if (!ret) {
            pUData->hadError = PWP_TRUE;
        }
    }
    return ret;
}
 
 
/***************************************************************************/
/***************************************************************************/
/*                        UNFORMATTED FORTRAN FILE UTILS                   */
/***************************************************************************/
/***************************************************************************/
 
/**************************************/
PWP_ENDIANNESS
PwuUnfFileSetEndianness (PWU_UNFDATA *pUData, PWP_ENDIANNESS endianness)
{
    PWP_ENDIANNESS ret = PWP_ENDIAN_ERROR;
    if (UDATA_ISOPEN(pUData) && (PWP_ENDIAN_ERROR != endianness)) {
        ret = pUData->endianness;
        pUData->endianness = endianness;
    }
    return ret;
}
 
/**************************************/
PWP_ENDIANNESS
PwuUnfFileGetEndianness (PWU_UNFDATA *pUData)
{
    return pUData ? pUData->endianness : PWP_ENDIAN_ERROR;
}
 
/**************************************/
PWP_BOOL
PwuUnfFileBegin(FILE *fp, PWU_UNFDATA *pUData)
{
    PWP_BOOL ret = PWP_FALSE;
    if (unfUDataInit(pUData) && fp) {
        pUData->fp = fp;
        ret = PWP_TRUE;
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfRecEnd(PWU_UNFDATA *pUData)
{
    PWP_BOOL ret = PWP_FALSE;
    if (0 == pUData) {
        // fail
    }
    else if (!UDATA_INREC(pUData)) {
        // silently ignore
        ret = PWP_TRUE;
    }
    else {
        if (!unfHdrLenWrite(pUData)) {
            // could not write rec len value to footer
        }
        else if (0 == pUData->fixedBytes) {
            // Not a fixed length record
            sysFILEPOS fPosSave;
            if (pwpFileGetpos(pUData->fp, &fPosSave)) {
                // could not save current file pos
            }
            else if (pwpFileSetpos(pUData->fp, &(pUData->fPos))) {
                // could not move pos to saved rec header location
            }
            else if (!unfHdrLenWrite(pUData)) {
                // could not write rec len value to header
            }
            else if (0 == pwpFileSetpos(pUData->fp, &fPosSave)) {
                // file pos restored to saved location
                ret = PWP_TRUE;
            }
        }
        else if (pUData->fixedBytes == pUData->recBytes) {
            // The fixed length record bytes match the actual bytes written!
            ret = PWP_TRUE;
        }
 
        if (ret) {
            // update running totals
            pUData->totRecBytes += pUData->recBytes;
            ++pUData->recCnt;
        }
        else {
            pUData->hadError = PWP_TRUE;
        }
 
        // clear for next rec
        pUData->inRec = PWP_FALSE;
    }
 
    // Do NOT reset pUData->recBytes here so that PwuUnfRecBytes() has access to
    // this record's byte count.
 
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfRecBegin(PWU_UNFDATA *pUData)
{
    PWP_BOOL ret = PWP_FALSE;
    if (UDATA_ISOPEN(pUData)) {
        // auto-close rec (if any)
        PwuUnfRecEnd(pUData);
        // PwuUnfRecEnd() does NOT reset recBytes.
        // We do not know the fixed record size.
        pUData->recBytes = pUData->fixedBytes = 0;
        // save current file pos. will write the final rec length later
        if (0 == pwpFileGetpos (pUData->fp, &(pUData->fPos))) {
            // must be true for call to unfHdrLenWrite()
            pUData->inRec = PWP_TRUE;
            // write dummy value... will set final value in PwuUnfRecEnd()
            ret = pUData->inRec = unfHdrLenWrite(pUData);
        }
        if (!ret) {
            pUData->hadError = PWP_TRUE;
        }
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfRecBeginFixed(PWU_UNFDATA *pUData, PWP_UINT32 bytes, PWP_UINT32 count)
{
    PWP_BOOL ret = PWP_FALSE;
    if (UDATA_ISOPEN(pUData)) {
        // auto-close rec (if any)
        PwuUnfRecEnd(pUData);
        // set recBytes for unfHdrLenWrite()
        // Caller provided the known (fixed) record size!
        pUData->recBytes = pUData->fixedBytes = bytes * count;
        // must be true for call to unfHdrLenWrite()
        pUData->inRec = PWP_TRUE;
        // write known recBytes value...
        ret = pUData->inRec = unfHdrLenWrite(pUData);
        // set recBytes back to zero to track actual bytes written
        pUData->recBytes = 0;
        if (!ret) {
            pUData->hadError = PWP_TRUE;
        }
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteArr(PWU_UNFDATA *pUData, const void *arr, size_t itemSize,
                  size_t itemCnt)
{
    PWP_BOOL ret = PWP_FALSE;
    if (UDATA_INREC(pUData)) {
        if (itemCnt == pwpFileWrite(arr, itemSize, itemCnt, pUData->fp)) {
            pUData->recBytes += (PWP_UINT32)(itemCnt * itemSize);
            ret = PWP_TRUE;
        }
    }
    if (!ret) {
        pUData->hadError = PWP_TRUE;
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteBuf(PWU_UNFDATA *pUData, const void *buf, size_t size)
{
    return PwuUnfRecWriteArr(pUData, buf, size, 1);
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteEndianBuf(PWU_UNFDATA *pUData, const void *buf, size_t size)
{
    const void *p = PwuApplyEndianness(pUData->endianness, buf, size);
    return PwuUnfRecWriteArr(pUData, p, size, 1);
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteINT(PWU_UNFDATA *pUData, PWP_INT val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteUINT(PWU_UNFDATA *pUData, PWP_UINT val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteINT8(PWU_UNFDATA *pUData, PWP_INT8 val)
{
    return PwuUnfRecWriteBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteUINT8(PWU_UNFDATA *pUData, PWP_UINT8 val)
{
    return PwuUnfRecWriteBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteINT16(PWU_UNFDATA *pUData, PWP_INT16 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteUINT16(PWU_UNFDATA *pUData, PWP_UINT16 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteINT32(PWU_UNFDATA *pUData, PWP_INT32 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteUINT32(PWU_UNFDATA *pUData, PWP_UINT32 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteINT64(PWU_UNFDATA *pUData, PWP_INT64 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteUINT64(PWU_UNFDATA *pUData, PWP_UINT64 val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteFLOAT(PWU_UNFDATA *pUData, PWP_FLOAT val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfRecWriteREAL(PWU_UNFDATA *pUData, PWP_REAL val)
{
    return PwuUnfRecWriteEndianBuf(pUData, &val, sizeof(val));
}
 
/**************************************/
PWP_BOOL
PwuUnfFileEnd(PWU_UNFDATA *pUData)
{
    PWP_BOOL ret = PWP_FALSE;
    if (pUData) {
        // make sure rec is closed
        PwuUnfRecEnd(pUData);
        pUData->fp = 0;
        pUData->status = STAT_CLOSED;
        ret = !pUData->hadError;
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuUnfHadError(PWU_UNFDATA *pUData)
{
    return UDATA_ISINIT(pUData) && pUData->hadError;
}
 
/**************************************/
PWP_UINT32
PwuUnfRecBytes(PWU_UNFDATA *pUData)
{
    return UDATA_ISINIT(pUData) ? pUData->recBytes : 0;
}
 
/**************************************/
PWP_UINT32
PwuUnfTotRecBytes(PWU_UNFDATA *pUData)
{
    return UDATA_ISINIT(pUData) ? pUData->totRecBytes : 0;
}
 
/**************************************/
PWP_UINT32
PwuUnfRecCount(PWU_UNFDATA *pUData)
{
    return UDATA_ISINIT(pUData) ? pUData->recCnt : 0;
}
 
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
 
/***************************************************************************/
static const char *
typeToString(PWP_ENUM_VALTYPE type)
{
    const char *ret = "Unknown";
    switch(type) {
    case PWP_VALTYPE_STRING:    ret = "String"; break;
    case PWP_VALTYPE_INT:       ret = "Int"; break;
    case PWP_VALTYPE_UINT:      ret = "UInt"; break;
    case PWP_VALTYPE_REAL:      ret = "Real"; break;
    case PWP_VALTYPE_ENUM:      ret = "Enum"; break;
    case PWP_VALTYPE_BOOL:      ret = "Bool"; break;
    case PWP_VALTYPE_SIZE: break; // silence compiler warning
    }
    return ret;
}
 
 
/***************************************************************************/
class NamedStrings {
 
    typedef std::map<PwuString, PwuString>          NameStrMap;
    typedef std::pair<NameStrMap::iterator, bool>   NameStrMapInsertRet;
 
public:
    NamedStrings() :
        data_()
    {
    }
    ~NamedStrings()
    {
    }
 
    void set(const PwuString &name, const PwuString &value) {
        NameStrMap::iterator it = data_.find(name);
        if (data_.end() != it) {
            // set existing value
            it->second = value;
        }
        else {
            // set new value
            data_.insert(NameStrMap::value_type(name, value));
        }
    }
 
    PwuString &
    get(const PwuString &name, PwuString &value, const PwuString &defVal,
            bool &isDefVal) {
        NameStrMap::const_iterator it = data_.find(name);
        if (data_.end() != it) {
            value = it->second; // return existing value
            isDefVal = false;
        }
        else {
            value = defVal; // return default value
            isDefVal = true;
        }
        return value;
    }
 
    PwuString &
    operator[](const PwuString &name) {
        return data_[name];
    }
 
    void erase(const PwuString &name) {
        NameStrMap::iterator it = data_.find(name);
        if (data_.end() != it) {
            // found it - erase it
            data_.erase(it);
        }
        // else not found - silently ignore
    }
 
    bool exists(const PwuString &name) {
        return (data_.end() != data_.find(name));
    }
 
protected:
    NameStrMap  data_;
};
 
static NamedStrings namedStrings;
 
 
/**************************************/
PwuString
PwuJoin(const PwuString &j1, const PwuString &j2, char sepChar = '.')
{
    PwuString res;
    if (j1.empty()) {
        res = j2;
    }
    else if (j2.empty()) {
        res = j1;
    }
    else { // both j1 and j2 are NOT empty
        bool j1EndsWithDot = (sepChar == j1[j1.size() - 1]);
        bool j2StartsWithDot = (sepChar == j2[0]);
        res = j1;
        if (j1EndsWithDot && j2StartsWithDot) {
            // j1. += [.]j2
            res.append(j2.begin() + 1, j2.end());
        }
        else if (j1EndsWithDot) {
            res.append(j2);      // j1. += j2
        }
        else if (j2StartsWithDot) {
            res.append(j2);      // j1 += .j2
        }
        else {
            res.append(1, sepChar); // j1 += .
            res.append(j2);      // j1 += j2
        }
    }
    return res;
}
 
/**************************************/
PwuString
PwuJoin(const PwuString &j1, const PwuString &j2, const PwuString &j3,
    char sepChar = '.')
{
    return PwuJoin(PwuJoin(j1, j2), j3, sepChar);
}
 
/**************************************/
PwuString
PwuJoin(const PwuString &j1, const PwuString &j2, const PwuString &j3,
    const PwuString &j4, char sepChar = '.')
{
    return PwuJoin(PwuJoin(j1, j2), PwuJoin(j3, j4), sepChar);
}
 
/**************************************/
static PwuString
PwuValueNamesGroup(const PwuString &rootGroup)
{
    // <rootGroup>.ValNames
    return PwuJoin(rootGroup, PWU_PUBLISH_NAMES_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnsGroup(const PwuString &rootGroup)
{
    // <rootGroup>.ValDefs
    return PwuJoin(rootGroup, PWU_PUBLISH_DEFNS_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnAttrGroup(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>
    return PwuJoin(PwuValueDefnsGroup(rootGroup), valName, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnNameKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_TYPE_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_NAME_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnTypeKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_TYPE_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_TYPE_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnAccessKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_ACCESS_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_ACCESS_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnDescKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_DESC_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_DESC_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnDefaultKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_DEFAULT_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_DEFAULT_STR, '.');
}
 
/**************************************/
static PwuString
PwuValueDefnRangeKey(const PwuString &rootGroup, const PwuString &valName)
{
    // <rootGroup>.ValDefs.<valName>.<PWU_VALUE_DEFN_RANGE_STR>
    return PwuJoin(PwuValueDefnAttrGroup(rootGroup, valName),
            PWU_VALUE_DEFN_RANGE_STR, '.');
}
 
/**************************************/
PWP_BOOL PwuAssignValue(const char group[], const char name[],
    const char value[], bool createIfNotExists)
{
    PWP_BOOL ret = PWP_FALSE;
    if (group && group[0] && name && name[0]) {
        PwuString key = PwuJoin(group, name);
        if (0 == value) {
            namedStrings.erase(key); // delete name/value pair!
            ret = PWP_TRUE;
        }
        else if (createIfNotExists || namedStrings.exists(key)) {
            namedStrings[key] = value;
            ret = PWP_TRUE;
        }
    }
    return ret;
}
 
/**************************************/
PWP_BOOL PwuAssignValueInt(const char group[], const char name[],
    PWP_INT value, bool createIfNotExists)
{
    std::ostringstream buf;
    buf << value << std::ends;
    return PwuAssignValue(group, name, buf.str().c_str(), createIfNotExists);
}
 
/**************************************/
PWP_BOOL PwuAssignValueUInt(const char group[], const char name[],
    PWP_UINT value, bool createIfNotExists)
{
    std::ostringstream buf;
    buf << value << std::ends;
    return PwuAssignValue(group, name, buf.str().c_str(), createIfNotExists);
}
 
/**************************************/
PWP_BOOL PwuAssignValueReal(const char group[], const char name[],
    PWP_REAL value, bool createIfNotExists)
{
    std::ostringstream buf;
    buf << value << std::ends;
    return PwuAssignValue(group, name, buf.str().c_str(), createIfNotExists);
}
 
/**************************************/
PWP_BOOL PwuAssignValueEnum(const char group[], const char name[],
    const char value[], bool createIfNotExists)
{
    return PwuAssignValue(group, name, value, createIfNotExists);
}
 
/**************************************/
PWP_BOOL PwuPublishValueDefinition(const char group[], const char name[],
    PWP_ENUM_VALTYPE type, const char value[], const char access[],
    const char desc[], const char range[])
{
    //  value definition attributes         value
    //  ----------------------------------  ---------
    //  <group>.ValNames                    += |<name>
    //  <group>.ValDefs.<name>.type          <type>
    //  <group>.ValDefs.<name>.access        <access>
    //  <group>.ValDefs.<name>.description   <desc>
    //  <group>.ValDefs.<name>.default       <value>
    //  <group>.ValDefs.<name>.range         <range>
    //
    PWP_BOOL ret = PWP_FALSE;
    if (group && group[0] && name && name[0]) {
        PwuString varDefKeyName = PwuValueDefnNameKey(group, name);
 
        // Check if "<group>.ValDefs.<name>.type" exists
        if (!namedStrings.exists(varDefKeyName)) {
            // name is a new name
            PwuString &varNames = namedStrings[PwuValueNamesGroup(group)];
            // Append name to the string ref'ed by varNames
            varNames = PwuJoin(varNames, name, '|');
        }
 
        PwuString varDefKeyType = PwuValueDefnTypeKey(group, name);
        PwuString varDefKeyAccess = PwuValueDefnAccessKey(group, name);
        PwuString varDefKeyDesc = PwuValueDefnDescKey(group, name);
        PwuString varDefKeyDefault = PwuValueDefnDefaultKey(group, name);
        PwuString varDefKeyRange = PwuValueDefnRangeKey(group, name);
 
        namedStrings[varDefKeyName]     = name;
        namedStrings[varDefKeyType]     = typeToString(type);
        namedStrings[varDefKeyAccess]   = access;
        namedStrings[varDefKeyDesc]     = desc;
        namedStrings[varDefKeyDefault]  = value;
        namedStrings[varDefKeyRange]    = range;
        ret = PWP_TRUE;
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuGetValue(const char group[], const char name[], PWP_HVALUE hVal)
{
    bool isDefault;
    PwuString str;
    namedStrings.get(PwuJoin(group, name), str, "", isDefault);
    if (!isDefault) {
        PwuValueSetString(hVal, str.c_str());
    }
    return PWP_CAST_BOOL(!isDefault);
}
 
/**************************************/
template<typename T, PWP_ENUM_VALTYPE TId>
static PWP_BOOL
PwuValueSetter(PWP_HVALUE hVal, T * val)
{
    PWP_BOOL ret = PWP_FALSE;
    PWP_HVALUE_IMPL *impl = PWP_HVALUE_GET_IMPL(hVal);
    if (val && impl && impl->PwpValueCB_(impl->dest_, TId, val, 0)) {
        ret = PWP_TRUE;
    }
    return ret;
}
 
/**************************************/
PWP_BOOL
PwuValueSetString(PWP_HVALUE hVal, const char *val)
{
    return PwuValueSetter<const char, PWP_VALTYPE_STRING>(hVal, val);
}
 
/**************************************/
PWP_BOOL
PwuValueSetInt(PWP_HVALUE hVal, PWP_INT val)
{
    return PwuValueSetter<PWP_INT, PWP_VALTYPE_INT>(hVal, &val);
}
 
/**************************************/
PWP_BOOL
PwuValueSetUInt(PWP_HVALUE hVal, PWP_UINT val)
{
    return PwuValueSetter<PWP_UINT, PWP_VALTYPE_UINT>(hVal, &val);
}
 
/**************************************/
PWP_BOOL
PwuValueSetReal(PWP_HVALUE hVal, PWP_REAL val)
{
    return PwuValueSetter<PWP_REAL, PWP_VALTYPE_REAL>(hVal, &val);
}
 
/**************************************/
PWP_BOOL
PwuValueSetEnum(PWP_HVALUE hVal, const char *val)
{
    return PwuValueSetter<const char, PWP_VALTYPE_ENUM>(hVal, val);
}
 
/**************************************/
PWP_BOOL
PwuValueSetBool(PWP_HVALUE hVal, PWP_BOOL val)
{
    return PwuValueSetter<PWP_BOOL, PWP_VALTYPE_BOOL>(hVal, &val);
}