1 // Copyright (C) 2019 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //      http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef ICING_ABSL_PORTS_ANNOTATE_H_
16 #define ICING_ABSL_PORTS_ANNOTATE_H_
17 
18 #include <string_view>
19 
20 #include "icing/text_classifier/lib3/utils/base/status.h"
21 
22 namespace icing {
23 namespace lib {
24 namespace absl_ports {
25 
26 // Returns a Status that is identical to `s` except that the error_message()
27 // has been augmented by adding `msg` to the end of the original error message.
28 //
29 // Annotate should be used to add higher-level information to a Status.  E.g.,
30 //
31 //   libtextclassifier3::Status s = file::GetContents(...);
32 //   if (!s.ok()) {
33 //     return Annotate(s, "loading blacklist");
34 //   }
35 //
36 // Annotate() adds the appropriate separators, so callers should not include a
37 // separator in `msg`. The exact formatting is subject to change, so you should
38 // not depend on it in your tests.
39 //
40 // OK status values have no error message and therefore if `s` is OK, the result
41 // is unchanged.
42 libtextclassifier3::Status Annotate(const libtextclassifier3::Status& s,
43                                     std::string_view msg);
44 
45 }  // namespace absl_ports
46 }  // namespace lib
47 }  // namespace icing
48 
49 #endif  // ICING_ABSL_PORTS_ANNOTATE_H_
50