/*---------------------------------------------------------------------------*
 *  LCHAR.h  *
 *                                                                           *
 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
 *  you may not use this file except in compliance with the License.         *
 *                                                                           *
 *  You may obtain a copy of the License at                                  *
 *      http://www.apache.org/licenses/LICENSE-2.0                           *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * 
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 *---------------------------------------------------------------------------*/

#ifndef __LCHAR_H
#define __LCHAR_H


#include "ESR_ReturnCode.h"
#include "PortPrefix.h"
#include "ptypes.h"

/**
 * @addtogroup LCHARModule LCHAR API functions
 * LCHAR manipulation functions.
 *
 * @{
 */

/**
 * Trims string, removing any leading, trailing whitespace.
 *
 * @param text Text to trim
 * @return ESR_SUCCESS
 */
PORTABLE_API ESR_ReturnCode lstrtrim(LCHAR* text);

/**
 * Inserts text into a string.
 *
 * @param source String to insert
 * @param target String to insert into
 * @param offset Offset in target string
 * @param len [in/out] Length of target argument. If the return code is ESR_BUFFER_OVERFLOW,
 *            the required length is returned in this variable.
 * @return ESR_BUFFER_OVERFLOW is target is too small to insert into
 */
PORTABLE_API ESR_ReturnCode lstrinsert(const LCHAR* source, LCHAR* target, size_t offset, size_t* len);

/**
 * Changes all instances of one character to another in a string.
 *
 * @param text String to process
 * @param source Source character
 * @param target Target character
 * @return ESR_SUCCESS
 */
PORTABLE_API ESR_ReturnCode lstrreplace(LCHAR* text, const LCHAR source, const LCHAR target);

/**
 * Converts string to integer.
 *
 * @param text String to parse
 * @param result [out] Resulting value
 * @param base Number base to use
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
 */
PORTABLE_API ESR_ReturnCode lstrtoi(const LCHAR* text, int* result, int base);

/**
 * Converts string to unsigned integer.
 *
 * @param text String to parse
 * @param result [out] Resulting value
 * @param base Number base to use
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
 */
PORTABLE_API ESR_ReturnCode lstrtoui(const LCHAR* text, unsigned int* result, int base);

/**
 * Converts string to size_t.
 *
 * @param text String to parse
 * @param result [out] Resulting value
 * @param base Number base to use
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
 */
PORTABLE_API ESR_ReturnCode lstrtosize_t(const LCHAR* text, size_t* result, int base);

/**
 * Converts string to float.
 *
 * @param text String to parse
 * @param result [out] Resulting value
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
 */
PORTABLE_API ESR_ReturnCode lstrtof(const LCHAR* text, float* result);

/**
 * Converts string to boolean.
 *
 * @param text String to parse
 * @param result [out] Resulting value
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a boolean value
 */
PORTABLE_API ESR_ReturnCode lstrtob(const LCHAR* text, ESR_BOOL* result);

/**
 * Returns the first token in the string in the form of an integer.
 *
 * @param text Text containing integers
 * @param value [out] Integer that was read
 * @param finalPosition [out] The first character after the token. A NULL value means this
 *                            argument is ignored.
 * @return ESR_INVALID_ARGUMENT is text is null or does not represent an integer value
 */
PORTABLE_API ESR_ReturnCode LCHARGetInt( LCHAR* text, int* value, LCHAR** finalPosition);

/**
 * Convert string to upper case
 *
 * @param string [in/out] string to be converted
 * @return ESR_INVALID_ARGUMENT is string is null
 */
PORTABLE_API ESR_ReturnCode lstrupr(LCHAR* string);

/**
 * Convert string to lower case
 *
 * @param string [in/out] string to be converted
 * @return ESR_INVALID_ARGUMENT is string is null
 */
PORTABLE_API ESR_ReturnCode lstrlwr(LCHAR* string);

/**
 * Binary safe case-insensitive string comparison
 *
 * @param string1 Text containing integers
 * @param string2 Integer that was read
 * @param result [out] returns
 *        < 0 if str1 is less than str2;
 *        > 0 if str1 is greater than str2, and
 *          0 if they are equal.
 * @return ESR_INVALID_ARGUMENT is string1 or string2 is null
 */
PORTABLE_API ESR_ReturnCode lstrcasecmp(const LCHAR *string1, const LCHAR *string2, int *result);

/**
 * Converts int to string
 *
 * @param value unsigned long to convert
 * @param string [out] String to store
 * @param len [in/out] in: length of the buffer; out: length of the converted string
 * @param radix Base of value; must be in the range 2 - 36
 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result
 */
PORTABLE_API ESR_ReturnCode litostr(int value, LCHAR *string, size_t *len, int radix);

/**
 * Converts unsigned long to string
 *
 * @param value unsigned long to convert
 * @param string [out] String to store
 * @param len [in/out] in: length of the buffer; out: length of the converted string
 * @param radix Base of value; must be in the range 2 - 36
 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result
 */
PORTABLE_API ESR_ReturnCode lultostr(unsigned long value, LCHAR *string, size_t *len, int radix);

/**
 * @}
 */

#endif /* __LCHAR_H */