1 /*! @header QuesaString.h 2 Declares the Quesa string objects. 3 */ 4 /* NAME: 5 QuesaString.h 6 7 DESCRIPTION: 8 Quesa public header. 9 10 COPYRIGHT: 11 Copyright (c) 1999-2004, Quesa Developers. All rights reserved. 12 13 For the current release of Quesa, please see: 14 15 <http://www.quesa.org/> 16 17 Redistribution and use in source and binary forms, with or without 18 modification, are permitted provided that the following conditions 19 are met: 20 21 o Redistributions of source code must retain the above copyright 22 notice, this list of conditions and the following disclaimer. 23 24 o Redistributions in binary form must reproduce the above 25 copyright notice, this list of conditions and the following 26 disclaimer in the documentation and/or other materials provided 27 with the distribution. 28 29 o Neither the name of Quesa nor the names of its contributors 30 may be used to endorse or promote products derived from this 31 software without specific prior written permission. 32 33 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 34 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 35 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 36 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 37 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 38 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 39 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 40 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 41 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 42 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 43 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 44 ___________________________________________________________________________ 45 */ 46 #ifndef QUESA_STRING_HDR 47 #define QUESA_STRING_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #ifdef __QD3DSTRING__ 55 #error 56 #endif 57 58 #define __QD3DSTRING__ 59 60 61 62 63 64 //============================================================================= 65 // C++ preamble 66 //----------------------------------------------------------------------------- 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 72 73 74 75 //============================================================================= 76 // Function prototypes 77 //----------------------------------------------------------------------------- 78 /*! 79 * @function 80 * Q3String_GetType 81 * @discussion 82 * Returns the type of a string object. 83 * 84 * Returns kQ3StringTypeCString, or kQ3ObjectTypeInvalid if the 85 * object type is unknown. 86 * 87 * @param stringObj The object to test. 88 * @result The type of the object. 89 */ 90 Q3_EXTERN_API_C ( TQ3ObjectType ) 91 Q3String_GetType ( 92 TQ3StringObject stringObj 93 ); 94 95 96 97 /*! 98 * @function 99 * Q3CString_New 100 * @discussion 101 * Create a new C string object. 102 * 103 * Creates a string object based on a NULL terminated string. The 104 * string data is copied, and so str can be disposed of after 105 * creating the object. 106 * 107 * @param str The C string to copy. 108 * @result The new string object. 109 */ 110 Q3_EXTERN_API_C ( TQ3StringObject ) 111 Q3CString_New ( 112 const char *str 113 ); 114 115 116 117 /*! 118 * @function 119 * Q3CString_GetLength 120 * @discussion 121 * Get the length of a string object. 122 * 123 * Returns the number of bytes required to store the character 124 * data in the string object. The length returned does not 125 * include the terminating NULL byte. 126 * 127 * @param stringObj The object to test. 128 * @param length The number of bytes needed for character data. 129 * @result Success or failure of the operation. 130 */ 131 Q3_EXTERN_API_C ( TQ3Status ) 132 Q3CString_GetLength ( 133 TQ3StringObject stringObj, 134 TQ3Uns32 *length 135 ); 136 137 138 139 /*! 140 * @function 141 * Q3CString_SetString 142 * @discussion 143 * Set the character data of a string object. 144 * 145 * Assigns a C string to the string object. The string data is copied 146 * and so str can be disposed of after this call. 147 * 148 * @param stringObj The object to update. 149 * @param str The string to assign to the object. 150 * @result Success or failure of the operation. 151 */ 152 Q3_EXTERN_API_C ( TQ3Status ) 153 Q3CString_SetString ( 154 TQ3StringObject stringObj, 155 const char *str 156 ); 157 158 159 160 /*! 161 * @function 162 * Q3CString_GetString 163 * @discussion 164 * Return the character data of a string object. 165 * 166 * The data returned must be released with a subsequent call to 167 * Q3CString_EmptyData. The data returned will be NULL terminated. 168 * 169 * The str parameter is overwritten, and so must not point to an 170 * existing string or a memory leak will occur. If the value of 171 * the str parameter is not NULL, a warning will be posted. 172 * 173 * @param stringObj The object to query. 174 * @param str Receives a pointer to the character data. 175 * @result Success or failure of the operation. 176 */ 177 Q3_EXTERN_API_C ( TQ3Status ) 178 Q3CString_GetString ( 179 TQ3StringObject stringObj, 180 char **str 181 ); 182 183 184 185 /*! 186 * @function 187 * Q3CString_EmptyData 188 * @discussion 189 * Releases the memory allocated by a previous call to 190 * Q3CString_GetString. 191 * 192 * After the string data has been freed, the str parameter 193 * will be reset to NULL. 194 * 195 * @param str The string data to release. 196 * @result Success or failure of the operation. 197 */ 198 Q3_EXTERN_API_C ( TQ3Status ) 199 Q3CString_EmptyData ( 200 char **str 201 ); 202 203 204 205 206 207 //============================================================================= 208 // C++ postamble 209 //----------------------------------------------------------------------------- 210 #ifdef __cplusplus 211 } 212 #endif 213 214 #endif 215 216 217