src/lib/utf_conversion/utf_conversion.h

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#include <zircon/compiler.h>
#include <zircon/types.h>

#ifndef SRC_LIB_UTF_CONVERSION_UTF_CONVERSION_H_
#define SRC_LIB_UTF_CONVERSION_UTF_CONVERSION_H_

__BEGIN_CDECLS

// Flags which control UTF conversion behavior.
//
// ++ PRESERVE_UNPAIRED_SURROGATES
// By default, when an unpaired surrogates are encountered in a UTF16 stream,
// they will be replaced with the codepoint for the Unicode replacment character
// (U+FFFD).  When the PRESERVE_UNPAIRED_SURROGATE flag is passed, however, the
// value of the unpaired surrogate will be encoded directly as a codepoint.
//
// Note that while the presence of unpaired surrogates are technically a
// violation of the Unicode UTF16 encoding specification, apparently there are
// many UTF16 encoded strings in the world today who have chosen to allow this.
//
// This implementation considers the following to be unpaired surrogates.
// ++ A "high" surrogate [0xD800, 0xDBFF] which is not followed by a "low"
//    surrogate.
// ++ A "low" surrogate [0xDC00, 0xDFFF] which is not preceded by a "high"
//    surrogate.
//
// ++ FORCE_LITTLE_ENDIAN
// ++ FORCE_BIG_ENDIAN
// By default, the conversion process will look for a byte-order-marker (code
// unit 0xFEFF) in order to determine the endianness of the UTF16 source
// string.  If no byte-order-marker is detected, host endianness will be
// assumed.
//
// Users may override this behavior by passing one of the force endian flags.
// The indicated endianness will be assumed, regardless of whether or not a byte
// order marker is found, and anything.  It is illegal to attempt to force both
// big and little endian encoding at the same time.  Attempts to do so will
// result byte-order-marker detection being applied.
//
// ++ DISCARD_BOM
// By default, a byte order marker detected in a UTF16 encoded string will be
// encoded in the UTF8 output.  Users may change this behavior and cause the BOM
// to be discarded instead of encoded by passing the DISCARD_BOM flag.
#define UTF_CONVERT_FLAG_PRESERVE_UNPAIRED_SURROGATES ((uint32_t)0x01)
#define UTF_CONVERT_FLAG_FORCE_LITTLE_ENDIAN ((uint32_t)0x02)
#define UTF_CONVERT_FLAG_FORCE_BIG_ENDIAN ((uint32_t)0x04)
#define UTF_CONVERT_FLAG_DISCARD_BOM ((uint32_t)0x08)

// Attempt to convert a UTF16 string to UTF8 using either an explicitly
// specified (utf16le_*, utf16be_*) or an unspecified endianness (utf16_*)
//
// src     : a pointer to the source string, encoded using UTF16
// src_len : The number of code units (uint16_t) in the source to process.
// dst     : a pointer to the buffer (not null terminated), or NULL to query
//           dst_len without actually writing anything.
// dst_len : A pointer to the length of of the destination buffer (in bytes).
//           Afterwards, this parameter will be updated to indicate the total
//           number of bytes it would take to hold a representation of the UTF8
//           string (excluding null terminator), even if there was not enough
//           room in the destination buffer to perform a full conversion.  No
//           error is returned if the buffer is not big enough.
// flags   : Flags which control the conversion process.  See above.
//
// Note:  Embedded nulls within the source will be processed and encoded.  *No*
// null termination of the destination buffer will be performed.
#if __cplusplus
zx_status_t utf16_to_utf8(const uint16_t* src, size_t src_len, uint8_t* dst, size_t* dst_len,
                          uint32_t flags = 0);
#else
zx_status_t utf16_to_utf8(const uint16_t* src, size_t src_len, uint8_t* dst, size_t* dst_len,
                          uint32_t flags);
#endif

// Convert UTF8 to UTF16.  Note that while src_len is in bytes, dst_len is
// in 16-bit units.
zx_status_t utf8_to_utf16(const uint8_t* src, size_t src_len, uint16_t* dst, size_t* dst_len);

__END_CDECLS

#endif  // SRC_LIB_UTF_CONVERSION_UTF_CONVERSION_H_