DOMString.h

/* -*- 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/. */

#ifndef mozilla_dom_DOMString_h
#define mozilla_dom_DOMString_h

#include "nsString.h"
#include "nsStringBuffer.h"
#include "mozilla/Assertions.h"
#include "mozilla/Attributes.h"
#include "mozilla/Maybe.h"
#include "nsDOMString.h"
#include "nsAtom.h"

namespace mozilla::dom {

/**
 * A class for representing string return values.  This can be either passed to
 * callees that have an nsString or nsAString out param or passed to a callee
 * that actually knows about this class and can work with it.  Such a callee may
 * call these setters:
 *
 *   SetKnownLiveStringBuffer
 *   SetStringBuffer
 *   SetKnownLiveString
 *   SetKnownLiveAtom
 *   SetNull
 *
 * to assign a value to the DOMString without instantiating an actual nsString
 * in the process, or use AsAString() to instantiate an nsString and work with
 * it.  These options are mutually exclusive!  Don't do more than one of them.
 *
 * It's only OK to call
 * SetKnownLiveStringBuffer/SetKnownLiveString/SetKnownLiveAtom if the caller of
 * the method in question plans to keep holding a strong ref to the stringbuffer
 * involved, whether it's a raw nsStringBuffer, or stored inside the string or
 * atom being passed.  In the string/atom cases that means the caller must own
 * the string or atom, and not mutate it (in the string case) for the lifetime
 * of the DOMString.
 *
 * The proper way to extract a value is to check IsNull().  If not null, then
 * check IsEmpty().  If neither of those is true, check HasStringBuffer().  If
 * that's true, call StringBuffer()/StringBufferLength().  If HasStringBuffer()
 * returns false, check HasLiteral, and if that returns true call
 * Literal()/LiteralLength().  If HasLiteral() is false, call AsAString() and
 * get the value from that.
 */
class MOZ_STACK_CLASS DOMString {
 public:
  DOMString() : mStringBuffer(nullptr), mLength(0), mState(State::Empty) {}
  ~DOMString() {
    MOZ_ASSERT(!mString || !mStringBuffer, "Shouldn't have both present!");
    if (mState == State::OwnedStringBuffer) {
      MOZ_ASSERT(mStringBuffer);
      mStringBuffer->Release();
    }
  }

  operator nsString&() { return AsAString(); }

  // It doesn't make any sense to convert a DOMString to a const nsString or
  // nsAString reference; this class is meant for outparams only.
  operator const nsString&() = delete;
  operator const nsAString&() = delete;

  nsString& AsAString() {
    MOZ_ASSERT(mState == State::Empty || mState == State::String,
               "Moving from nonempty state to another nonempty state?");
    MOZ_ASSERT(!mStringBuffer, "We already have a stringbuffer?");
    if (!mString) {
      mString.emplace();
      mState = State::String;
    }
    return *mString;
  }

  bool HasStringBuffer() const {
    MOZ_ASSERT(!mString || !mStringBuffer, "Shouldn't have both present!");
    MOZ_ASSERT(mState > State::Null,
               "Caller should have checked IsNull() and IsEmpty() first");
    return mState >= State::OwnedStringBuffer;
  }

  // Get the stringbuffer.  This can only be called if HasStringBuffer()
  // returned true.  If that's true, it will never return null.  Note that
  // constructing a string from this nsStringBuffer with length given by
  // StringBufferLength() might give you something that is not null-terminated.
  nsStringBuffer* StringBuffer() const {
    MOZ_ASSERT(HasStringBuffer(),
               "Don't ask for the stringbuffer if we don't have it");
    MOZ_ASSERT(mStringBuffer, "We better have a stringbuffer if we claim to");
    return mStringBuffer;
  }

  // Get the length of the stringbuffer.  Can only be called if
  // HasStringBuffer().
  uint32_t StringBufferLength() const {
    MOZ_ASSERT(HasStringBuffer(),
               "Don't call this if there is no stringbuffer");
    return mLength;
  }

  // Tell the DOMString to relinquish ownership of its nsStringBuffer to the
  // caller.  Can only be called if HasStringBuffer().
  void RelinquishBufferOwnership() {
    MOZ_ASSERT(HasStringBuffer(),
               "Don't call this if there is no stringbuffer");
    if (mState == State::OwnedStringBuffer) {
      // Just hand that ref over.
      mState = State::UnownedStringBuffer;
    } else {
      // Caller should end up holding a ref.
      mStringBuffer->AddRef();
    }
  }

