Boost C++ Libraries Home Libraries People FAQ More
PrevUpHomeNext

類模板 variant

boost::variant — 安全、泛型、基於棧的可識別聯合容器。

摘要

template<typename T1, typename T2 = unspecified, ..., 
         typename TN = unspecified> 
class variant {
public:
  // types
  typedef unspecified types;

  // construct/copy/destruct
  variant();
  variant(const variant &);
  template<typename T> variant(T &);
  template<typename T> variant(const T &);
  template<typename U1, typename U2, ..., typename UN> 
    variant(variant<U1, U2, ..., UN> &);
  template<typename U1, typename U2, ..., typename UN> 
    variant(const variant<U1, U2, ..., UN> &);
  ~variant();

  // modifiers
  void swap(variant &);
  variant & operator=(const variant &);
  template<typename T> variant & operator=(const T &);

  // queries
  int which() const;
  bool empty() const;
  const std::type_info & type() const;

  // relational
  bool operator==(const variant &) const;
  template<typename U> void operator==(const U &) const;
  bool operator<(const variant &) const;
  template<typename U> void operator<(const U &) const;
};

說明

variant 類模板(靈感來自於 Andrei Alexandrescu 的同名類[Ale01A])是一個高效的、可遞歸的、可保存任意值類型(POD 或 非-POD)的有界可識別值類型。它可以構造自任意可轉換為其任一有界類型的類型，或者構造自一個源 variant，只要源 variant 的每個有界類型可以轉換為目標 variant 的某個有界類型。通過使用 apply_visitor, variant 可以支持編譯期檢查的、類型安全的訪問；而通過 get, variant 可以支持運行期檢查的、類型安全的值取出。

說明：

  • variant 的有界類型通過內嵌的 typedef types 獲得，它是一個 MPL-兼容的序列，其中包含一組類型，這些類型必須被訪問該 variant 的 visitor 所處理。
  • variant 的所有成員至少要滿足基本的異常安全保證。即，variant 的所有操作即使失敗了也必須保持數據的一致性。
  • 每個被指定為 variant 的模板參數的類型必須滿足 BoundedType 概念的要求。
  • 每個被指定為 variant 的模板參數的類型必須在去除限定符後是唯一的。因此，像 variant<int, int> 和 variant<int, const int> 這樣的類型的行為是未定義的。
  • 符合規範的 variant 實現必須至少允許10個類型作為模板參數。實際所允許的參數數量由預處理器宏 BOOST_VARIANT_LIMIT_TYPES 獲得。(以 MPL 或兼容序列的元素來指定 variant 的有界類型，則可以超過這個限制，相關說明請見 make_variant_over)

variant 的構造/複製/析構

  1. variant();
    要求： variant 的第一個有界類型(即 T1)必須符合 可缺省構造 [20.1.4] 概念的要求。
    後續條件： *this 的內容為第一個有界類型(即 T1)的缺省值。
    拋出： 可能因 T1 的缺省構造函數所引起的任何異常而失敗。 
  2. variant(const variant & other);
    後續條件： *this 的內容為 other 內容的一份拷貝。
    拋出： 可能因 other 所含類型的複製構造函數所引起的任何異常而失敗。 
  3. template<typename T> variant(T & operand);
    要求： T 必須明確地可轉換為某個有界類型(如 T1, T2, 等)。
    後續條件： *this 的內容為 operand 到某個有界類型的最佳轉換，取決於標準的重載決議規則。
    拋出： 可能因 operand 至某個有界類型的轉換所引起的任何異常而失敗。 
  4. template<typename T> variant(const T & operand);
    說明： 與前一構造函數語義相同，但允許構造自臨時對象。 
  5. template<typename U1, typename U2, ..., typename UN> 
      variant(variant<U1, U2, ..., UN> & operand);
    要求： 每一個 U1, U2, ..., UN 都必須明確可轉換為某個有界類型(如 T1, T2, ..., TN)。
    後續條件： 如果 variant<U1, U2, ..., UN> 本身是其中一個有界類型，則 *this 的內容為 operand 的拷貝。否則，*this 的內容為 operand 到某個有界類型的最佳轉換，取決於標準的重載決議規則。
    拋出： 如果 variant<U1, U2, ..., UN> 本身是其中一個有界類型，則可能因 variant<U1, U2, ..., UN> 的複製構造函數所引起的任何異常而失敗。否則，可能因 operand 至某個有界類型的轉換所引起的任何異常而失敗。 
  6. template<typename U1, typename U2, ..., typename UN> 
      variant(const variant<U1, U2, ..., UN> & operand);
    說明： 與前一構造函數語義相同，但允許構造自臨時對象。 
  7. ~variant();
    作用： 銷毀 *this 的內容。
    拋出： 不會拋出。

