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 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 */ 93 PORTABLE_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 */ 102 PORTABLE_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 */ 113 PORTABLE_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 */ 121 PORTABLE_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 */ 129 PORTABLE_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 */ 142 PORTABLE_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 */ 153 PORTABLE_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 */ 164 PORTABLE_API ESR_ReturnCode lultostr(unsigned long value, LCHAR *string, size_t *len, int radix); 165 166 /** 167 * @} 168 */ 169 170 #endif /* __LCHAR_H */ 171