  bool HasLiteral() const {
    MOZ_ASSERT(!mString || !mStringBuffer, "Shouldn't have both present!");
    MOZ_ASSERT(mState > State::Null,
               "Caller should have checked IsNull() and IsEmpty() first");
    return mState == State::Literal;
  }

  // Get the literal string.  This can only be called if HasLiteral()
  // returned true.  If that's true, it will never return null.
  const char16_t* Literal() const {
    MOZ_ASSERT(HasLiteral(), "Don't ask for the literal if we don't have it");
    MOZ_ASSERT(mLiteral, "We better have a literal if we claim to");
    return mLiteral;
  }

  // Get the length of the literal.  Can only be called if HasLiteral().
  uint32_t LiteralLength() const {
    MOZ_ASSERT(HasLiteral(), "Don't call this if there is no literal");
    return mLength;
  }

  bool HasAtom() const {
    MOZ_ASSERT(!mString || !mStringBuffer, "Shouldn't have both present!");
    MOZ_ASSERT(mState > State::Null,
               "Caller should have checked IsNull() and IsEmpty() first");
    return mState == State::UnownedAtom;
  }

  // Get the atom.  This can only be called if HasAtom() returned true.  If
  // that's true, it will never return null.
  nsDynamicAtom* Atom() const {
    MOZ_ASSERT(HasAtom(), "Don't ask for the atom if we don't have it");
    MOZ_ASSERT(mAtom, "We better have an atom if we claim to");
    return mAtom;
  }

  // Initialize the DOMString to a (nsStringBuffer, length) pair.  The length
  // does NOT have to be the full length of the (null-terminated) string in the
  // nsStringBuffer.
  void SetKnownLiveStringBuffer(nsStringBuffer* aStringBuffer,
                                uint32_t aLength) {
    MOZ_ASSERT(mState == State::Empty, "We're already set to a value");
    if (aLength != 0) {
      SetStringBufferInternal(aStringBuffer, aLength);
      mState = State::UnownedStringBuffer;
    }
    // else nothing to do
  }

  // Like SetKnownLiveStringBuffer, but holds a reference to the nsStringBuffer.
  void SetStringBuffer(nsStringBuffer* aStringBuffer, uint32_t aLength) {
    MOZ_ASSERT(mState == State::Empty, "We're already set to a value");
    if (aLength != 0) {
      SetStringBufferInternal(aStringBuffer, aLength);
      aStringBuffer->AddRef();
      mState = State::OwnedStringBuffer;
    }
    // else nothing to do
  }

  void SetKnownLiveString(const nsAString& aString) {
    MOZ_ASSERT(mString.isNothing(), "We already have a string?");
    MOZ_ASSERT(mState == State::Empty, "We're already set to a value");
    MOZ_ASSERT(!mStringBuffer, "Setting stringbuffer twice?");
    if (MOZ_UNLIKELY(aString.IsVoid())) {
      SetNull();
    } else if (!aString.IsEmpty()) {
      nsStringBuffer* buf = nsStringBuffer::FromString(aString);
      if (buf) {
        SetKnownLiveStringBuffer(buf, aString.Length());
      } else if (aString.IsLiteral()) {
        SetLiteralInternal(aString.BeginReading(), aString.Length());
      } else {
        AsAString() = aString;
      }
    }
  }

  enum NullHandling { eTreatNullAsNull, eTreatNullAsEmpty, eNullNotExpected };

  void SetKnownLiveAtom(nsAtom* aAtom, NullHandling aNullHandling) {
    MOZ_ASSERT(mString.isNothing(), "We already have a string?");
    MOZ_ASSERT(mState == State::Empty, "We're already set to a value");
    MOZ_ASSERT(!mAtom, "Setting atom twice?");
    MOZ_ASSERT(aAtom || aNullHandling != eNullNotExpected);
    if (aNullHandling == eNullNotExpected || aAtom) {
      if (aAtom->IsStatic()) {
        // Static atoms are backed by literals.  Explicitly call AsStatic() here
        // to avoid the extra IsStatic() checks in nsAtom::GetUTF16String().
        SetLiteralInternal(aAtom->AsStatic()->GetUTF16String(),
                           aAtom->GetLength());
      } else {
        mAtom = aAtom->AsDynamic();
        mState = State::UnownedAtom;
      }
    } else if (aNullHandling == eTreatNullAsNull) {
      SetNull();
    }
  }

