{"id":107595,"date":"2022-12-15T07:00:00","date_gmt":"2022-12-15T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=107595"},"modified":"2022-12-15T08:42:42","modified_gmt":"2022-12-15T16:42:42","slug":"20221215-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20221215-00\/?p=107595","title":{"rendered":"Inside C++\/WinRT: IReference<T><\/CODE>"},"content":{"rendered":"

Last time, we looked at how to create an IReference<T><\/code> in C++\/WinRT<\/a>. How did I know the answer? By reading the source code and reverse-engineering what operations were valid and what they produced.<\/p>\n

Let’s look at the available constructors:<\/p>\n

IReference(IReference const& other) = default;\r\nIReference(IReference&& other) = default;\r\n<\/pre>\n
The copy and move constructors are implicitly declared, but I’m declaring them explicitly so they show up on the list.<\/p>\n
IReference(std::nullptr_t = nullptr) noexcept {}\r\n<\/pre>\n
This constructor serves as a default constructor, or you can construct from nullptr<\/code>. Either way creates an empty IReference<\/code>. This constructor exists for all interface types, so it’s nothing surprising.<\/p>\n
IReference(void* ptr, take_ownership_from_abi_t) noexcept\r\n    : Windows::Foundation::IInspectable(\r\n        ptr, take_ownership_from_abi) {}\r\n<\/pre>\n
The take_ownership_from_abi<\/code> tag type constructor creates an IReference<\/code> that takes ownership of an ABI pointer. This constructor also exists for all interface types, so nothing special is happening yet.<\/p>\n
IReference(T const& value)\r\n    : IReference<T>(\r\n        impl::reference_traits<T>::make(value))     \r\n{}\r\n<\/pre>\n
This is a conversion constructor which takes the underlying value type, calls the make<\/code> method from some class we haven’t yet studied, and uses that to initialize the IReference<\/code>. We’ll look at that class later.<\/p>\n
The last constructor is<\/p>\n
IReference(std::optional<T> const& value)\r\n    : IReference(\r\n        value ? IReference(value.value()) : nullptr)\r\n{}\r\n<\/pre>\n
This is a conversion constructor that takes a std::optional<T><\/code> and produces the corresponding std::IReference<T><\/code>. If the optional<\/code> has a value, then we wrap it inside an IReference<\/code> using the value conversion constructor we saw above. Otherwise, we initialize from nullptr<\/code>, which means “no value”.<\/p>\n
One thing to observe is that these last two constructors work with  CTAD<\/a>, so you can omit the template specialization:<\/p>\n
\/\/ compile deduces IReference<double> from double\r\ndouble value = 42.0;\r\nauto ref = IReference(value);\r\n\r\n\/\/ compile deduces IReference<double> from std::optional<double>\r\nstd::optional<double> value(42.0);\r\nauto ref = IReference(value);\r\n<\/pre>\n
The last member function is the std::optional<\/code> conversion:<\/p>\n
operator std::optional<T>() const\r\n{\r\n    if (*this)\r\n    {\r\n        return this->Value();\r\n    }\r\n    else\r\n    {\r\n        return std::nullopt;\r\n    }\r\n}\r\n<\/pre>\n
This converts an IReference<T><\/code> to a std::optional<T><\/code> by producing the value if the wrapped pointer is non-null, or producing an empty optional<\/code> if the wrapped pointer is null.<\/p>\n
All that’s left is studying the impl::reference_traits<\/code>.<\/p>\n
template <typename T>\r\nstruct reference_traits\r\n{\r\n    static auto make(T const& value)\r\n    { return winrt::make<impl::reference<T>>(value); }\r\n    using itf = Windows::Foundation::IReference<T>;\r\n};\r\n<\/pre>\n
This is the unspecialized template traits class which make<\/code>s an IReference<T><\/code> by creating an instance of the private impl::reference<\/code> class. We’ll make a note to come back to that later.<\/p>\n
What follows is a series of specializations for various fundamental types. For example,<\/p>\n
template <>\r\nstruct reference_traits<uint8_t>\r\n{\r\n    static auto make(uint8_t value)\r\n    { return Windows::Foundation::PropertyValue::CreateUInt8(value); }\r\n    using itf = Windows::Foundation::IReference<uint8_t>;\r\n};\r\n<\/pre>\n
To create an IReference<uint8_t><\/code>, the make()<\/code> method uses the PropertyValue::CreateUInt8()<\/code> method. Repeat for the other special-purpose factory methods of PropertyValue<\/code>.<\/p>\n
Okay, so now we’re left with that impl::reference<\/code> class:<\/p>\n
template <typename T>\r\nstruct reference :\r\n    implements<reference<T>,\r\n        Windows::Foundation::IReference<T>,\r\n        Windows::Foundation::IPropertyValue>\r\n{\r\n    reference(T const& value) : m_value(value)\r\n    { }\r\n\r\n    T Value() const { return m_value; }\r\n\r\n    Windows::Foundation::PropertyType Type() const noexcept\r\n    {\r\n        return Windows::Foundation::PropertyType::OtherType;\r\n    }\r\n\r\n    static constexpr bool IsNumericScalar() noexcept\r\n    {\r\n        return std::is_arithmetic_v<T> || std::is_enum_v<T>;\r\n    }\r\n\r\n    uint8_t GetUInt8() const\r\n    {\r\n        return to_scalar<uint8_t>();\r\n    }\r\n\r\n    \u301a repeat for the other Get(IntegralType) methods \u301b\r\n\r\n    float GetSingle() { throw hresult_not_implemented(); }\r\n\r\n    \u301a repeat for the other Get(NonIntegralType) methods \u301b\r\n\r\nprivate:\r\n    template <typename To>\r\n    To to_scalar() const\r\n    {\r\n        if constexpr (IsNumericScalar()) {\r\n            return static_cast<To>(m_value);\r\n        } else {\r\n            throw hresult_not_implemented();\r\n        }\r\n    }\r\n\r\n    T m_value;\r\n};\r\n<\/pre>\n
The impl::reference<T><\/code> type is used for custom enumerations and custom structures. In both cases, the IReference<T>::Value()<\/code> produces the wrapped value.<\/p>\n
The remaining methods provide the implementation of IPropertyValue<\/code>, which we noted last time is one of the hidden requirements of IReference<T><\/code>.<\/p>\n
If used for enumerations, Is\u00adNumeric\u00adScalar()<\/code> reports true<\/code>, and all of the Get(IntegralType)<\/code> methods return the underlying integral value, cast to the requested integral type. On the other hand, for structures, Is\u00adNumeric\u00adScalar()<\/code> reports false<\/code>, and all of the Get(IntegralType)<\/code> methods throw hresult_not_implemented()<\/code>.<\/p>\n
For the floating point and other non-integral types, the methods always throw hresult_not_implemented()<\/code>.<\/p>\n
It’s from reverse-engineering the C++\/WinRT implementation of IReference<\/code> that we inferred the rules for its use. Being able to reverse-engineer the proper use of a library from reading its source code is a key under-appreciated software developer skill. Until you can infer the proper way of working with unfamiliar code, your career growth options will be limited. You’ll be one of those people who can only do things they are taught, without the ability to learn new things on their own.<\/p>\n","protected":false},"excerpt":{"rendered":"
Reverse-engineering the usages from the code.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-107595","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Reverse-engineering the usages from the code.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/107595","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=107595"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/107595\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=107595"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=107595"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=107595"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}