ui/gfx/utf16_indexing.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_GFX_UTF16_INDEXING_H_
   6 #define UI_GFX_UTF16_INDEXING_H_
   7
   8 #include "base/strings/string16.h"
   9 #include "ui/gfx/gfx_export.h"
  10
  11 namespace gfx {
  12
  13 // Returns false if s[index-1] is a high surrogate and s[index] is a low
  14 // surrogate, true otherwise.
  15 GFX_EXPORT bool IsValidCodePointIndex(const base::string16& s, size_t index);
  16
  17 // |UTF16IndexToOffset| returns the number of code points between |base| and
  18 // |pos| in the given string. |UTF16OffsetToIndex| returns the index that is
  19 // |offset| code points away from the given |base| index. These functions are
  20 // named after glib's |g_utf8_pointer_to_offset| and |g_utf8_offset_to_pointer|,
  21 // which perform the same function for UTF-8. As in glib, it is an error to
  22 // pass an |offset| that walks off the edge of the string.
  23 //
  24 // These functions attempt to deal with invalid use of UTF-16 surrogates in a
  25 // way that makes as much sense as possible: unpaired surrogates are treated as
  26 // single characters, and if an argument index points to the middle of a valid
  27 // surrogate pair, it is treated as though it pointed to the end of that pair.
  28 // The index returned by |UTF16OffsetToIndex| never points to the middle of a
  29 // surrogate pair.
  30 //
  31 // The following identities hold:
  32 //   If |s| contains no surrogate pairs, then
  33 //     UTF16IndexToOffset(s, base, pos) == pos - base
  34 //     UTF16OffsetToIndex(s, base, offset) == base + offset
  35 //   If |pos| does not point to the middle of a surrogate pair, then
  36 //     UTF16OffsetToIndex(s, base, UTF16IndexToOffset(s, base, pos)) == pos
  37 //   Always,
  38 //     UTF16IndexToOffset(s, base, UTF16OffsetToIndex(s, base, ofs)) == ofs
  39 //     UTF16IndexToOffset(s, i, j) == -UTF16IndexToOffset(s, j, i)
  40 GFX_EXPORT ptrdiff_t UTF16IndexToOffset(const base::string16& s,
  41                                         size_t base,
  42                                         size_t pos);
  43 GFX_EXPORT size_t UTF16OffsetToIndex(const base::string16& s,
  44                                      size_t base,
  45                                      ptrdiff_t offset);
  46
  47 }  // namespace gfx
  48
  49 #endif  // UI_GFX_UTF16_INDEXING_H_