{"id":324,"date":"2024-08-27T19:41:36","date_gmt":"2024-08-27T19:41:36","guid":{"rendered":"https:\/\/permutationcity.co.uk\/bp\/?p=324"},"modified":"2024-08-26T08:40:05","modified_gmt":"2024-08-26T08:40:05","slug":"api-lock-in","status":"publish","type":"post","link":"https:\/\/permutationcity.co.uk\/bp\/2024\/08\/27\/api-lock-in\/","title":{"rendered":"API lock-in"},"content":{"rendered":"\n

When C# first came out it didn’t have generics<\/a>,\nthat didn’t come out until\nversion 2.0<\/a>.\nThat meant that, say, the user interface APIs either had to deal with collections of unknown objects or\nbe use custom written collections.\nIf they did one you don’t know what object you have;\nif you do the other then you can’t process the collections with standard tools.\nI’d like to be more specific but Microsoft hasn’t kept all the documentation available that far back.\nIt’s probably somewhere on the Wayback Machine<\/a> but\nI couldn’t chase it down.\nThen generics did<\/em> come out but the existing APIs were already written,\nwe were locked in to the old way of doing things.<\/p>\n\n\n\n

Old-fashioned find<\/h2>\n\n\n\n

I started on this track thinking about the interface of\nstd::find<\/code><\/a>.\nIf you want to search a collection in C++ you might well do something like this:<\/p>\n\n\n\n

    const auto i = std::ranges::find(numbers, 7);\n    if (i != numbers.end()) {\n        std::out << "Your lucky number was at position " <<\n            std::distance(i - numbers.begin()) << std::endl;\n    }<\/pre><\/div>\n\n\n\n
This works but I feel the i != numbers.end()<\/code> is clunky.\nAnother language might do it differently:<\/p>\n\n\n\n
    int index = numbers.IndexOf(7);\n    if (index != -1) {\n        Console.WriteLine("Your lucky number was at position {0}", index);\n    }<\/pre><\/div>\n\n\n\n
That’s less clunky but you’re still left comparing the against magic number.\nIt’s what we’ve always done.\nHowever it leaves room for writing this:<\/p>\n\n\n\n
    int index = numbers.IndexOf(7);\n    Console.WriteLine("Your lucky number was at position {0}", index);<\/pre><\/div>\n\n\n\n
Which might work or it might not.\nIf the developer has thought everything through then the list always contains the lucky number.\nMaybe the list did always contain the lucky number until something else in the codebase changed.\nThe worst this will do is print out -1<\/code> but\nif you’re accessing data then you’re out of bounds.<\/p>\n\n\n\n
In any case I thought the interface to std::find<\/code> looked a bit old fashioned.\nWhat might it look like if they were writing it today:<\/p>\n\n\n\n
template <typename Range, typename T>\nstd::optional<Range::iterator> find(const Range& range, const T& value);<\/pre><\/div>\n\n\n\n
So rather than returning an iterator directly it returns an optional iterator.\nThat means you can know directly whether it was successful or not:<\/p>\n\n\n\n
    const auto i = std::ranges::find(numbers, 7);\n    if (i.has_value()) {\n        const auto index = std::distance(i.value() - numbers.begin());\n        std::out << "Your lucky number was at position " << index << std::endl;\n    }<\/pre><\/div>\n\n\n\n
I think that’s less clunky than the original.\nWe’re not doing a mysterious comparison were asking a specific question about our result.\nThat example is overly wordy.\nToday I’d probably write it like this:<\/p>\n\n\n\n
    if (const auto i = std::ranges::find(numbers, 7)) {\n        std::out << "Your lucky number was at position " <<\n            std::distance(i.value() - numbers.begin()) << std::endl;\n    }<\/pre><\/div>\n\n\n\n
The optional type is automatically converted to a boolean when evaluating the if-statement. Of course there is still room to be careless:<\/p>\n\n\n\n
    const auto i = std::ranges::find(numbers, 7);\n    std::out << "Your lucky number was at position " <<\n        std::distance(i.value() - numbers.begin()) << std::endl;<\/pre><\/div>\n\n\n\n
But i<\/code> isn’t a dumb iterator here, it’s an optional iterator.\nIt “knows” whether you found something or not.\nIt’s never going to print out -1<\/code>, it’ll\nthrow an exception<\/a>\ninstead.\nYou can<\/em> still shoot yourself in the foot using\n*i<\/code><\/a>\nwhich doesn’t perform any checks.<\/p>\n\n\n\n
Are there any downsides?\nI don’t know how std::optional<\/code> is implemented but there’s probably a slight space overhead.\nIt probably stores an extra boolean to determine whether the value is present or not.\nWe’re probably going to use the iterator immediately so that’s not too much cost.\nHaving an extra check with every value()<\/code> access might matter more.\nI tried to do\nsome performance tests<\/a>\nbut the old and new style seem neck and neck.\nIt could be that as long as the check is done once the optimiser can get rid of any repetitions.\nLooking at the assembly on Compiler Explorer<\/a> that seems to be right.<\/p>\n\n\n\n
This new style seems to have potential.\nI’ve added it to my own library of code so I can see how it works out long term.<\/p>\n\n\n\n
Locked in<\/h2>\n\n\n\n
This post isn’t really about a new-style find<\/code>.\nIt’s about the more general problem fixed APIs.\nMaybe the standards group for C++<\/a> had the same idea last year but\nthere are already millions of lines of code using the old-style std::find<\/code>,\nthey can’t just change it.<\/p>\n\n\n\n
There are more traditional ways of extending APIs:<\/p>\n\n\n\n