/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* vim: set ts=8 sts=2 et sw=2 tw=80: */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */ // IWYU pragma: private, include "nsString.h"
// Latin1 to UTF-16 // Interpret each incoming unsigned byte value as a Unicode scalar value (not // windows-1252!). The function names say "ASCII" instead of "Latin1" for // legacy reasons.
// UTF-16 to Latin1 // If all code points in the input are below U+0100, represents each scalar // value as an unsigned byte. (This is not windows-1252!) If there are code // points above U+00FF, memory-safely produces garbage and will likely start // asserting in future debug builds. The nature of the garbage may differ // based on CPU architecture and must not be relied upon. The names say // "ASCII" instead of "Latin1" for legacy reasons.
// Latin1 to UTF-8 // Interpret each incoming unsigned byte value as a Unicode scalar value (not // windows-1252!). // If the input is ASCII, the heap-allocated mozilla::StringBuffer is shared if // possible.
// UTF-8 to Latin1 // If all code points in the input are below U+0100, represents each scalar // value as an unsigned byte. (This is not windows-1252!) If there are code // points above U+00FF, memory-safely produces garbage in release builds and // asserts in debug builds. The nature of the garbage may differ // based on CPU architecture and must not be relied upon. // If the input is ASCII, the heap-allocated mozilla::StringBuffer is shared if // possible.
/** * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. * * Infallibly allocates and returns a new |char| buffer which you must * free with |free|. * Performs a conversion with LossyConvertUTF16toLatin1() writing into the * newly-allocated buffer. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource a 16-bit wide string * @return a new |char| buffer you must free with |free|.
*/ char* ToNewCString(const nsAString& aSource);
/* A fallible version of ToNewCString. Returns nullptr on failure. */ char* ToNewCString(const nsAString& aSource, const mozilla::fallible_t& aFallible);
/** * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. * * Infallibly allocates and returns a new |char| buffer which you must * free with |free|. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource an 8-bit wide string * @return a new |char| buffer you must free with |free|.
*/ char* ToNewCString(const nsACString& aSource);
/* A fallible version of ToNewCString. Returns nullptr on failure. */ char* ToNewCString(const nsACString& aSource, const mozilla::fallible_t& aFallible);
/** * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. * * Infallibly allocates and returns a new |char| buffer which you must * free with |free|. * Performs an encoding conversion from a UTF-16 string to a UTF-8 string with * unpaired surrogates replaced with the REPLACEMENT CHARACTER copying * |aSource| to your new buffer. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource a UTF-16 string (made of char16_t's) * @param aUTF8Count the number of 8-bit units that was returned * @return a new |char| buffer you must free with |free|.
*/ char* ToNewUTF8String(const nsAString& aSource, uint32_t* aUTF8Count = nullptr);
/* A fallible version of ToNewUTF8String. Returns nullptr on failure. */ char* ToNewUTF8String(const nsAString& aSource, uint32_t* aUTF8Count, const mozilla::fallible_t& aFallible);
/** * Returns a new |char16_t| buffer containing a zero-terminated copy * of |aSource|. * * Infallibly allocates and returns a new |char16_t| buffer which you must * free with |free|. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource a UTF-16 string * @return a new |char16_t| buffer you must free with |free|.
*/
char16_t* ToNewUnicode(const nsAString& aSource);
/* A fallible version of ToNewUnicode. Returns nullptr on failure. */
char16_t* ToNewUnicode(const nsAString& aSource, const mozilla::fallible_t& aFallible);
/** * Returns a new |char16_t| buffer containing a zero-terminated copy * of |aSource|. * * Infallibly allocates and returns a new |char16_t| buffer which you must * free with|free|. * * Performs an encoding conversion by 0-padding 8-bit wide characters up to * 16-bits wide (i.e. Latin1 to UTF-16 conversion) while copying |aSource| * to your new buffer. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource a Latin1 string * @return a new |char16_t| buffer you must free with |free|.
*/
char16_t* ToNewUnicode(const nsACString& aSource);
/* A fallible version of ToNewUnicode. Returns nullptr on failure. */
char16_t* ToNewUnicode(const nsACString& aSource, const mozilla::fallible_t& aFallible);
/** * Returns a new |char16_t| buffer containing a zero-terminated copy * of |aSource|. * * Infallibly allocates and returns a new |char| buffer which you must * free with |free|. Performs an encoding conversion from UTF-8 to UTF-16 * while copying |aSource| to your new buffer. Malformed byte sequences * are replaced with the REPLACEMENT CHARACTER. * * The new buffer is zero-terminated, but that may not help you if |aSource| * contains embedded nulls. * * @param aSource an 8-bit wide string, UTF-8 encoded * @param aUTF16Count the number of 16-bit units that was returned * @return a new |char16_t| buffer you must free with |free|. * (UTF-16 encoded)
*/
char16_t* UTF8ToNewUnicode(const nsACString& aSource,
uint32_t* aUTF16Count = nullptr);
/* A fallible version of UTF8ToNewUnicode. Returns nullptr on failure. */
char16_t* UTF8ToNewUnicode(const nsACString& aSource, uint32_t* aUTF16Count, const mozilla::fallible_t& aFallible);
/** * Copies |aLength| 16-bit code units from the start of |aSource| to the * |char16_t| buffer |aDest|. * * After this operation |aDest| is not null terminated. * * @param aSource a UTF-16 string * @param aSrcOffset start offset in the source string * @param aDest a |char16_t| buffer * @param aLength the number of 16-bit code units to copy * @return pointer to destination buffer - identical to |aDest|
*/
char16_t* CopyUnicodeTo(const nsAString& aSource, uint32_t aSrcOffset,
char16_t* aDest, uint32_t aLength);
/** * Replaces unpaired surrogates with U+FFFD in the argument. * * Copies a shared string buffer or an otherwise read-only * buffer only if there are unpaired surrogates.
*/
[[nodiscard]] inlinebool EnsureUTF16Validity(nsAString& aString) {
size_t upTo = mozilla::Utf16ValidUpTo(aString);
size_t len = aString.Length(); if (upTo == len) { returntrue;
}
char16_t* ptr = aString.BeginWriting(mozilla::fallible); if (!ptr) { returnfalse;
} auto span = mozilla::Span(ptr, len);
span[upTo] = 0xFFFD;
mozilla::EnsureUtf16ValiditySpan(span.From(upTo + 1)); returntrue;
}
/** * Join a sequence of items, each optionally transformed to a string, with a * given separator, appending to a given string. * * \tparam CharType char or char16_t * \tparam InputRange a range usable with range-based for * \tparam Func optionally, a functor accepting a nsTSubstring<CharType>& and * an item of InputRange which appends the latter to the former
*/ template < typename CharType, typename InputRange, typename Func = const decltype(mozilla::detail::kStringJoinAppendDefault)&> void StringJoinAppend(
nsTSubstring<CharType>& aOutput, const nsTLiteralString<CharType>& aSeparator, const InputRange& aInputRange,
Func&& aFunc = mozilla::detail::kStringJoinAppendDefault) { bool first = true; for (constauto& item : aInputRange) { if (first) {
first = false;
} else {
aOutput.Append(aSeparator);
}
aFunc(aOutput, item);
}
}
/** * Join a sequence of items, each optionally transformed to a string, with a * given separator, returning a new string. * * \tparam CharType char or char16_t * \tparam InputRange a range usable with range-based for * \tparam Func optionally, a functor accepting a nsTSubstring<CharType>& and * an item of InputRange which appends the latter to the former
/** * Finds the leftmost occurrence of |aPattern|, if any in the range * |aSearchStart|..|aSearchEnd|. * * Returns |true| if a match was found, and adjusts |aSearchStart| and * |aSearchEnd| to point to the match. If no match was found, returns |false| * and makes |aSearchStart == aSearchEnd|. * * Currently, this is equivalent to the O(m*n) implementation previously on * |ns[C]String|. * * If we need something faster, then we can implement that later.
*/
/* sometimes we don't care about where the string was, just that we
* found it or not */ inlinebool FindInReadable( const nsAString& aPattern, const nsAString& aSource,
nsStringComparator aCompare = nsTDefaultStringComparator) {
nsAString::const_iterator start, end;
aSource.BeginReading(start);
aSource.EndReading(end); return FindInReadable(aPattern, start, end, aCompare);
}
/** * Finds the rightmost occurrence of |aPattern| * Returns |true| if a match was found, and adjusts |aSearchStart| and * |aSearchEnd| to point to the match. If no match was found, returns |false| * and makes |aSearchStart == aSearchEnd|.
*/ bool RFindInReadable(const nsAString& aPattern, nsAString::const_iterator&,
nsAString::const_iterator&,
nsStringComparator = nsTDefaultStringComparator); bool RFindInReadable(const nsACString& aPattern, nsACString::const_iterator&,
nsACString::const_iterator&,
nsCStringComparator = nsTDefaultStringComparator);
/** * Finds the leftmost occurrence of |aChar|, if any in the range * |aSearchStart|..|aSearchEnd|. * * Returns |true| if a match was found, and adjusts |aSearchStart| to * point to the match. If no match was found, returns |false| and * makes |aSearchStart == aSearchEnd|.
*/ bool FindCharInReadable(char16_t aChar, nsAString::const_iterator& aSearchStart, const nsAString::const_iterator& aSearchEnd); bool FindCharInReadable(char aChar, nsACString::const_iterator& aSearchStart, const nsACString::const_iterator& aSearchEnd);
/** * Compare a UTF-8 string to an UTF-16 string. * * Returns 0 if the strings are equal, -1 if aUTF8String is less * than aUTF16Count, and 1 in the reverse case. Errors are replaced * with U+FFFD and then the U+FFFD is compared as if it had occurred * in the input. If aErr is not nullptr, *aErr is set to true if * either string had malformed sequences.
*/
int32_t CompareUTF8toUTF16(const nsACString& aUTF8String, const nsAString& aUTF16String, bool* aErr = nullptr);
