1 /*
2 * Copyright (c) 2025 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 #ifndef RUNTIME_INCLUDE_TAIHE_STRING_ABI_H_
16 #define RUNTIME_INCLUDE_TAIHE_STRING_ABI_H_
17
18 #include <taihe/common.h>
19
20 #include <stddef.h>
21 #include <stdint.h>
22
23 // Private ABI: Don't use in your code //
24
25 enum TStringFlags {
26 TSTRING_REF = 1,
27 };
28
29 struct TString {
30 uint32_t flags;
31 uint32_t length;
32 char const *ptr; // always valid and non-null
33 };
34
35 struct TStringData {
36 TRefCount count;
37 char buffer[];
38 };
39
40 // Public C API //
41
42 // Returns the buffer of the TString.
tstr_buf(struct TString tstr)43 TH_INLINE const char *tstr_buf(struct TString tstr)
44 {
45 return tstr.ptr;
46 }
47
48 // Returns the length of the TString.
tstr_len(struct TString tstr)49 TH_INLINE size_t tstr_len(struct TString tstr)
50 {
51 return tstr.length;
52 }
53
54 // Allocates memory and initializes a TString with a given capacity.
55 // # Arguments
56 // - `tstr_ptr`: Pointer to an uninitialized TString structure.
57 // - `capacity`: The desired capacity of the string buffer.
58 // # Returns
59 // - Pointer to the allocated buffer.
60 // # Notes
61 // - The caller is responsible for setting the string length.
62 // - Reference count is set to 1 after called.
63 TH_EXPORT char *tstr_initialize(struct TString *tstr_ptr, uint32_t capacity);
64
65 // Creates a new heap-allocated TString by copying an existing string.
66 // # Arguments
67 // - `buf`: A null-terminated string (must not be null).
68 // - `len`: The length of the string.
69 // # Returns
70 // - A new TString containing a copy of `buf`.
71 // # Notes
72 // - The returned TString must be freed using `tstr_drop`.
73 TH_EXPORT struct TString tstr_new(char const *buf TH_NONNULL, size_t len);
74
75 // Creates a TString from an existing string.
76 // # Arguments
77 // - `buf`: a null-terminated string. Null pointer is invalid.
78 // - `len`: the length of the string.
79 // - `tstr`: pointer to an uninitialized TString. Do not pass an
80 // already-initialized TString here.
81 // # Returns
82 // - `tstr`, if the string is created successfully. The caller must ensure the
83 // string buffer and the returned TString remain unchanged during the whole
84 // lifetime of the TString.
85 // - `NULL`, if the string is not null-terminated, or the length is too large.
86 // In this case, the original `tstr` is still uninitialized and should not be
87 // used.
88 TH_EXPORT struct TString tstr_new_ref(char const *buf TH_NONNULL, size_t len);
89
90 // Frees a TString, releasing allocated memory if applicable.
91 // # Arguments
92 // - `tstr`: The TString to be freed.
93 // # Notes
94 // - The TString should not be accessed after calling this function.
95 TH_EXPORT void tstr_drop(struct TString tstr);
96
97 // Creates a duplicate of a TString.
98 // # Arguments
99 // - `tstr`: The TString to be copied.
100 // # Returns
101 // - A new TString that is either a reference or a deep copy.
102 // # Notes
103 // - If `tstr` is heap-allocated, its reference count is incremented.
104 // - If `tstr` is a reference, a new heap-allocated copy is created.
105 // - Use `tstr_drop` to free the duplicate when done.
106 TH_EXPORT struct TString tstr_dup(struct TString tstr);
107
108 // Concatenates two TString objects.
109 // # Parameters
110 // - `count`: The number of strings to concatenate.
111 // - `tstr_list`: An array of TString objects to concatenate.
112 // # Returns
113 // - A new TString object containing the concatenated result.
114 // # Notes
115 // - The returned TString must be freed using `tstr_drop`.
116 TH_EXPORT struct TString tstr_concat(size_t count, struct TString const *tstr_list);
117
118 // Extracts a substring from a TString object.
119 // # Parameters
120 // - `tstr`: The source TString object to extract the substring from.
121 // - `pos`: The starting position of the substring within the source TString
122 // object.
123 // - `len`: The length of the substring to extract.
124 // # Returns
125 // - A TString reference of the extracted substring.
126 // # Notes
127 // - The returned TString is just a view of the original string and does not own
128 // the memory, so it should not be freed.
129 TH_EXPORT struct TString tstr_substr(struct TString tstr, size_t pos, size_t len);
130 #endif // RUNTIME_INCLUDE_TAIHE_STRING_ABI_H_