]>
Commit | Line | Data |
---|---|---|
1d09f67e TL |
1 | // Licensed to the Apache Software Foundation (ASF) under one |
2 | // or more contributor license agreements. See the NOTICE file | |
3 | // distributed with this work for additional information | |
4 | // regarding copyright ownership. The ASF licenses this file | |
5 | // to you under the Apache License, Version 2.0 (the | |
6 | // "License"); you may not use this file except in compliance | |
7 | // with the License. You may obtain a copy of the License at | |
8 | // | |
9 | // http://www.apache.org/licenses/LICENSE-2.0 | |
10 | // | |
11 | // Unless required by applicable law or agreed to in writing, | |
12 | // software distributed under the License is distributed on an | |
13 | // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
14 | // KIND, either express or implied. See the License for the | |
15 | // specific language governing permissions and limitations | |
16 | // under the License. | |
17 | ||
18 | #pragma once | |
19 | ||
20 | #include <memory> | |
21 | #include <string> | |
22 | ||
23 | #include "arrow/c/abi.h" | |
24 | #include "arrow/result.h" | |
25 | #include "arrow/status.h" | |
26 | #include "arrow/type_fwd.h" | |
27 | #include "arrow/util/macros.h" | |
28 | #include "arrow/util/visibility.h" | |
29 | ||
30 | namespace arrow { | |
31 | ||
32 | /// \defgroup c-data-interface Functions for working with the C data interface. | |
33 | /// | |
34 | /// @{ | |
35 | ||
36 | /// \brief Export C++ DataType using the C data interface format. | |
37 | /// | |
38 | /// The root type is considered to have empty name and metadata. | |
39 | /// If you want the root type to have a name and/or metadata, pass | |
40 | /// a Field instead. | |
41 | /// | |
42 | /// \param[in] type DataType object to export | |
43 | /// \param[out] out C struct where to export the datatype | |
44 | ARROW_EXPORT | |
45 | Status ExportType(const DataType& type, struct ArrowSchema* out); | |
46 | ||
47 | /// \brief Export C++ Field using the C data interface format. | |
48 | /// | |
49 | /// \param[in] field Field object to export | |
50 | /// \param[out] out C struct where to export the field | |
51 | ARROW_EXPORT | |
52 | Status ExportField(const Field& field, struct ArrowSchema* out); | |
53 | ||
54 | /// \brief Export C++ Schema using the C data interface format. | |
55 | /// | |
56 | /// \param[in] schema Schema object to export | |
57 | /// \param[out] out C struct where to export the field | |
58 | ARROW_EXPORT | |
59 | Status ExportSchema(const Schema& schema, struct ArrowSchema* out); | |
60 | ||
61 | /// \brief Export C++ Array using the C data interface format. | |
62 | /// | |
63 | /// The resulting ArrowArray struct keeps the array data and buffers alive | |
64 | /// until its release callback is called by the consumer. | |
65 | /// | |
66 | /// \param[in] array Array object to export | |
67 | /// \param[out] out C struct where to export the array | |
68 | /// \param[out] out_schema optional C struct where to export the array type | |
69 | ARROW_EXPORT | |
70 | Status ExportArray(const Array& array, struct ArrowArray* out, | |
71 | struct ArrowSchema* out_schema = NULLPTR); | |
72 | ||
73 | /// \brief Export C++ RecordBatch using the C data interface format. | |
74 | /// | |
75 | /// The record batch is exported as if it were a struct array. | |
76 | /// The resulting ArrowArray struct keeps the record batch data and buffers alive | |
77 | /// until its release callback is called by the consumer. | |
78 | /// | |
79 | /// \param[in] batch Record batch to export | |
80 | /// \param[out] out C struct where to export the record batch | |
81 | /// \param[out] out_schema optional C struct where to export the record batch schema | |
82 | ARROW_EXPORT | |
83 | Status ExportRecordBatch(const RecordBatch& batch, struct ArrowArray* out, | |
84 | struct ArrowSchema* out_schema = NULLPTR); | |
85 | ||
86 | /// \brief Import C++ DataType from the C data interface. | |
87 | /// | |
88 | /// The given ArrowSchema struct is released (as per the C data interface | |
89 | /// specification), even if this function fails. | |
90 | /// | |
91 | /// \param[in,out] schema C data interface struct representing the data type | |
92 | /// \return Imported type object | |
93 | ARROW_EXPORT | |
94 | Result<std::shared_ptr<DataType>> ImportType(struct ArrowSchema* schema); | |
95 | ||
96 | /// \brief Import C++ Field from the C data interface. | |
97 | /// | |
98 | /// The given ArrowSchema struct is released (as per the C data interface | |
99 | /// specification), even if this function fails. | |
100 | /// | |
101 | /// \param[in,out] schema C data interface struct representing the field | |
102 | /// \return Imported field object | |
103 | ARROW_EXPORT | |
104 | Result<std::shared_ptr<Field>> ImportField(struct ArrowSchema* schema); | |
105 | ||
106 | /// \brief Import C++ Schema from the C data interface. | |
107 | /// | |
108 | /// The given ArrowSchema struct is released (as per the C data interface | |
109 | /// specification), even if this function fails. | |
110 | /// | |
111 | /// \param[in,out] schema C data interface struct representing the field | |
112 | /// \return Imported field object | |
113 | ARROW_EXPORT | |
114 | Result<std::shared_ptr<Schema>> ImportSchema(struct ArrowSchema* schema); | |
115 | ||
116 | /// \brief Import C++ array from the C data interface. | |
117 | /// | |
118 | /// The ArrowArray struct has its contents moved (as per the C data interface | |
119 | /// specification) to a private object held alive by the resulting array. | |
120 | /// | |
121 | /// \param[in,out] array C data interface struct holding the array data | |
122 | /// \param[in] type type of the imported array | |
123 | /// \return Imported array object | |
124 | ARROW_EXPORT | |
125 | Result<std::shared_ptr<Array>> ImportArray(struct ArrowArray* array, | |
126 | std::shared_ptr<DataType> type); | |
127 | ||
128 | /// \brief Import C++ array and its type from the C data interface. | |
129 | /// | |
130 | /// The ArrowArray struct has its contents moved (as per the C data interface | |
131 | /// specification) to a private object held alive by the resulting array. | |
132 | /// The ArrowSchema struct is released, even if this function fails. | |
133 | /// | |
134 | /// \param[in,out] array C data interface struct holding the array data | |
135 | /// \param[in,out] type C data interface struct holding the array type | |
136 | /// \return Imported array object | |
137 | ARROW_EXPORT | |
138 | Result<std::shared_ptr<Array>> ImportArray(struct ArrowArray* array, | |
139 | struct ArrowSchema* type); | |
140 | ||
141 | /// \brief Import C++ record batch from the C data interface. | |
142 | /// | |
143 | /// The ArrowArray struct has its contents moved (as per the C data interface | |
144 | /// specification) to a private object held alive by the resulting record batch. | |
145 | /// | |
146 | /// \param[in,out] array C data interface struct holding the record batch data | |
147 | /// \param[in] schema schema of the imported record batch | |
148 | /// \return Imported record batch object | |
149 | ARROW_EXPORT | |
150 | Result<std::shared_ptr<RecordBatch>> ImportRecordBatch(struct ArrowArray* array, | |
151 | std::shared_ptr<Schema> schema); | |
152 | ||
153 | /// \brief Import C++ record batch and its schema from the C data interface. | |
154 | /// | |
155 | /// The type represented by the ArrowSchema struct must be a struct type array. | |
156 | /// The ArrowArray struct has its contents moved (as per the C data interface | |
157 | /// specification) to a private object held alive by the resulting record batch. | |
158 | /// The ArrowSchema struct is released, even if this function fails. | |
159 | /// | |
160 | /// \param[in,out] array C data interface struct holding the record batch data | |
161 | /// \param[in,out] schema C data interface struct holding the record batch schema | |
162 | /// \return Imported record batch object | |
163 | ARROW_EXPORT | |
164 | Result<std::shared_ptr<RecordBatch>> ImportRecordBatch(struct ArrowArray* array, | |
165 | struct ArrowSchema* schema); | |
166 | ||
167 | /// @} | |
168 | ||
169 | /// \defgroup c-stream-interface Functions for working with the C data interface. | |
170 | /// | |
171 | /// @{ | |
172 | ||
173 | /// \brief EXPERIMENTAL: Export C++ RecordBatchReader using the C stream interface. | |
174 | /// | |
175 | /// The resulting ArrowArrayStream struct keeps the record batch reader alive | |
176 | /// until its release callback is called by the consumer. | |
177 | /// | |
178 | /// \param[in] reader RecordBatchReader object to export | |
179 | /// \param[out] out C struct where to export the stream | |
180 | ARROW_EXPORT | |
181 | Status ExportRecordBatchReader(std::shared_ptr<RecordBatchReader> reader, | |
182 | struct ArrowArrayStream* out); | |
183 | ||
184 | /// \brief EXPERIMENTAL: Import C++ RecordBatchReader from the C stream interface. | |
185 | /// | |
186 | /// The ArrowArrayStream struct has its contents moved to a private object | |
187 | /// held alive by the resulting record batch reader. | |
188 | /// | |
189 | /// \param[in,out] stream C stream interface struct | |
190 | /// \return Imported RecordBatchReader object | |
191 | ARROW_EXPORT | |
192 | Result<std::shared_ptr<RecordBatchReader>> ImportRecordBatchReader( | |
193 | struct ArrowArrayStream* stream); | |
194 | ||
195 | /// @} | |
196 | ||
197 | } // namespace arrow |