/* $Id: strcache.h 20360 2009-06-08 00:04:31Z vboxsync $ */
/** @file
 * IPRT - String Cache, stub implementation.
 */

/*
 * Copyright (C) 2009 Sun Microsystems, Inc.
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software
 * Foundation, in version 2 as it comes in the "COPYING" file of the
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
 * VirtualBox OSE distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 USA or visit http://www.sun.com if you need
 * additional information or have any questions.
 */

#ifndef ___iprt_strcache_h
#define ___iprt_strcache_h

#include <iprt/types.h>

RT_BEGIN_DECLS


/**
 * Create a new string cache.
 *
 * @returns IPRT status code
 *
 * @param   phStrCache          Where to return the string cache handle.
 * @param   pszName             The name of the cache (for debug purposes).
 */
RTDECL(int) RTStrCacheCreate(PRTSTRCACHE phStrCache, const char *pszName);


/**
 * Destroys a string cache.
 *
 * This will cause all strings in the cache to be released and thus become
 * invalid.
 *
 * @returns IPRT status.
 *
 * @param   hStrCache           Handle to the string cache. The nil and default
 *                              handles are ignored quietly (VINF_SUCCESS).
 */
RTDECL(int) RTStrCacheDestroy(RTSTRCACHE hStrCache);


/**
 * Enters a string into the cache.
 *
 * @returns Pointer to a read-only copy of the string.
 *
 * @param   hStrCache           Handle to the string cache.
 * @param   pchString           Pointer to a string. This does not need to be
 *                              zero terminated, but must not contain any zero
 *                              characters.
 * @param   cchString           The number of characters (bytes) to enter.
 *
 * @remarks It is implementation dependent whether the returned string pointer
 *          differs when entering the same string twice.
 */
RTDECL(const char *) RTStrCacheEnterN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);

/**
 * Enters a string into the cache.
 *
 * @returns Pointer to a read-only copy of the string.
 *
 * @param   hStrCache           Handle to the string cache.
 * @param   psz                 Pointer to a zero terminated string.
 *
 * @remarks See RTStrCacheEnterN.
 */
RTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz);


/**
 * Retains a reference to a string.
 *
 * @returns The new reference count. UINT32_MAX is returned if the string
 *          pointer is invalid.
 */
RTDECL(uint32_t) RTStrCacheRetain(const char *psz);

/**
 * Releases a reference to a string.
 *
 * @returns The new reference count.
 *          UINT32_MAX is returned if the string pointer is invalid.
 *
 * @param   hStrCache           Handle to the string cache. Passing NIL is ok,
 *                              but this may come a performance hit.
 * @param   psz                 Pointer to a cached string.
 */
RTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz);

/**
 * Gets the string length of a cache entry.
 *
 * @returns The string length. 0 if the string is invalid (asserted).
 *
 * @param   psz             Pointer to a cached string.
 */
RTDECL(size_t) RTStrCacheLength(const char *psz);

RT_END_DECLS

#endif