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 */ 42 PORTABLE_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 */ 54 PORTABLE_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 */ 64 PORTABLE_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 */ 74 PORTABLE_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 */ 84 PORTABLE_API ESR_ReturnCode lstrtoui(const LCHAR* text, unsigned int* result, int base); 85 86 /** 87 * Converts string to size_t. 88 * 89 * @param text String to parse 90 * @param result [out] Resulting value 91 * @param base Number base to use 92 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number 93 */ 94 PORTABLE_API ESR_ReturnCode lstrtosize_t(const LCHAR* text, size_t* result, int base); 95 96 /** 97 * Converts string to float. 98 * 99 * @param text String to parse 100 * @param result [out] Resulting value 101 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a number 102 */ 103 PORTABLE_API ESR_ReturnCode lstrtof(const LCHAR* text, float* result); 104 105 /** 106 * Converts string to boolean. 107 * 108 * @param text String to parse 109 * @param result [out] Resulting value 110 * @return ESR_INVALID_ARGUMENT is text is null or does not represent a boolean value 111 */ 112 PORTABLE_API ESR_ReturnCode lstrtob(const LCHAR* text, ESR_BOOL* result); 113 114 /** 115 * Returns the first token in the string in the form of an integer. 116 * 117 * @param text Text containing integers 118 * @param value [out] Integer that was read 119 * @param finalPosition [out] The first character after the token. A NULL value means this 120 * argument is ignored. 121 * @return ESR_INVALID_ARGUMENT is text is null or does not represent an integer value 122 */ 123 PORTABLE_API ESR_ReturnCode LCHARGetInt( LCHAR* text, int* value, LCHAR** finalPosition); 124 125 /** 126 * Convert string to upper case 127 * 128 * @param string [in/out] string to be converted 129 * @return ESR_INVALID_ARGUMENT is string is null 130 */ 131 PORTABLE_API ESR_ReturnCode lstrupr(LCHAR* string); 132 133 /** 134 * Convert string to lower case 135 * 136 * @param string [in/out] string to be converted 137 * @return ESR_INVALID_ARGUMENT is string is null 138 */ 139 PORTABLE_API ESR_ReturnCode lstrlwr(LCHAR* string); 140 141 /** 142 * Binary safe case-insensitive string comparison 143 * 144 * @param string1 Text containing integers 145 * @param string2 Integer that was read 146 * @param result [out] returns 147 * < 0 if str1 is less than str2; 148 * > 0 if str1 is greater than str2, and 149 * 0 if they are equal. 150 * @return ESR_INVALID_ARGUMENT is string1 or string2 is null 151 */ 152 PORTABLE_API ESR_ReturnCode lstrcasecmp(const LCHAR *string1, const LCHAR *string2, int *result); 153 154 /** 155 * Converts int to string 156 * 157 * @param value unsigned long to convert 158 * @param string [out] String to store 159 * @param len [in/out] in: length of the buffer; out: length of the converted string 160 * @param radix Base of value; must be in the range 2 - 36 161 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result 162 */ 163 PORTABLE_API ESR_ReturnCode litostr(int value, LCHAR *string, size_t *len, int radix); 164 165 /** 166 * Converts unsigned long to string 167 * 168 * @param value unsigned long to convert 169 * @param string [out] String to store 170 * @param len [in/out] in: length of the buffer; out: length of the converted string 171 * @param radix Base of value; must be in the range 2 - 36 172 * @return ESR_INVALID_ARGUMENT is string is null; ESR_BUFFER_OVERFLOW is string is not big enough to contain result 173 */ 174 PORTABLE_API ESR_ReturnCode lultostr(unsigned long value, LCHAR *string, size_t *len, int radix); 175 176 /** 177 * @} 178 */ 179 180 #endif /* __LCHAR_H */ 181
