1 // Copyright (c) 2016 The WebM project authors. All Rights Reserved. 2 // 3 // Use of this source code is governed by a BSD-style license 4 // that can be found in the LICENSE file in the root of the source 5 // tree. An additional intellectual property rights grant can be found 6 // in the file PATENTS. All contributing project authors may 7 // be found in the AUTHORS file in the root of the source tree. 8 #ifndef INCLUDE_WEBM_ELEMENT_H_ 9 #define INCLUDE_WEBM_ELEMENT_H_ 10 11 #include <cstdint> 12 #include <limits> 13 #include <utility> 14 15 #include "./id.h" 16 17 /** 18 \file 19 A wrapper around an object that represents a WebM element, including its parsed 20 metadata. 21 */ 22 23 namespace webm { 24 25 /** 26 \addtogroup PUBLIC_API 27 @{ 28 */ 29 30 /** 31 A wrapper around an object that represents a WebM element. 32 33 Since some elements may be absent, this wrapper is used to indicate the 34 presence (or lack thereof) of an element in a WebM document. If the element is 35 encoded in the file and it has been parsed, `is_present()` will return true. 36 Otherwise it will return false since the element was ommitted or skipped when 37 parsing. 38 */ 39 template <typename T> 40 class Element { 41 public: 42 /** 43 Value-initializes the element's value and makes `is_present()` false. 44 */ 45 constexpr Element() = default; 46 47 /** 48 Creates an element with the given value and makes `is_present()` false. 49 50 \param value The value of the element. 51 */ Element(const T & value)52 explicit constexpr Element(const T& value) : value_(value) {} 53 54 /** 55 Creates an element with the given value and makes `is_present()` false. 56 57 \param value The value of the element. 58 */ Element(T && value)59 explicit constexpr Element(T&& value) : value_(std::move(value)) {} 60 61 /** 62 Creates an element with the given value and presence state. 63 64 \param value The value of the element. 65 \param is_present True if the element is present, false if it is absent. 66 */ Element(const T & value,bool is_present)67 constexpr Element(const T& value, bool is_present) 68 : value_(value), is_present_(is_present) {} 69 70 /** 71 Creates an element with the given value and presence state. 72 73 \param value The value of the element. 74 \param is_present True if the element is present, false if it is absent. 75 */ Element(T && value,bool is_present)76 constexpr Element(T&& value, bool is_present) 77 : value_(std::move(value)), is_present_(is_present) {} 78 79 constexpr Element(const Element<T>& other) = default; 80 constexpr Element(Element<T>&& other) = default; 81 82 ~Element() = default; 83 84 Element<T>& operator=(const Element<T>& other) = default; 85 Element<T>& operator=(Element<T>&& other) = default; 86 87 /** 88 Sets the element's value and state. 89 90 \param value The new value for the element. 91 \param is_present The new presence state for the element. 92 */ Set(const T & value,bool is_present)93 void Set(const T& value, bool is_present) { 94 value_ = value; 95 is_present_ = is_present; 96 } 97 98 /** 99 Sets the element's value and state. 100 101 \param value The new value for the element. 102 \param is_present The new presence state for the element. 103 */ Set(T && value,bool is_present)104 void Set(T&& value, bool is_present) { 105 value_ = std::move(value); 106 is_present_ = is_present; 107 } 108 109 /** 110 Gets the element's value. 111 */ value()112 constexpr const T& value() const { return value_; } 113 114 /** 115 Gets a mutuable pointer to the element's value (will never be null). 116 */ mutable_value()117 T* mutable_value() { return &value_; } 118 119 /** 120 Returns true if the element is present, false otherwise. 121 */ is_present()122 constexpr bool is_present() const { return is_present_; } 123 124 bool operator==(const Element<T>& other) const { 125 return is_present_ == other.is_present_ && value_ == other.value_; 126 } 127 128 private: 129 T value_{}; 130 bool is_present_ = false; 131 }; 132 133 /** 134 Metadata for WebM elements that are encountered when parsing. 135 */ 136 struct ElementMetadata { 137 /** 138 The EBML ID of the element. 139 */ 140 Id id; 141 142 /** 143 The number of bytes that were used to encode the EBML ID and element size. 144 145 If the size of the header is unknown (which is only the case if a seek was 146 performed to the middle of an element, so its header was not parsed), this 147 will be the value `kUnknownHeaderSize`. 148 */ 149 std::uint32_t header_size; 150 151 /** 152 The size of the element. 153 154 This is number of bytes in the element's body, which excludes the header 155 bytes. 156 157 If the size of the element's body is unknown, this will be the value 158 `kUnknownElementSize`. 159 */ 160 std::uint64_t size; 161 162 /** 163 The absolute byte position of the element, starting at the first byte of the 164 element's header. 165 166 If the position of the element is unknown (which is only the case if a seek 167 was performed to the middle of an element), this will be the value 168 `kUnknownElementPosition`. 169 */ 170 std::uint64_t position; 171 172 /** 173 Returns true if every member within the two objects are equal. 174 */ 175 bool operator==(const ElementMetadata& other) const { 176 return id == other.id && header_size == other.header_size && 177 size == other.size && position == other.position; 178 } 179 }; 180 181 /** 182 A special value for `ElementMetadata::header_size` indicating the header size 183 is not known. 184 */ 185 constexpr std::uint64_t kUnknownHeaderSize = 186 std::numeric_limits<std::uint32_t>::max(); 187 188 /** 189 A special value for `ElementMetadata::size` indicating the element's size is 190 not known. 191 */ 192 constexpr std::uint64_t kUnknownElementSize = 193 std::numeric_limits<std::uint64_t>::max(); 194 195 /** 196 A special value for `ElementMetadata::position` indicating the element's 197 position is not known. 198 */ 199 constexpr std::uint64_t kUnknownElementPosition = 200 std::numeric_limits<std::uint64_t>::max(); 201 202 /** 203 @} 204 */ 205 206 } // namespace webm 207 208 #endif // INCLUDE_WEBM_ELEMENT_H_ 209