1/*
2 * Copyright (c) 2021 Huawei Device Co., Ltd.
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
16/** @file file_ex.h
17*
18*  @brief Provides global file operation functions implemented in c_utils.
19*/
20
21/**
22* @defgroup FileReadWrite
23* @{
24* @brief Provides interfaces for reading data from and writing data to files.
25*
26* You can use the interfaces to read data from a file, write data to a file,
27* and search for the specified string.
28*/
29
30#ifndef UTILS_BASE_FILE_EX_H
31#define UTILS_BASE_FILE_EX_H
32
33#include <string>
34#include <vector>
35#ifdef UTILS_CXX_RUST
36#include "cxx.h"
37#endif
38
39namespace OHOS {
40#ifdef UTILS_CXX_RUST
41bool RustLoadStringFromFile(const rust::String& filePath, rust::String& content);
42bool RustLoadStringFromFd(int fd, rust::String& content);
43bool RustLoadBufferFromFile(const rust::String& filePath, rust::vec<char>& content);
44bool RustSaveBufferToFile(const rust::String& filePath, const rust::vec<char>& content, bool truncated);
45bool RustSaveStringToFile(const rust::String& filePath, const rust::String& content, bool truncated);
46bool RustSaveStringToFd(int fd, const rust::String& content);
47bool RustFileExists(const rust::String& fileName);
48bool RustStringExistsInFile(const rust::String& fileName, const rust::String& subStr, bool caseSensitive);
49int  RustCountStrInFile(const rust::String& fileName, const rust::String& subStr, bool caseSensitive);
50#endif
51/**
52 * @ingroup FileReadWrite
53 * @brief Reads a string from a file.
54 *
55 * @param filePath Indicates the path of the target file.
56 * @param content Indicates the <b>std::string</b> object used to hold
57 * the data read.
58 * @return Returns <b>true</b> if the string is read successfully;
59 * returns <b>false</b> otherwise.
60 * @note The maximum file size is 32 MB.
61 */
62bool LoadStringFromFile(const std::string& filePath, std::string& content);
63
64/**
65 * @ingroup FileReadWrite
66 * @brief Writes a string to a file.
67 *
68 * @param filePath Indicates the path of the target file.
69 * @param content Indicates the <b>std::string</b> object to write.
70 * @param truncated Indicates whether to truncate the original file.
71 * @return Returns <b>true</b> if the string is written successfully;
72 * returns <b>false</b> otherwise.
73 */
74bool SaveStringToFile(const std::string& filePath, const std::string& content, bool truncated = true);
75
76/**
77 * @ingroup FileReadWrite
78 * @brief Reads a string from a file specified by its file descriptor (FD).
79 *
80 * @param fd Indicates the FD of the file to read.
81 * @param content Indicates the <b>std::string</b> object used to hold
82 * the data read.
83 * @return Returns <b>true</b> if the string is read successfully;
84 * returns <b>false</b> otherwise.
85 */
86bool LoadStringFromFd(int fd, std::string& content);
87
88/**
89 * @ingroup FileReadWrite
90 * @brief Writes a string to a file specified by its FD.
91 *
92 * @param fd Indicates the FD of the file to write.
93 * @param content Indicates the <b>std::string</b> object to write.
94 * @return Returns <b>true</b> if the string is written successfully;
95 * returns <b>false</b> otherwise.
96 */
97bool SaveStringToFd(int fd, const std::string& content);
98
99/**
100 * @ingroup FileReadWrite
101 * @brief Reads data as a vector from a file.
102 *
103 * @param filePath Indicates the path of the target file.
104 * @param content Indicates the <b>std::vector</b> object used to hold
105 * the data read.
106 * @return Returns <b>true</b> if the data is read successfully;
107 * returns <b>false</b> otherwise.
108 */
109bool LoadBufferFromFile(const std::string& filePath, std::vector<char>& content);
110
111/**
112 * @ingroup FileReadWrite
113 * @brief Writes data of a vector to a file.
114 *
115 * @param filePath Indicates the path of the target file.
116 * @param content Indicates the <b>std::vector</b> object to write.
117 * @return Returns <b>true</b> if the data is written successfully;
118 * returns <b>false</b> otherwise.
119 */
120bool SaveBufferToFile(const std::string& filePath, const std::vector<char>& content, bool truncated = true);
121
122/**
123 * @ingroup FileReadWrite
124 * @brief Checks whether a file exists.
125 *
126 * @param filePath Indicates the file to check.
127 * @return Returns <b>true</b> if the file exists; returns <b>false</b>
128 * if any error (e.g. Permission Denied) occurs.
129 */
130bool FileExists(const std::string& fileName);
131
132/**
133 * @ingroup FileReadWrite
134 * @brief Checks whether a file contains the specified string.
135 *
136 * @param fileName Indicates the path of the target file.
137 * @param subStr Indicates the <b>std::string</b> object to check.
138 * @param caseSensitive Indicates whether the string is case-sensitive.
139 * @return Returns <b>true</b> if the file contains the specified string;
140 * returns <b>false</b> otherwise.
141 */
142bool StringExistsInFile(const std::string& fileName, const std::string& subStr, bool caseSensitive = true);
143
144/**
145 * @ingroup FileReadWrite
146 * @brief Obtains the number of occurrences of the specified string in a file.
147 *
148 * @param fileName Indicates the path of the target file.
149 * @param subStr Indicates the <b>std::string</b> object to search.
150 * @param caseSensitive Indicates whether the string is case-sensitive.
151 * @return Returns the number of occurrences of the string in the file;
152 * returns <b>0</b> if <b>subStr</b> is null.
153 */
154int  CountStrInFile(const std::string& fileName, const std::string& subStr, bool caseSensitive = true);
155}
156
157#endif
158
159/**@}*/
160