gecko-dev/js/public/ColumnNumber.h

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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/. */

// [SMDOC] Column numbers
//
// Inside SpiderMonkey, column numbers are represented as 1-origin 32-bit
// unsigned integers. Some parts of the engine use the highest bit of a column
// number as a tag to indicate Wasm frame.
//
// These classes help clarifying the origin of the column number, and also
// figuring out whether the column number uses the wasm's tag or not, and also
// help converting between them.
//
// Also these classes support converting from 0-origin column number.
//
// In a 0-origin context, column 0 is the first character of the line.
// In a 1-origin context, column 1 is the first character of the line,
// for example:
//
//           function foo() { ... }
//           ^              ^
// 0-origin: 0              15
// 1-origin: 1              16

#ifndef js_ColumnNumber_h
#define js_ColumnNumber_h

#include "mozilla/Assertions.h"  // MOZ_ASSERT
#include "mozilla/Attributes.h"  // MOZ_IMPLICIT

#include <limits>    // std::numeric_limits
#include <stdint.h>  // uint32_t

namespace JS {

// Wasm function index.
//
// This class is used as parameter or return type of
// TaggedColumnNumberOneOrigin class below.
struct WasmFunctionIndex {
  // TaggedColumnNumberOneOrigin uses the highest bit as a tag.
  static constexpr uint32_t Limit = std::numeric_limits<int32_t>::max() / 2;

  // For wasm frames, the function index is returned as the column with the
  // high bit set. In paths that format error stacks into strings, this
  // information can be used to synthesize a proper wasm frame. But when raw
  // column numbers are handed out, we just fix them to the first column to
  // avoid confusion.
  static constexpr uint32_t DefaultBinarySourceColumnNumberOneOrigin = 1;

 private:
  uint32_t value_ = 0;

 public:
  constexpr WasmFunctionIndex() = default;
  constexpr WasmFunctionIndex(const WasmFunctionIndex& other) = default;

  inline explicit WasmFunctionIndex(uint32_t value) : value_(value) {
    MOZ_ASSERT(valid());
  }

  uint32_t value() const { return value_; }

  bool valid() const { return value_ <= Limit; }
};

// The offset between 2 column numbers.
struct ColumnNumberOffset {
 private:
  int32_t value_ = 0;

 public:
  constexpr ColumnNumberOffset() = default;
  constexpr ColumnNumberOffset(const ColumnNumberOffset& other) = default;

  inline explicit ColumnNumberOffset(int32_t value) : value_(value) {}

  static constexpr ColumnNumberOffset zero() { return ColumnNumberOffset(); }

  bool operator==(const ColumnNumberOffset& rhs) const {
    return value_ == rhs.value_;
  }

  bool operator!=(const ColumnNumberOffset& rhs) const {
    return !(*this == rhs);
  }

  int32_t value() const { return value_; }
};

// The positive offset from certain column number.
struct ColumnNumberUnsignedOffset {
 private:
  uint32_t value_ = 0;

 public:
  constexpr ColumnNumberUnsignedOffset() = default;
  constexpr ColumnNumberUnsignedOffset(
      const ColumnNumberUnsignedOffset& other) = default;

  inline explicit ColumnNumberUnsignedOffset(uint32_t value) : value_(value) {}

  static constexpr ColumnNumberUnsignedOffset zero() {
    return ColumnNumberUnsignedOffset();
  }

  ColumnNumberUnsignedOffset operator+(
      const ColumnNumberUnsignedOffset& offset) const {
    return ColumnNumberUnsignedOffset(value_ + offset.value());
  }

  ColumnNumberUnsignedOffset& operator+=(
      const ColumnNumberUnsignedOffset& offset) {
    value_ += offset.value();
    return *this;
  }

  bool operator==(const ColumnNumberUnsignedOffset& rhs) const {
    return value_ == rhs.value_;
  }

  bool operator!=(const ColumnNumberUnsignedOffset& rhs) const {
    return !(*this == rhs);
  }

  uint32_t value() const { return value_; }

  uint32_t* addressOfValueForTranscode() { return &value_; }
};

struct TaggedColumnNumberOneOrigin;

namespace detail {

// Shared implementation of {,Limited}ColumnNumberOneOrigin classes.
//
// LimitValue being 0 means there's no limit.
template <uint32_t LimitValue = 0>
struct MaybeLimitedColumnNumber {
 public:
  static constexpr uint32_t OriginValue = 1;

 protected:
  uint32_t value_ = OriginValue;

  friend struct ::JS::TaggedColumnNumberOneOrigin;

 public:
  constexpr MaybeLimitedColumnNumber() = default;
  MaybeLimitedColumnNumber(const MaybeLimitedColumnNumber& other) = default;
  MaybeLimitedColumnNumber& operator=(const MaybeLimitedColumnNumber& other) =
      default;

