{"id":109155,"date":"2023-12-15T07:00:00","date_gmt":"2023-12-15T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=109155"},"modified":"2023-12-15T09:41:00","modified_gmt":"2023-12-15T17:41:00","slug":"20231215-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20231215-00\/?p=109155","title":{"rendered":"How do I specify an optional string parameter to a Windows Runtime method?"},"content":{"rendered":"

Strings occupy a weird space in the Windows Runtime type system. They are formally classified as value types, even though they have reference behavior.<\/p>\n

The problem is that different languages treat strings differently.<\/p>\n\n\n\n\n\n\n\n\n
Language<\/th>\nString type<\/th>\nValue or reference<\/th>\nMutable or immutable<\/th>\n<\/tr>\n
C++<\/td>\nstd::wstring<\/code><\/td>\nValue<\/td>\nMutable<\/td>\n<\/tr>\n
C#<\/td>\nString<\/code><\/td>\nReference<\/td>\nImmutable<\/td>\n<\/tr>\n
JavaScript<\/td>\nString<\/code><\/td>\nReference<\/td>\nImmutable<\/td>\n<\/tr>\n
Python<\/td>\nstr<\/code><\/td>\nReference<\/td>\nImmutable<\/td>\n<\/tr>\n
Rust<\/td>\nString<\/code><\/td>\nValue<\/td>\nMutable<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

To avoid creating problems over how to create an IReference<String><\/code> in languages where strings are already references, the Windows Runtime simply disallows IReference<String><\/code> outright.<\/p>\n

Okay, so what are your options here?<\/p>\n

If an empty string is an acceptable sentinel value to mean “No string”, then you can just take a String<\/code>. Internally, an empty HSTRING<\/code> is represented by a null pointer<\/a>, so the two cases are indistinguishable at the ABI layer.<\/p>\n

runtimeclass Widget\r\n{\r\n    Widget(String name);\r\n\r\n    \/\/ Property to get\/set the Name after construction\r\n    String Name;\r\n}\r\n<\/pre>\n
In this case, an empty name is probably what you were going to do anyway if somebody wanted to create a Widget without a name.<\/p>\n
In the above case, the optionality of the name<\/code> parameter could be expressed by an overload that simply doesn’t have a name<\/code> parameter at all.<\/p>\n
runtimeclass Widget\r\n{\r\n    Widget();            \/\/ create with no name\r\n    Widget(String name); \/\/ create with explicit name\r\n\r\n    \/\/ Property to get\/set the Name after construction\r\n    String Name;\r\n}\r\n<\/pre>\n
Here’s another case where you might be tempted to have an optional string:<\/p>\n
runtimeclass Connection\r\n{\r\n    void Connect(String token, String server);\r\n}\r\n<\/pre>\n
Maybe you want the token to be optional: If not provided, the code will obtain a new token.<\/p>\n
And maybe you want the server to be optional: If not provided, the code will use the default server.<\/p>\n
Since empty strings are probably not valid tokens or server names, you can use an empty string to mean “not provided”.<\/p>\n
But what if you want to distinguish between empty strings and no string at all?<\/p>\n
runtimeclass WidgetFilter\r\n{\r\n    WidgetFilter();\r\n\r\n    Windows.Foundation.IReference<Windows.UI.Color> Color;\r\n    Windows.Foundation.IReference<bool> Polarity;\r\n    String Title;\r\n}\r\n\r\nruntimeclass WidgetFinder\r\n{\r\n    static IVectorView<Widget> FindAll(WidgetFilter filter);\r\n}\r\n<\/pre>\n
In this case, the FindAll<\/code> method takes a WidgetFilter<\/code> which lets you specify which widgets you are looking for. You can filter by color, by polarity, and by title.<\/p>\n
The color and polarity can be represented by an IReference<\/code>, where null means “Don’t care”. But we can’t use an empty title string to mean “Don’t care”, because that would prevent us from filtering to widgets whose title is the empty string.<\/p>\n
This is, admittedly, a weird and unusual case.<\/p>\n
Unfortunately, the solution is also weird and unusual.<\/p>\n
To work around the inability to use an IReference<String><\/code>, you can box the string into an Object<\/code>.<\/p>\n
runtimeclass WidgetFilter\r\n{\r\n    WidgetFilter();\r\n\r\n    Windows.Foundation.IReference<Windows.UI.Color> Color;\r\n    Windows.Foundation.IReference<bool> Polarity;\r\n    Object Title; \/\/ null for \"don't care\" or a boxed string\r\n}\r\n\r\n\/\/ C++\/WinRT\r\nWidgetFilter filter;\r\nfilter.Title(nullptr);               \/\/ don't care\r\nfilter.Title(winrt::box_value(L\"\")); \/\/ empty string as title\r\n\r\n\/\/ C++\/CX\r\nWidgetFilter^ filter = ref new WidgetFilter();\r\nfilter->Title = nullptr;            \/\/ don't care\r\nfilter->Title = PropertyValue::CreateString(L\"\"); \/\/ (see discussion)\r\n\r\n\/\/ C#\r\nWidgetFilter filter = new WidgetFilter();\r\nfilter.Title = null;                \/\/ don't care\r\nfilter.Title = \"\";                  \/\/ empty string as title\r\n\r\n\/\/ JavaScript\r\nvar filter = new WidgetFilter();\r\nfilter.title = null;                \/\/ don't care\r\nfilter.title = \"\";                  \/\/ empty string as title\r\n<\/pre>\n
The C++\/CX case of boxing an empty string is awkward because C++\/CX tries to make strings look like objects. (Related reading:  The C++\/CX String^<\/code> is not an object, even though it wears a hat<\/a>.)<\/p>\n
To force C++\/CX to box an empty string to a non-null object, you put the empty string inside a PropertyValue<\/code>, which implements IReference<String><\/code>, and then use that as the object.<\/p>\n
To recover the string, you need to unbox.<\/p>\n
\/\/ C++\/WinRT\r\n\/\/ Version 1\r\nIInspectable title = filter.Title();\r\nif (title) {\r\n    add_title_filter(winrt::unbox_value<hstring>(title));\r\n}\r\n\r\n\/\/ Version 2\r\nIInspectable title = filter.Title();\r\nif (title) {\r\n    add_title_filter(title.as<hstring>());\r\n}\r\n\r\n\/\/ Version 3\r\nstd::optional<hstring> title = filter.Title().try_as<hstring>();\r\nif (title) {\r\n    add_title_filter(title.value());\r\n}\r\n\r\n\/\/ C++\/CX\r\nObject^ title = filter->Title;\r\nif (title) {\r\n    add_title_filter(safe_cast<String^>(title));\r\n}\r\n\r\n\/\/ C#\r\nobject title = filter.Title;\r\nif (title != null)\r\n{\r\n    add_title_filter((string)title);\r\n}\r\n\r\n\/\/ JavaScript\r\nvar title = filter.title;\r\nif (title != null)\r\n{\r\n    add_title_filter(title);\r\n}\r\n<\/pre>\n
The case of boxing a string where you need to distinguish between “no string” and “an empty string” is a weird and unusual case in the Windows Runtime. The best approach is to try to design your API so you don’t ever need to do it.<\/p>\n
For example, you could change the Title<\/code> property to a pair of methods.<\/p>\n
runtimeclass WidgetFilter\r\n{\r\n    WidgetFilter();\r\n\r\n    Windows.Foundation.IReference<Windows.UI.Color> Color;\r\n    Windows.Foundation.IReference<bool> Polarity;\r\n\r\n    void SetTitleFilter(String title);<\/span>\r\n    void ClearTitleFilter();          <\/span>\r\n}\r\n<\/pre>\n
In this way, a caller can specify “I am looking for an empty title” by calling Set\u00adTitle\u00adFilter(\"\")<\/code>, or they can specify “I don’t care about the title” by either never specifying a title filter or by clearing any previous title filter by calling Clear\u00adTitle\u00adFilter()<\/code>.<\/p>\n
On the implementation side, you can record the filter in a private std::optional<winrt::hstring><\/code> to inspect whether a filter has been applied.<\/p>\n
Another option is to use a “nullable string at home<\/a>” by pairing it with a Boolean property.<\/p>\n
runtimeclass WidgetFilter\r\n{\r\n    WidgetFilter();\r\n\r\n    Windows.Foundation.IReference<Windows.UI.Color> Color;\r\n    Windows.Foundation.IReference<bool> Polarity;\r\n\r\n    Boolean UseTitle;<\/span>\r\n    String Title;\r\n}\r\n<\/pre>\n","protected":false},"excerpt":{"rendered":"
Strings are sort of reference but sort of values.<\/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-109155","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Strings are sort of reference but sort of values.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/109155","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=109155"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/109155\/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=109155"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=109155"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=109155"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}