UN_Utils.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_Utils.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Utils_h__
#define __UN_Utils_h__

#include "UN_API.h"
#include <UT/UT_String.h>
#include <UT/UT_StringHolder.h>

/// A namespace for UN library utility functions.
namespace UN_Utils
{
    /// @{ Returns true if the given name is a valid C-like variable.
    /// Ie, contains only aplphanumeric or underscore charactedrs,
    /// but does not start with a numeric character. Ohterwise, returns false.
    /// @p safe_chars - other additional (non-alphanumeric) characters 
    ///             that are allowed in the name.
    static inline bool
    isValidName( const UT_StringRef &name, 
                 const UT_StringRef &safe_chars = UT_StringRef() )
    { 
        // TODO: FIXME: including test for `!name` to be compatible
        //      with the original call to isValidVariable() without safe chars,
        //      which accepts an empty string as a valid name (bug?).
        //      A call with safe chars rejects an empty name.
        //      Empty strings arise for the root node.
        //      Revisit this and add specific validation exeptions 
        //      for the root node only.
        return !name || UT_StringWrap(name).isValidVariableName(safe_chars);
    }

    static inline bool  isValidCategoryName( const UT_StringRef &name )
                            { return isValidName(name); }
    static inline bool  isValidTypeName( const UT_StringRef &name )
                            { return isValidName(name); }
    UN_API bool         isValidNodeTypeName( const UT_StringRef &name,
                               const UT_StringRef &safe_chars = UT_StringRef());
    static inline bool  isValidPortTypeName( const UT_StringRef &name,
                               const UT_StringRef &safe_chars = UT_StringRef())
        // TODO: FIXME: see the todo comment above about name
                            { return name && isValidName(name, safe_chars); }
    static inline bool  isValidParmTypeName( const UT_StringRef &name )
                            { return isValidTypeName(name); }

    static inline bool  isValidGraphItemName( const UT_StringRef &name,
                                const UT_StringRef &safe_chars = UT_StringRef())
                            { return isValidName(name, safe_chars); }
    static inline bool  isValidNodeName( const UT_StringRef &name,
                                const UT_StringRef &safe_chars = UT_StringRef())
                            { return isValidGraphItemName(name, safe_chars); }
    static inline bool  isValidPortName( const UT_StringRef &name )
                            { return isValidName(name); }
    static inline bool  isValidInputName( const UT_StringRef &name )
                            { return isValidPortName(name); }
    static inline bool  isValidOutputName( const UT_StringRef &name )
                            { return isValidPortName(name); }
    static inline bool  isValidParmName( const UT_StringRef &name )
                            { return isValidName(name); }
    /// @}


    /// @{ Converts the given name to a one containing only valid characters.
    /// @p safe_chars - other additional (non-alphanumeric) characters 
    ///             that are allowed in the name.
    static inline UT_StringHolder
    makeValidName( const UT_StringRef &name, 
                   const UT_StringRef &safe_chars = UT_StringRef())
    { 
        return UT_StringHolder(name).forceValidVariableName(safe_chars);
    }

    static inline UT_StringHolder
    makeValidCategoryName( const UT_StringRef &name )
    { 
        return makeValidName(name); 
    }

    static inline UT_StringHolder
    makeValidGraphItemName( const UT_StringRef &name,
            const UT_StringRef &safe_chars = UT_StringRef())
    {
        return makeValidName(name, safe_chars); 
    }

    static inline UT_StringHolder
    makeValidPortName( const UT_StringRef &name )
    { 
        return makeValidName(name); 
    }
    /// @}


    /// @{ Returns a valid name, converting the given one if it is not valid.
    static inline UT_StringHolder
    ensureValidCategoryName( const UT_StringRef &name )
    {  
        return isValidCategoryName( name ) 
            ? name : makeValidCategoryName( name );
    }
    /// @}


}

#endif