  explicit MaybeLimitedColumnNumber(uint32_t value) : value_(value) {
    MOZ_ASSERT(valid());
  }

  bool operator==(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    return value_ == rhs.value_;
  }

  bool operator!=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    return !(*this == rhs);
  }

  MaybeLimitedColumnNumber<LimitValue> operator+(
      const ColumnNumberOffset& offset) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
    return MaybeLimitedColumnNumber<LimitValue>(value_ + offset.value());
  }

  MaybeLimitedColumnNumber<LimitValue> operator+(
      const ColumnNumberUnsignedOffset& offset) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
    return MaybeLimitedColumnNumber<LimitValue>(value_ + offset.value());
  }

  MaybeLimitedColumnNumber<LimitValue> operator-(
      const ColumnNumberOffset& offset) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(ptrdiff_t(value_) - offset.value() >= 0);
    return MaybeLimitedColumnNumber<LimitValue>(value_ - offset.value());
  }
  ColumnNumberOffset operator-(
      const MaybeLimitedColumnNumber<LimitValue>& other) const {
    MOZ_ASSERT(valid());
    return ColumnNumberOffset(int32_t(value_) - int32_t(other.value_));
  }

  MaybeLimitedColumnNumber<LimitValue>& operator+=(
      const ColumnNumberOffset& offset) {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
    value_ += offset.value();
    MOZ_ASSERT(valid());
    return *this;
  }
  MaybeLimitedColumnNumber<LimitValue>& operator-=(
      const ColumnNumberOffset& offset) {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(ptrdiff_t(value_) - offset.value() >= 0);
    value_ -= offset.value();
    MOZ_ASSERT(valid());
    return *this;
  }

  bool operator<(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(rhs.valid());
    return value_ < rhs.value_;
  }
  bool operator<=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(rhs.valid());
    return value_ <= rhs.value_;
  }
  bool operator>(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(rhs.valid());
    return value_ > rhs.value_;
  }
  bool operator>=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
    MOZ_ASSERT(valid());
    MOZ_ASSERT(rhs.valid());
    return value_ >= rhs.value_;
  }

  uint32_t oneOriginValue() const {
    MOZ_ASSERT(valid());

    return value_;
  }

  uint32_t* addressOfValueForTranscode() { return &value_; }

  bool valid() const {
    if constexpr (LimitValue == 0) {
      return true;
    }

    MOZ_ASSERT(value_ != 0);

    return value_ <= LimitValue;
  }
};

// See the comment for LimitedColumnNumberOneOrigin below
static constexpr uint32_t ColumnNumberOneOriginLimit =
    std::numeric_limits<int32_t>::max() / 2;

}  // namespace detail

// Column number in 1-origin with 31-bit limit.
//
// Various parts of the engine requires the column number be represented in
// 31 bits.
//
// See:
//  * TaggedColumnNumberOneOrigin
//  * TokenStreamAnyChars::checkOptions
//  * SourceNotes::isRepresentable
//  * WasmFrameIter::computeLine
struct LimitedColumnNumberOneOrigin : public detail::MaybeLimitedColumnNumber<
                                          detail::ColumnNumberOneOriginLimit> {
 private:
  using Base =
      detail::MaybeLimitedColumnNumber<detail::ColumnNumberOneOriginLimit>;

 public:
  static constexpr uint32_t Limit = detail::ColumnNumberOneOriginLimit;

  static_assert(uint32_t(Limit + Limit) > Limit,
                "Adding Limit should not overflow");

  using Base::Base;

  LimitedColumnNumberOneOrigin() = default;
  LimitedColumnNumberOneOrigin(const LimitedColumnNumberOneOrigin& other) =
      default;
  MOZ_IMPLICIT LimitedColumnNumberOneOrigin(const Base& other) : Base(other) {}

  static LimitedColumnNumberOneOrigin limit() {
    return LimitedColumnNumberOneOrigin(Limit);
  }

  static LimitedColumnNumberOneOrigin fromUnlimited(uint32_t value) {
    if (value > Limit) {
      return LimitedColumnNumberOneOrigin(Limit);
    }
    return LimitedColumnNumberOneOrigin(value);
  }
  static LimitedColumnNumberOneOrigin fromUnlimited(
      const MaybeLimitedColumnNumber<0>& value) {
    return fromUnlimited(value.oneOriginValue());
  }

  static LimitedColumnNumberOneOrigin fromZeroOrigin(uint32_t value) {
    return LimitedColumnNumberOneOrigin(value + 1);
  }
};

