blob: 8b945f55a30b433690278b44396ff94ff5842098 [file] [log] [blame]
Alexander Afanasyevc169a812014-05-20 20:37:29 -04001/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Alexander Afanasyevaf283d82014-01-03 13:23:34 -08002/**
Alexander Afanasyevc169a812014-05-20 20:37:29 -04003 * Copyright (c) 2013-2014 Regents of the University of California.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07004 *
5 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07006 *
Alexander Afanasyevc169a812014-05-20 20:37:29 -04007 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8 * terms of the GNU Lesser General Public License as published by the Free Software
9 * Foundation, either version 3 of the License, or (at your option) any later version.
10 *
11 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14 *
15 * You should have received copies of the GNU General Public License and GNU Lesser
16 * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17 * <http://www.gnu.org/licenses/>.
18 *
19 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080020 */
21
22#ifndef NDN_STRING_HELPER_HPP
23#define NDN_STRING_HELPER_HPP
24
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070025#include "../common.hpp"
26#include "../encoding/buffer.hpp"
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080027
28namespace ndn {
29
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070030class StringHelperError : public std::invalid_argument
31{
32public:
33 explicit
34 StringHelperError(const std::string& what)
35 : std::invalid_argument(what)
36 {
37 }
38};
39
40/**
41 * @brief Output the hex representation of the bytes in array to the output stream @p os
42 *
43 * @param os Output stream
44 * @param buffer The array of bytes
45 * @param length Size of the array
46 * @param isUpperCase if true (default) output use uppercase for hex values
47 *
philo7b187f52015-08-24 14:07:08 -070048 * Examples:
49 *
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070050 * printHex(std::cout, "Hello, World!") outputs "48656C6C6F2C20776F726C6421"
51 * printHex(std::cout, "Hello, World!", false) outputs "48656c6c6f2c20776f726c6421"
52 *
53 * Each octet is always represented as two hex characters ("00" for octet==0).
54 *
55 * The output string is a continuous sequence of hex characters without any whitespace separators.
56 */
57void
58printHex(std::ostream& os, const uint8_t* buffer, size_t length, bool isUpperCase = true);
59
60/**
61 * @brief Output the hex representation of the bytes in the @p buffer to the output stream @p os
62 *
63 * @param os Output stream
64 * @param buffer The array of bytes
65 * @param isUpperCase if true (default) output use uppercase for hex values
66 */
67void
68printHex(std::ostream& os, const Buffer& buffer, bool isUpperCase = true);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -080069
70/**
Alexander Afanasyev770827c2014-05-13 17:42:55 -070071 * @brief Return the hex representation of the bytes in array
72 *
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070073 * @param buffer The array of bytes
74 * @param length Size of the array
75 * @param isUpperCase if true (default) output use uppercase for hex values
76 *
philo7b187f52015-08-24 14:07:08 -070077 * Examples:
78 *
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070079 * toHex("Hello, World!") == "48656C6C6F2C20776F726C6421"
80 * toHex("Hello, World!", false) == "48656c6c6f2c20776f726c6421"
81 *
82 * Each octet is always represented as two hex characters ("00" for octet==0).
83 *
84 * The output string is a continuous sequence of hex characters without any whitespace separators.
Alexander Afanasyev809805d2014-02-17 17:20:33 -080085 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070086std::string
87toHex(const uint8_t* buffer, size_t length, bool isUpperCase = true);
Alexander Afanasyevfdbfc6d2014-04-14 15:12:11 -070088
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070089/**
90 * @brief Return the hex representation of the bytes in the @p buffer to the output stream @p os
91 *
92 * @param buffer The array of bytes
93 * @param isUpperCase if true (default) output use uppercase for hex values
94 */
95std::string
96toHex(const Buffer& buffer, bool isUpperCase = true);
Alexander Afanasyev809805d2014-02-17 17:20:33 -080097
Alexander Afanasyev8828ca62015-07-02 13:40:09 -070098/**
99 * @brief Convert the hex string to buffer
100 * @param hexString sequence of pairs of hex numbers (lower and upper case can be mixed)
101 * without any whitespace separators (e.g., "48656C6C6F2C20776F726C6421")
102 * @throw StringHelperError if input is invalid
103 */
104shared_ptr<const Buffer>
105fromHex(const std::string& hexString);
Alexander Afanasyev809805d2014-02-17 17:20:33 -0800106
107/**
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700108 * @brief Modify str in place to erase whitespace on the left
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800109 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700110void
111trimLeft(std::string& str);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800112
113/**
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700114 * @brief Modify str in place to erase whitespace on the right
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800115 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700116void
117trimRight(std::string& str);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800118
119/**
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700120 * @brief Modify str in place to erase whitespace on the left and right
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800121 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700122void
123trim(std::string& str);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800124
125/**
Alexander Afanasyev770827c2014-05-13 17:42:55 -0700126 * @brief Convert the hex character to an integer from 0 to 15, or -1 if not a hex character
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800127 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700128int
129fromHexChar(uint8_t c);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800130
131/**
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700132 * @brief Decode a percent-encoded string
133 * @see RFC 3986 section 2
134 *
135 * When % is not followed by two hex characters, the output is not transformed.
136 *
philo7b187f52015-08-24 14:07:08 -0700137 * Examples:
138 *
139 * unescape("hello%20world") == "hello world"
140 * unescape("hello%20world%FooBar") == "hello world%FooBar"
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800141 */
Alexander Afanasyev8828ca62015-07-02 13:40:09 -0700142std::string
143unescape(const std::string& str);
Alexander Afanasyevaf283d82014-01-03 13:23:34 -0800144
145} // namespace ndn
146
147#endif // NDN_STRING_HELPER_HPP