1/*---------------------------------------------------------------------------*
2 *  LCHAR.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __LCHAR_H
21#define __LCHAR_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "PortPrefix.h"
27#include "ptypes.h"
28
29/**
30 * @addtogroup LCHARModule LCHAR API functions
31 * LCHAR manipulation functions.
32 *
33 * @{
34 */
35
36/**
37 * Trims string, removing any leading, trailing whitespace.
38 *
39 * @param text Text to trim
40 * @return ESR_SUCCESS
41 */
42PORTABLE_API ESR_ReturnCode lstrtrim(LCHAR* text);
43
44/**
45 * Inserts text into a string.
46 *
47 * @param source String to insert
48 * @param target String to insert into
49 * @param offset Offset in target string
50 * @param len [in/out] Length of target argument. If the return code is ESR_BUFFER_OVERFLOW,
51 *            the required length is returned in this variable.
52 * @return ESR_BUFFER_OVERFLOW is target is too small to insert into
53 */
54PORTABLE_API ESR_ReturnCode lstrinsert(const LCHAR* source, LCHAR* target, size_t offset, size_t* len);
55
56/**
57 * Changes all instances of one character to another in a string.
58 *
59 * @param text String to process
60 * @param source Source character
61 * @param target Target character
62 * @return ESR_SUCCESS
63 */
64PORTABLE_API ESR_ReturnCode lstrreplace(LCHAR* text, const LCHAR source, const LCHAR target);
65
66/**
67 * Converts string to integer.
68 *
69 * @param text String to parse
70 * @param result [out] Resulting value
71 * @param base Number base to use
72 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
73 */
74PORTABLE_API ESR_ReturnCode lstrtoi(const LCHAR* text, int* result, int base);
75
76/**
77 * Converts string to unsigned integer.
78 *
79 * @param text String to parse
80 * @param result [out] Resulting value
81 * @param base Number base to use
82 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
83 */
84PORTABLE_API ESR_ReturnCode lstrtoui(const LCHAR* text, unsigned int* result, int base);
85
86/**
87 * Converts string to float.
88 *
89 * @param text String to parse
90 * @param result [out] Resulting value
91 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number
92 */
93PORTABLE_API ESR_ReturnCode lstrtof(const LCHAR* text, float* result);
94
95/**
96 * Converts string to boolean.
97 *
98 * @param text String to parse
99 * @param result [out] Resulting value
100 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a boolean value
101 */
102PORTABLE_API ESR_ReturnCode lstrtob(const LCHAR* text, ESR_BOOL* result);
103
104/**
105 * Returns the first token in the string in the form of an integer.
106 *
107 * @param text Text containing integers
108 * @param value [out] Integer that was read
109 * @param finalPosition [out] The first character after the token. A NULL value means this
110 *                            argument is ignored.
111 * @return ESR_INVALID_ARGUMENT is text is null or does not represent an integer value
112 */
113PORTABLE_API ESR_ReturnCode LCHARGetInt( LCHAR* text, int* value, LCHAR** finalPosition);
114
115/**
116 * Convert string to upper case
117 *
118 * @param string [in/out] string to be converted
119 * @return ESR_INVALID_ARGUMENT is string is null
120 */
121PORTABLE_API ESR_ReturnCode lstrupr(LCHAR* string);
122
123/**
124 * Convert string to lower case
125 *
126 * @param string [in/out] string to be converted
127 * @return ESR_INVALID_ARGUMENT is string is null
128 */
129PORTABLE_API ESR_ReturnCode lstrlwr(LCHAR* string);
130
131/**
132 * Binary safe case-insensitive string comparison
133 *
134 * @param string1 Text containing integers
135 * @param string2 Integer that was read
136 * @param result [out] returns
137 *        < 0 if str1 is less than str2;
138 *        > 0 if str1 is greater than str2, and
139 *          0 if they are equal.
140 * @return ESR_INVALID_ARGUMENT is string1 or string2 is null
141 */
142PORTABLE_API ESR_ReturnCode lstrcasecmp(const LCHAR *string1, const LCHAR *string2, int *result);
143
144/**
145 * Converts int to string
146 *
147 * @param value unsigned long to convert
148 * @param string [out] String to store
149 * @param len [in/out] in: length of the buffer; out: length of the converted string
150 * @param radix Base of value; must be in the range 2 - 36
151 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result
152 */
153PORTABLE_API ESR_ReturnCode litostr(int value, LCHAR *string, size_t *len, int radix);
154
155/**
156 * Converts unsigned long to string
157 *
158 * @param value unsigned long to convert
159 * @param string [out] String to store
160 * @param len [in/out] in: length of the buffer; out: length of the converted string
161 * @param radix Base of value; must be in the range 2 - 36
162 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result
163 */
164PORTABLE_API ESR_ReturnCode lultostr(unsigned long value, LCHAR *string, size_t *len, int radix);
165
166/**
167 * @}
168 */
169
170#endif /* __LCHAR_H */
171