variant 的修改操作

  1. void swap(variant & other);
    要求： 每個有界類型都必須滿足 可賦值 概念的要求。
    作用： 交換 *this 和 other 的內容。
    拋出： 如果 other 所含類型與 *this 所含類型相同，則可能因 *this 和 other 的內容的 swap 操作所引起的異常而失敗。否則，可能因某個所含類型的複製構造函數所引起的異常而失敗。也可能由於內存不足而拋出 std::bad_alloc (為什麼？). 
  2. variant & operator=(const variant & rhs);
    要求： 每個有界類型都必須滿足 可賦值 概念的要求。
    作用： 如果 rhs 所含類型與 *this 所含類型相同，則將 rhs 的內容賦值到 *this 的內容中。否則，將 *this 的內容變為 rhs 內容的一份拷貝，並銷毀 *this 原來的內容。
    拋出： 如果 rhs 所含類型與 *this 所含類型相同，則可能因將 rhs 的內容賦值到 *this 中而引起的異常而失敗。否則，可能因 rhs 所含類型的複製構造函數所引起的異常而失敗。也可能由於內存不足而拋出 std::bad_alloc (為什麼？). 
  3. template<typename T> variant & operator=(const T & rhs);
    要求：
    • T 必須明確可轉換為某個有界類型(即 T1, T2, 等)。
    • 每個有界類型都必須滿足 可賦值 概念的要求。
    作用： 如果 *this 所含類型為 T, 則將 rhs 賦為 *this 的內容。否則，將 *this 的內容變為從 rhs 到某個有界類型的最佳轉換，取決於標準的重載決議規則，並銷毀 *this 原來的內容。
    拋出： 如果 *this 所含類型為 T, 則可能因將 rhs 賦為 *this 的內容所引起的異常而失敗。否則，可能因從 rhs 到某個有界類型的轉換所引起的異常而失敗。還可能由於內存不足而拋出 std::bad_alloc (為什麼？).

variant 的查詢操作

  1. int which() const;
    返回： *this 所含類型在有界類型集合中的索引值，從零起計。(例如，如果從一個包含 std::string 的 variant<int, std::string> 調用，which() 將返回 1.)
    拋出： 不會拋出異常。 
  2. bool empty() const;
    返回： false: variant 總是剛好包含某一個有界類型。(更多信息請見 “"非空" 保證” 一節)
    原理： 便於與 boost::any 的泛型兼容。
    拋出： 不會拋出異常。 
  3. const std::type_info & type() const;
    返回： typeid(x), 其中 x 為 *this 的內容。
    拋出： 不會拋出異常。

variant 的關係操作

  1. bool operator==(const variant & rhs) const;
    template<typename U> void operator==(const U &) const;
    說明： 存在一個返回 void 的重載只是為了防止右操作數隱式轉換為 variant; 這樣的用法將(被有意地)引發一個編譯錯誤。
    要求： variant 的每一個有界類型都必須滿足 相等性可比較 概念的要求。
    返回： true 當且僅當 which() == rhs.which() 且 content_this == content_rhs, 其中 content_this 為 *this 的內容而 content_rhs 為 rhs 的內容。
    拋出： 如果 which() == rhs.which() 則可能因 operator==(T,T) 所引起的異常而失敗，其中 T 為 *this 所含類型。 

  2. bool operator<(const variant & rhs) const;
    template<typename U> void operator<(const U &) const;
    說明： 存在一個返回 void 的重載只是為了防止右操作數隱式轉換為 variant; 這樣的用法將(被有意地)引發一個編譯錯誤。
    要求： variant 的每一個有界類型都必須滿足 小於關係可比較 概念的要求。
    返回： 如果 which() == rhs.which() 則返回：content_this < content_rhs, 其中 content_this 為 *this 的內容而 content_rhs 為 rhs 的內容。否則返回：which() < rhs.which().
    拋出： 如果 which() == rhs.which() 則可能因 operator<(T,T) 所引起的異常而失敗，其中 T 為 *this 所含類型。
Copyright © 2002, 2003 Eric Friedman, Itay Maman
PrevUpHomeNext