1 // Copyright 2010-2021 Google LLC 2 // Licensed under the Apache License, Version 2.0 (the "License"); 3 // you may not use this file except in compliance with the License. 4 // You may obtain a copy of the License at 5 // 6 // http://www.apache.org/licenses/LICENSE-2.0 7 // 8 // Unless required by applicable law or agreed to in writing, software 9 // distributed under the License is distributed on an "AS IS" BASIS, 10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 // See the License for the specific language governing permissions and 12 // limitations under the License. 13 14 // The header defines an interface for functions taking and returning an int64_t 15 // and supporting range queries over their domain and codomain. 16 17 #ifndef OR_TOOLS_UTIL_RANGE_QUERY_FUNCTION_H_ 18 #define OR_TOOLS_UTIL_RANGE_QUERY_FUNCTION_H_ 19 20 #include <functional> 21 #include <memory> 22 23 #include "ortools/base/integral_types.h" 24 25 namespace operations_research { 26 // RangeIntToIntFunction is an interface to int64_t->int64_t functions 27 // supporting fast answer to range queries about their domain/codomain. 28 class RangeIntToIntFunction { 29 public: 30 virtual ~RangeIntToIntFunction() = default; 31 32 // Suppose f is the abstract underlying function. 33 // Returns f(argument). 34 // TODO(user): Rename to Run 35 virtual int64_t Query(int64_t argument) const = 0; 36 // Returns min_x f(x), where x is in [from, to). 37 virtual int64_t RangeMin(int64_t from, int64_t to) const = 0; 38 // Returns max_x f(x), where x is in [from, to). 39 virtual int64_t RangeMax(int64_t from, int64_t to) const = 0; 40 // Returns the first x from [range_begin, range_end) for which f(x) is in 41 // [interval_begin, interval_end), or range_end if there is no such x. 42 virtual int64_t RangeFirstInsideInterval(int64_t range_begin, 43 int64_t range_end, 44 int64_t interval_begin, 45 int64_t interval_end) const = 0; 46 // Returns the last x from [range_begin, range_end) for which f(x) is in 47 // [interval_begin, interval_end), or range_begin-1 if there is no such x. 48 virtual int64_t RangeLastInsideInterval(int64_t range_begin, 49 int64_t range_end, 50 int64_t interval_begin, 51 int64_t interval_end) const = 0; 52 }; 53 54 // RangeMinMaxIndexFunction is different from RangeIntToIntFunction in two ways: 55 // 56 // 1. It does not support codomain or value queries. 57 // 58 // 2. For domain queries it returns an argument where the minimum/maximum is 59 // attained, rather than the minimum/maximum value. 60 class RangeMinMaxIndexFunction { 61 public: 62 virtual ~RangeMinMaxIndexFunction() = default; 63 // Suppose f is the abstract underlying function. 64 // Returns an x from [from, to), such that f(x) => f(y) for every y from 65 // [from, to). 66 virtual int64_t RangeMaxArgument(int64_t from, int64_t to) const = 0; 67 // Returns an x from [from, to), such that f(x) <= f(y) for every y from 68 // [from, to). 69 virtual int64_t RangeMinArgument(int64_t from, int64_t to) const = 0; 70 }; 71 72 // A copy of f is going to be stored in the returned object, so its closure 73 // should remain intact as long as the returned object is being used. 74 RangeIntToIntFunction* MakeBareIntToIntFunction( 75 std::function<int64_t(int64_t)> f); 76 // It is assumed that f is defined over the interval [domain_start, domain_end). 77 // The function scans f once and it is safe to destroy f and its closure after 78 // MakeCachedIntToIntFunction returns. 79 RangeIntToIntFunction* MakeCachedIntToIntFunction( 80 const std::function<int64_t(int64_t)>& f, int64_t domain_start, 81 int64_t domain_end); 82 // It is safe to destroy the first argument and its closure after 83 // MakeCachedRangeMinMaxIndexFunction returns. 84 RangeMinMaxIndexFunction* MakeCachedRangeMinMaxIndexFunction( 85 const std::function<int64_t(int64_t)>& f, int64_t domain_start, 86 int64_t domain_end); 87 } // namespace operations_research 88 89 #endif // OR_TOOLS_UTIL_RANGE_QUERY_FUNCTION_H_ 90