  void SetNull() {
    MOZ_ASSERT(!mStringBuffer, "Should have no stringbuffer if null");
    MOZ_ASSERT(mString.isNothing(), "Should have no string if null");
    MOZ_ASSERT(mState == State::Empty, "Already set to a value?");
    mState = State::Null;
  }

  bool IsNull() const {
    MOZ_ASSERT(!mStringBuffer || mString.isNothing(),
               "How could we have a stringbuffer and a nonempty string?");
    return mState == State::Null || (mString && mString->IsVoid());
  }

  bool IsEmpty() const {
    MOZ_ASSERT(!mStringBuffer || mString.isNothing(),
               "How could we have a stringbuffer and a nonempty string?");
    // This is not exact, because we might still have an empty XPCOM string.
    // But that's OK; in that case the callers will try the XPCOM string
    // themselves.
    return mState == State::Empty;
  }

  void ToString(nsAString& aString) {
    if (IsNull()) {
      SetDOMStringToNull(aString);
    } else if (IsEmpty()) {
      aString.Truncate();
    } else if (HasStringBuffer()) {
      // Don't share the nsStringBuffer with aString if the result would not
      // be null-terminated.
      nsStringBuffer* buf = StringBuffer();
      uint32_t len = StringBufferLength();
      auto chars = static_cast<char16_t*>(buf->Data());
      if (chars[len] == '\0') {
        // Safe to share the buffer.
        buf->ToString(len, aString);
      } else {
        // We need to copy, unfortunately.
        aString.Assign(chars, len);
      }
    } else if (HasLiteral()) {
      aString.AssignLiteral(Literal(), LiteralLength());
    } else if (HasAtom()) {
      mAtom->ToString(aString);
    } else {
      aString = AsAString();
    }
  }

 private:
  void SetStringBufferInternal(nsStringBuffer* aStringBuffer,
                               uint32_t aLength) {
    MOZ_ASSERT(mString.isNothing(), "We already have a string?");
    MOZ_ASSERT(mState == State::Empty, "We're already set to a value");
    MOZ_ASSERT(!mStringBuffer, "Setting stringbuffer twice?");
    MOZ_ASSERT(aStringBuffer, "Why are we getting null?");
    MOZ_ASSERT(aLength != 0, "Should not have empty string here");
    mStringBuffer = aStringBuffer;
    mLength = aLength;
  }

  void SetLiteralInternal(const char16_t* aLiteral, uint32_t aLength) {
    MOZ_ASSERT(!mLiteral, "What's going on here?");
    mLiteral = aLiteral;
    mLength = aLength;
    mState = State::Literal;
  }

  enum class State : uint8_t {
    Empty,  // An empty string.  Default state.
    Null,   // Null (not a string at all)

    // All states that involve actual string data should come after
    // Empty and Null.

    String,       // An XPCOM string stored in mString.
    Literal,      // A string literal (static lifetime).
    UnownedAtom,  // mAtom is valid and we are not holding a ref.
    // If we ever add an OwnedAtom state, XPCStringConvert::DynamicAtomToJSVal
    // will need to grow an out param for whether the atom was shared.
    OwnedStringBuffer,    // mStringBuffer is valid and we have a ref to it.
    UnownedStringBuffer,  // mStringBuffer is valid; we are not holding a ref.
    // The two string buffer values must come last.  This lets us avoid doing
    // two tests to figure out whether we have a stringbuffer.
  };

  // We need to be able to act like a string as needed
  Maybe<nsAutoString> mString;

  union {
    // The nsStringBuffer in the OwnedStringBuffer/UnownedStringBuffer cases.
    nsStringBuffer* MOZ_UNSAFE_REF(
        "The ways in which this can be safe are "
        "documented above and enforced through "
        "assertions") mStringBuffer;
    // The literal in the Literal case.
    const char16_t* mLiteral;
    // The atom in the UnownedAtom case.
    nsDynamicAtom* MOZ_UNSAFE_REF(
        "The ways in which this can be safe are "
        "documented above and enforced through "
        "assertions") mAtom;
  };

  // Length in the stringbuffer and literal cases.
  uint32_t mLength;

  State mState;
};

}  // namespace mozilla::dom

#endif  // mozilla_dom_DOMString_h