1 2# Upgrading 3 4This file contains instructions for users of Protozero who are upgrading from 5one version to another. 6 7You do not need to change anything if only the minor version changes, but it 8is better to keep up with changes if you can. The switch to the next major 9version will be easier then. And you might get some more convenient usage. 10 11To help you with upgrading to new versions, you can define the C++ preprocessor 12macro `PROTOZERO_STRICT_API` in which case Protozero will compile without the 13code used for backwards compatibilty. You will then get compile errors for 14older API usages. 15 16## Upgrading from *v1.6* to *v1.7* 17 18* The `pbf_writer` class is now a typedef for `basic_pbf_writer<std::string>` 19 If you have forward declared it in your code, it might have to change. 20 21## Upgrading from *v1.5* to *v1.6.0* 22 23* The `data_view` class moved from `types.hpp` into its own header file 24 `data_view.hpp`. Most people should not include those headers directly, 25 but if you do, you might have to change your includes. 26* There are two new exceptions `invalid_tag_exception` and 27 `invalid_length_exception` which cover cases that were only checked by 28 `assert` before this version. If you catch specific exceptions in your code 29 you might have to amend it. But just catching `protozero::exception` is 30 usually fine for most code (if you catch exceptions at all). 31* The `pbf_reader` constructor taking a `std::pair` is now deprecated. If you 32 are compiling with `PROTOZERO_STRICT_API` it is not available any more. Use 33 one of the other constructors instead. 34 35## Upgrading from *v1.4.5* to *v1.5.0* 36 37* New functions for checking tag and type at the same time to make your 38 program more robust. Read the section "Repeated fields in messages" in 39 the new [Advanced Topics documentation](doc/advanced.md). 40 41## Upgrading from *v1.4.4* to *v1.4.5* 42 43* The macro `PROTOZERO_DO_NOT_USE_BARE_POINTER` is not used any more. If you 44 have been setting this, remove it. 45 46## Upgrading from *v1.4.0* to *v1.4.1* 47 48* You can now do `require('protozero')` in nodejs to print the path 49 to the include paths for the protozero headers. 50 51## Upgrading from *v1.3.0* to *v1.4.0* 52 53* Functions in `pbf_reader` (and the derived `pbf_message`) called 54 `get_packed_*()` now return an `iterator_range` instead of a `std::pair`. 55 The new class is derived from `std::pair`, so changes are usually not 56 strictly necessary. For future compatibility, you should change all 57 attribute accesses on the returned objects from `first` and `second` to 58 `begin()` and `end()`, respectively. So change something like this: 59 60 auto x = message.get_packed_int32(); 61 for (auto it = x.first; it != x.second; ++it) { 62 .... 63 } 64 65 to: 66 67 auto x = message.get_packed_int32(); 68 for (auto it = x.begin(); it != x.end(); ++it) { 69 .... 70 } 71 72 or even better use the range-based for loop: 73 74 auto x = message.get_packed_int32(); 75 for (auto val : x) { 76 .... 77 } 78 79 Ranges can also be used in this way. This will change the range in-place: 80 81 auto range = message.get_packed_int32(); 82 while (!range.empty()) { 83 auto value = range.front(); 84 range.drop_front(); 85 .... 86 } 87 88* The class `pbf_reader` has a new method `get_view()` returning an object 89 of the new `protozero::data_view` class. The `data_view` only has minimal 90 functionality, but what it has is compatible to the `std::string_view` class 91 which will be coming in C++17. The view autoconverts to a `std::string` if 92 needed. Use `get_view()` instead of `get_data()` giving you a more intuitive 93 interface (call `data()` and `size()` on the view instead of using `first` 94 and `second` on the `std::pair` returned by `get_data()`). 95 96 You can set the macro `PROTOZERO_USE_VIEW` (before including `types.hpp`) to 97 the name of any class that behaves like `protozero::data_view` and 98 `data_view` will be an alias to that class instead of the implementation 99 from protozero. This way you can use the C++17 `string_view` or a similar 100 class if it is already available on your system. 101 102