// Column number in 1-origin.
struct ColumnNumberOneOrigin : public detail::MaybeLimitedColumnNumber<0> {
 private:
  using Base = detail::MaybeLimitedColumnNumber<0>;

 public:
  using Base::Base;
  using Base::operator=;

  ColumnNumberOneOrigin() = default;
  ColumnNumberOneOrigin(const ColumnNumberOneOrigin& other) = default;
  ColumnNumberOneOrigin& operator=(ColumnNumberOneOrigin&) = default;

  MOZ_IMPLICIT ColumnNumberOneOrigin(const Base& other) : Base(other) {}

  explicit ColumnNumberOneOrigin(const LimitedColumnNumberOneOrigin& other)
      : Base(other.oneOriginValue()) {}

  static ColumnNumberOneOrigin fromZeroOrigin(uint32_t value) {
    return ColumnNumberOneOrigin(value + 1);
  }
};

// Either LimitedColumnNumberOneOrigin, or WasmFunctionIndex.
//
// In order to pass the Wasm frame's (url, bytecode-offset, func-index) tuple
// through the existing (url, line, column) tuple, it tags the highest bit of
// the column to indicate "this is a wasm frame".
//
// When knowing clients see this bit, they shall render the tuple
// (url, line, column|bit) as "url:wasm-function[column]:0xline" according
// to the WebAssembly Web API's Developer-Facing Display Conventions.
//   https://webassembly.github.io/spec/web-api/index.html#conventions
// The wasm bytecode offset continues to be passed as the JS line to avoid
// breaking existing devtools code written when this used to be the case.
//
// 0b0YYYYYYY_YYYYYYYY_YYYYYYYY_YYYYYYYY LimitedColumnNumberOneOrigin
// 0b1YYYYYYY_YYYYYYYY_YYYYYYYY_YYYYYYYY WasmFunctionIndex
//
// The tagged colum number shouldn't escape the JS engine except for the
// following places:
//   * SavedFrame API which can directly access WASM frame's info
//   * ubi::Node API which can also directly access WASM frame's info
struct TaggedColumnNumberOneOrigin {
  static constexpr uint32_t WasmFunctionTag = 1u << 31;

  static_assert((WasmFunctionIndex::Limit & WasmFunctionTag) == 0);
  static_assert((LimitedColumnNumberOneOrigin::Limit & WasmFunctionTag) == 0);

 protected:
  uint32_t value_ = LimitedColumnNumberOneOrigin::OriginValue;

  explicit TaggedColumnNumberOneOrigin(uint32_t value) : value_(value) {}

 public:
  constexpr TaggedColumnNumberOneOrigin() = default;
  TaggedColumnNumberOneOrigin(const TaggedColumnNumberOneOrigin& other) =
      default;

  explicit TaggedColumnNumberOneOrigin(
      const LimitedColumnNumberOneOrigin& other)
      : value_(other.value_) {
    MOZ_ASSERT(isLimitedColumnNumber());
  }
  explicit TaggedColumnNumberOneOrigin(const WasmFunctionIndex& other)
      : value_(other.value() | WasmFunctionTag) {
    MOZ_ASSERT(isWasmFunctionIndex());
  }

  static TaggedColumnNumberOneOrigin fromRaw(uint32_t value) {
    return TaggedColumnNumberOneOrigin(value);
  }

  static TaggedColumnNumberOneOrigin forDifferentialTesting() {
    return TaggedColumnNumberOneOrigin(LimitedColumnNumberOneOrigin());
  }

  bool operator==(const TaggedColumnNumberOneOrigin& rhs) const {
    return value_ == rhs.value_;
  }

  bool operator!=(const TaggedColumnNumberOneOrigin& rhs) const {
    return !(*this == rhs);
  }

  bool isLimitedColumnNumber() const { return !isWasmFunctionIndex(); }

  bool isWasmFunctionIndex() const { return !!(value_ & WasmFunctionTag); }

  LimitedColumnNumberOneOrigin toLimitedColumnNumber() const {
    MOZ_ASSERT(isLimitedColumnNumber());
    return LimitedColumnNumberOneOrigin(value_);
  }

  WasmFunctionIndex toWasmFunctionIndex() const {
    MOZ_ASSERT(isWasmFunctionIndex());
    return WasmFunctionIndex(value_ & ~WasmFunctionTag);
  }

  uint32_t oneOriginValue() const {
    return isWasmFunctionIndex()
               ? WasmFunctionIndex::DefaultBinarySourceColumnNumberOneOrigin
               : toLimitedColumnNumber().oneOriginValue();
  }

  uint32_t rawValue() const { return value_; }

  uint32_t* addressOfValueForTranscode() { return &value_; }
};

}  // namespace JS

#endif /* js_ColumnNumber_h */