arrow/util/uri.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 <utility>
0025 #include <vector>
0026
0027 #include "arrow/type_fwd.h"
0028 #include "arrow/util/visibility.h"
0029
0030 namespace arrow::util {
0031
0032 /// \brief A parsed URI
0033 class ARROW_EXPORT Uri {
0034  public:
0035   Uri();
0036   ~Uri();
0037   Uri(Uri&&);
0038   Uri& operator=(Uri&&);
0039
0040   // XXX Should we use std::string_view instead?  These functions are
0041   // not performance-critical.
0042
0043   /// The URI scheme, such as "http", or the empty string if the URI has no
0044   /// explicit scheme.
0045   std::string scheme() const;
0046
0047   /// Convenience function that returns true if the scheme() is "file"
0048   bool is_file_scheme() const;
0049
0050   /// Whether the URI has an explicit host name.  This may return true if
0051   /// the URI has an empty host (e.g. "file:///tmp/foo"), while it returns
0052   /// false is the URI has not host component at all (e.g. "file:/tmp/foo").
0053   bool has_host() const;
0054   /// The URI host name, such as "localhost", "127.0.0.1" or "::1", or the empty
0055   /// string is the URI does not have a host component.
0056   std::string host() const;
0057
0058   /// The URI port number, as a string such as "80", or the empty string is the URI
0059   /// does not have a port number component.
0060   std::string port_text() const;
0061   /// The URI port parsed as an integer, or -1 if the URI does not have a port
0062   /// number component.
0063   int32_t port() const;
0064
0065   /// The username specified in the URI.
0066   std::string username() const;
0067   /// The password specified in the URI.
0068   std::string password() const;
0069
0070   /// The URI path component.
0071   std::string path() const;
0072
0073   /// The URI query string
0074   std::string query_string() const;
0075
0076   /// The URI query items
0077   ///
0078   /// Note this API doesn't allow differentiating between an empty value
0079   /// and a missing value, such in "a&b=1" vs. "a=&b=1".
0080   Result<std::vector<std::pair<std::string, std::string>>> query_items() const;
0081
0082   /// Get the string representation of this URI.
0083   const std::string& ToString() const;
0084
0085   /// Factory function to parse a URI from its string representation.
0086   Status Parse(const std::string& uri_string);
0087
0088   /// Factory function to parse a URI from its string representation.
0089   static Result<Uri> FromString(const std::string& uri_string);
0090
0091  private:
0092   struct Impl;
0093   std::unique_ptr<Impl> impl_;
0094 };
0095
0096 /// Percent-encode the input string, for use e.g. as a URI query parameter.
0097 ///
0098 /// This will escape directory separators, making this function unsuitable
0099 /// for encoding URI paths directly. See UriFromAbsolutePath() instead.
0100 ARROW_EXPORT
0101 std::string UriEscape(std::string_view s);
0102
0103 ARROW_EXPORT
0104 std::string UriUnescape(std::string_view s);
0105
0106 /// Encode a host for use within a URI, such as "localhost",
0107 /// "127.0.0.1", or "[::1]".
0108 ARROW_EXPORT
0109 std::string UriEncodeHost(std::string_view host);
0110
0111 /// Whether the string is a syntactically valid URI scheme according to RFC 3986.
0112 ARROW_EXPORT
0113 bool IsValidUriScheme(std::string_view s);
0114
0115 /// Create a file uri from a given absolute path
0116 ARROW_EXPORT
0117 Result<std::string> UriFromAbsolutePath(std::string_view path);
0118
0119 }  // namespace arrow::util