git.sesse.net Git - casparcg/blob - dependencies64/cef/include/internal/cef_string_types.h

   1 // Copyright (c) 2010 Marshall A. Greenblatt. All rights reserved.
   2 //
   3 // Redistribution and use in source and binary forms, with or without
   4 // modification, are permitted provided that the following conditions are
   5 // met:
   6 //
   7 //    * Redistributions of source code must retain the above copyright
   8 // notice, this list of conditions and the following disclaimer.
   9 //    * Redistributions in binary form must reproduce the above
  10 // copyright notice, this list of conditions and the following disclaimer
  11 // in the documentation and/or other materials provided with the
  12 // distribution.
  13 //    * Neither the name of Google Inc. nor the name Chromium Embedded
  14 // Framework nor the names of its contributors may be used to endorse
  15 // or promote products derived from this software without specific prior
  16 // written permission.
  17 //
  18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 #ifndef CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_
  31 #define CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_
  32 #pragma once
  33
  34 // CEF provides functions for converting between UTF-8, -16 and -32 strings.
  35 // CEF string types are safe for reading from multiple threads but not for
  36 // modification. It is the user's responsibility to provide synchronization if
  37 // modifying CEF strings from multiple threads.
  38
  39 #include <stddef.h>
  40
  41 #include "include/base/cef_build.h"
  42 #include "include/internal/cef_export.h"
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 // CEF character type definitions. wchar_t is 2 bytes on Windows and 4 bytes on
  49 // most other platforms.
  50
  51 #if defined(OS_WIN)
  52 typedef wchar_t char16;
  53 #else  // !OS_WIN
  54 typedef unsigned short char16;  // NOLINT (runtime/int)
  55 #ifndef WCHAR_T_IS_UTF32
  56 #define WCHAR_T_IS_UTF32
  57 #endif  // WCHAR_T_IS_UTF32
  58 #endif  // !OS_WIN
  59
  60
  61 // CEF string type definitions. Whomever allocates |str| is responsible for
  62 // providing an appropriate |dtor| implementation that will free the string in
  63 // the same memory space. When reusing an existing string structure make sure
  64 // to call |dtor| for the old value before assigning new |str| and |dtor|
  65 // values. Static strings will have a NULL |dtor| value. Using the below
  66 // functions if you want this managed for you.
  67
  68 typedef struct _cef_string_wide_t {
  69   wchar_t* str;
  70   size_t length;
  71   void (*dtor)(wchar_t* str);
  72 } cef_string_wide_t;
  73
  74 typedef struct _cef_string_utf8_t {
  75   char* str;
  76   size_t length;
  77   void (*dtor)(char* str);
  78 } cef_string_utf8_t;
  79
  80 typedef struct _cef_string_utf16_t {
  81   char16* str;
  82   size_t length;
  83   void (*dtor)(char16* str);
  84 } cef_string_utf16_t;
  85
  86
  87 ///
  88 // These functions set string values. If |copy| is true (1) the value will be
  89 // copied instead of referenced. It is up to the user to properly manage
  90 // the lifespan of references.
  91 ///
  92
  93 CEF_EXPORT int cef_string_wide_set(const wchar_t* src, size_t src_len,
  94                                    cef_string_wide_t* output, int copy);
  95 CEF_EXPORT int cef_string_utf8_set(const char* src, size_t src_len,
  96                                    cef_string_utf8_t* output, int copy);
  97 CEF_EXPORT int cef_string_utf16_set(const char16* src, size_t src_len,
  98                                     cef_string_utf16_t* output, int copy);
  99
 100
 101 ///
 102 // Convenience macros for copying values.
 103 ///
 104
 105 #define cef_string_wide_copy(src, src_len, output)  \
 106     cef_string_wide_set(src, src_len, output, true)
 107 #define cef_string_utf8_copy(src, src_len, output)  \
 108     cef_string_utf8_set(src, src_len, output, true)
 109 #define cef_string_utf16_copy(src, src_len, output)  \
 110     cef_string_utf16_set(src, src_len, output, true)
 111
 112
 113 ///
 114 // These functions clear string values. The structure itself is not freed.
 115 ///
 116
 117 CEF_EXPORT void cef_string_wide_clear(cef_string_wide_t* str);
 118 CEF_EXPORT void cef_string_utf8_clear(cef_string_utf8_t* str);
 119 CEF_EXPORT void cef_string_utf16_clear(cef_string_utf16_t* str);
 120
 121
 122 ///
 123 // These functions compare two string values with the same results as strcmp().
 124 ///
 125
 126 CEF_EXPORT int cef_string_wide_cmp(const cef_string_wide_t* str1,
 127                                    const cef_string_wide_t* str2);
 128 CEF_EXPORT int cef_string_utf8_cmp(const cef_string_utf8_t* str1,
 129                                    const cef_string_utf8_t* str2);
 130 CEF_EXPORT int cef_string_utf16_cmp(const cef_string_utf16_t* str1,
 131                                     const cef_string_utf16_t* str2);
 132
 133
 134 ///
 135 // These functions convert between UTF-8, -16, and -32 strings. They are
 136 // potentially slow so unnecessary conversions should be avoided. The best
 137 // possible result will always be written to |output| with the boolean return
 138 // value indicating whether the conversion is 100% valid.
 139 ///
 140
 141 CEF_EXPORT int cef_string_wide_to_utf8(const wchar_t* src, size_t src_len,
 142                                        cef_string_utf8_t* output);
 143 CEF_EXPORT int cef_string_utf8_to_wide(const char* src, size_t src_len,
 144                                        cef_string_wide_t* output);
 145
 146 CEF_EXPORT int cef_string_wide_to_utf16(const wchar_t* src, size_t src_len,
 147                                         cef_string_utf16_t* output);
 148 CEF_EXPORT int cef_string_utf16_to_wide(const char16* src, size_t src_len,
 149                                         cef_string_wide_t* output);
 150
 151 CEF_EXPORT int cef_string_utf8_to_utf16(const char* src, size_t src_len,
 152                                         cef_string_utf16_t* output);
 153 CEF_EXPORT int cef_string_utf16_to_utf8(const char16* src, size_t src_len,
 154                                         cef_string_utf8_t* output);
 155
 156
 157 ///
 158 // These functions convert an ASCII string, typically a hardcoded constant, to a
 159 // Wide/UTF16 string. Use instead of the UTF8 conversion routines if you know
 160 // the string is ASCII.
 161 ///
 162
 163 CEF_EXPORT int cef_string_ascii_to_wide(const char* src, size_t src_len,
 164                                         cef_string_wide_t* output);
 165 CEF_EXPORT int cef_string_ascii_to_utf16(const char* src, size_t src_len,
 166                                          cef_string_utf16_t* output);
 167
 168
 169
 170 ///
 171 // It is sometimes necessary for the system to allocate string structures with
 172 // the expectation that the user will free them. The userfree types act as a
 173 // hint that the user is responsible for freeing the structure.
 174 ///
 175
 176 typedef cef_string_wide_t* cef_string_userfree_wide_t;
 177 typedef cef_string_utf8_t* cef_string_userfree_utf8_t;
 178 typedef cef_string_utf16_t* cef_string_userfree_utf16_t;
 179
 180
 181 ///
 182 // These functions allocate a new string structure. They must be freed by
 183 // calling the associated free function.
 184 ///
 185
 186 CEF_EXPORT cef_string_userfree_wide_t cef_string_userfree_wide_alloc();
 187 CEF_EXPORT cef_string_userfree_utf8_t cef_string_userfree_utf8_alloc();
 188 CEF_EXPORT cef_string_userfree_utf16_t cef_string_userfree_utf16_alloc();
 189
 190
 191 ///
 192 // These functions free the string structure allocated by the associated
 193 // alloc function. Any string contents will first be cleared.
 194 ///
 195
 196 CEF_EXPORT void cef_string_userfree_wide_free(cef_string_userfree_wide_t str);
 197 CEF_EXPORT void cef_string_userfree_utf8_free(cef_string_userfree_utf8_t str);
 198 CEF_EXPORT void cef_string_userfree_utf16_free(cef_string_userfree_utf16_t str);
 199
 200
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 #endif  // CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_