arrow/util/key_value_metadata.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 #pragma once
0019
0020 #include <cstdint>
0021 #include <memory>
0022 #include <string>
0023 #include <string_view>
0024 #include <unordered_map>
0025 #include <utility>
0026 #include <vector>
0027
0028 #include "arrow/result.h"
0029 #include "arrow/status.h"
0030 #include "arrow/util/macros.h"
0031 #include "arrow/util/visibility.h"
0032
0033 namespace arrow {
0034
0035 /// \brief A container for key-value pair type metadata. Not thread-safe
0036 class ARROW_EXPORT KeyValueMetadata {
0037  public:
0038   KeyValueMetadata();
0039   KeyValueMetadata(std::vector<std::string> keys, std::vector<std::string> values);
0040   explicit KeyValueMetadata(const std::unordered_map<std::string, std::string>& map);
0041
0042   static std::shared_ptr<KeyValueMetadata> Make(std::vector<std::string> keys,
0043                                                 std::vector<std::string> values);
0044
0045   void ToUnorderedMap(std::unordered_map<std::string, std::string>* out) const;
0046   void Append(std::string key, std::string value);
0047
0048   Result<std::string> Get(std::string_view key) const;
0049   bool Contains(std::string_view key) const;
0050   // Note that deleting may invalidate known indices
0051   Status Delete(std::string_view key);
0052   Status Delete(int64_t index);
0053   Status DeleteMany(std::vector<int64_t> indices);
0054   Status Set(std::string key, std::string value);
0055
0056   void reserve(int64_t n);
0057
0058   int64_t size() const;
0059   const std::string& key(int64_t i) const;
0060   const std::string& value(int64_t i) const;
0061   const std::vector<std::string>& keys() const { return keys_; }
0062   const std::vector<std::string>& values() const { return values_; }
0063
0064   std::vector<std::pair<std::string, std::string>> sorted_pairs() const;
0065
0066   /// \brief Perform linear search for key, returning -1 if not found
0067   int FindKey(std::string_view key) const;
0068
0069   std::shared_ptr<KeyValueMetadata> Copy() const;
0070
0071   /// \brief Return a new KeyValueMetadata by combining the passed metadata
0072   /// with this KeyValueMetadata. Colliding keys will be overridden by the
0073   /// passed metadata. Assumes keys in both containers are unique
0074   std::shared_ptr<KeyValueMetadata> Merge(const KeyValueMetadata& other) const;
0075
0076   bool Equals(const KeyValueMetadata& other) const;
0077   std::string ToString() const;
0078
0079  private:
0080   std::vector<std::string> keys_;
0081   std::vector<std::string> values_;
0082
0083   ARROW_DISALLOW_COPY_AND_ASSIGN(KeyValueMetadata);
0084 };
0085
0086 /// \brief Create a KeyValueMetadata instance
0087 ///
0088 /// \param pairs key-value mapping
0089 ARROW_EXPORT std::shared_ptr<KeyValueMetadata> key_value_metadata(
0090     const std::unordered_map<std::string, std::string>& pairs);
0091
0092 /// \brief Create a KeyValueMetadata instance
0093 ///
0094 /// \param keys sequence of metadata keys
0095 /// \param values sequence of corresponding metadata values
0096 ARROW_EXPORT std::shared_ptr<KeyValueMetadata> key_value_metadata(
0097     std::vector<std::string> keys, std::vector<std::string> values);
0098
0099 }  // namespace arrow