Ruby 4.1.0dev (2026-11-16 revision 3fdd6e8fcd4f63b56b4ae6ac3c04e4604a6053ac)
string.h
1#ifndef INTERNAL_STRING_H /*-*-C-*-vi:se ft=c:*/
2#define INTERNAL_STRING_H
11#include "ruby/internal/config.h"
12#include <stddef.h> /* for size_t */
13#include "internal/compilers.h" /* for __has_builtin */
14#include "ruby/internal/stdbool.h" /* for bool */
15#include "ruby/encoding.h" /* for rb_encoding */
16#include "ruby/ruby.h" /* for VALUE */
17#include "encindex.h"
18
19#define STR_SHARED FL_USER0 /* = ELTS_SHARED */
20#define STR_NOEMBED FL_USER1
21#define STR_CHILLED FL_USER2
22#define STR_FAKESTR FL_USER19
23
24enum ruby_rstring_private_flags {
25 RSTRING_CHILLED = STR_CHILLED,
26};
27
28#ifdef rb_fstring_cstr
29# undef rb_fstring_cstr
30#endif
31
32static inline bool
33rb_str_encindex_fastpath(int encindex)
34{
35 // The overwhelming majority of strings are in one of these 3 encodings,
36 // which are all either ASCII or perfect ASCII supersets.
37 // Hence you can use fast, single byte algorithms on them, such as `memchr` etc,
38 // without all the overhead of fetching the rb_encoding and using functions such as
39 // rb_enc_mbminlen etc.
40 // Many other encodings could qualify, but they are expected to be rare occurrences,
41 // so it's better to keep that list small.
42 switch (encindex) {
43 case ENCINDEX_ASCII_8BIT:
44 case ENCINDEX_UTF_8:
45 case ENCINDEX_US_ASCII:
46 return true;
47 default:
48 return false;
49 }
50}
51
52static inline bool
53rb_str_enc_fastpath(VALUE str)
54{
55 return rb_str_encindex_fastpath(ENCODING_GET_INLINED(str));
56}
57
58static inline rb_encoding *
59rb_str_enc_get(VALUE str)
60{
62 return rb_enc_from_index(ENCODING_GET(str));
63}
64
65/* string.c */
66VALUE rb_str_dup_m(VALUE str);
67VALUE rb_fstring(VALUE);
68VALUE rb_fstring_cstr(const char *str);
69VALUE rb_fstring_enc_new(const char *ptr, rb_len_t len, rb_encoding *enc);
70int rb_str_buf_cat_escaped_char(VALUE result, unsigned int c, int unicode_p);
71int rb_str_symname_p(VALUE);
72VALUE rb_str_quote_unprintable(VALUE);
73char *rb_str_fill_terminator(VALUE str, const int termlen);
74void rb_str_change_terminator_length(VALUE str, const int oldtermlen, const int termlen);
75VALUE rb_str_locktmp_ensure(VALUE str, VALUE (*func)(VALUE), VALUE arg);
76VALUE rb_str_chomp_string(VALUE str, VALUE chomp);
77VALUE rb_external_str_with_enc(VALUE str, rb_encoding *eenc);
78VALUE rb_str_cat_conv_enc_opts(VALUE newstr, rb_len_t ofs, const char *ptr, rb_len_t len,
79 rb_encoding *from, int ecflags, VALUE ecopts);
80VALUE rb_enc_str_scrub(rb_encoding *enc, VALUE str, VALUE repl);
81VALUE rb_str_escape(VALUE str);
82size_t rb_str_memsize(VALUE);
83char *rb_str_to_cstr(VALUE str);
84const char *ruby_escaped_char(int c);
85void rb_str_make_independent(VALUE str);
86int rb_enc_str_coderange_scan(VALUE str, rb_encoding *enc);
87int rb_ascii8bit_appendable_encoding_index(rb_encoding *enc, unsigned int code);
88VALUE rb_str_include(VALUE str, VALUE arg);
89VALUE rb_str_byte_substr(VALUE str, VALUE beg, VALUE len);
90VALUE rb_str_substr_two_fixnums(VALUE str, VALUE beg, VALUE len, int empty);
91void rb_str_make_embedded(VALUE);
92void rb_str_make_heap(VALUE str);
93VALUE rb_str_upto_each(VALUE, VALUE, int, int (*each)(VALUE, VALUE), VALUE);
94size_t rb_str_size_as_embedded(VALUE);
95bool rb_str_reembeddable_p(VALUE);
96bool rb_str_embedded_shared_root_p(VALUE);
97VALUE rb_str_upto_endless_each(VALUE, int (*each)(VALUE, VALUE), VALUE);
98VALUE rb_str_with_debug_created_info(VALUE, VALUE, int);
99VALUE rb_chilled_str_with_debug_created_info(VALUE, VALUE, int);
100VALUE rb_str_frozen_bare_string(VALUE);
101const char *rb_str_null_check(VALUE);
102VALUE rb_str_casecmp(VALUE str1, VALUE str2);
103VALUE rb_str_s_new(int argc, VALUE *argv, VALUE klass);
104
105/* error.c */
106void rb_warn_unchilled_literal(VALUE str);
107
108static inline bool STR_EMBED_P(VALUE str);
109static inline bool STR_SHARED_P(VALUE str);
110static inline VALUE QUOTE(VALUE v);
111static inline VALUE QUOTE_ID(ID v);
112static inline bool is_ascii_string(VALUE str);
113static inline bool is_broken_string(VALUE str);
114static inline VALUE rb_str_eql_internal(const VALUE str1, const VALUE str2);
115
116RUBY_SYMBOL_EXPORT_BEGIN
117/* string.c (export) */
118VALUE rb_str_tmp_frozen_acquire(VALUE str);
119void rb_str_tmp_frozen_release(VALUE str, VALUE tmp);
120VALUE rb_setup_fake_str(struct RString *fake_str, const char *name, rb_len_t len, rb_encoding *enc);
121RUBY_SYMBOL_EXPORT_END
122
123VALUE rb_fstring_new(const char *ptr, rb_len_t len);
124void rb_gc_free_fstring(VALUE obj);
125bool rb_obj_is_fstring_table(VALUE obj);
126void Init_fstring_table();
127VALUE rb_obj_as_string_result(VALUE str, VALUE obj);
128VALUE rb_str_alloc_enc_capa(VALUE klass, VALUE encoding, VALUE capacity);
129VALUE rb_str_opt_plus(VALUE x, VALUE y);
130VALUE rb_str_new_owned(char *ptr, rb_len_t len, rb_len_t capa, int encindex);
131VALUE rb_str_concat_literals(size_t num, const VALUE *strary);
132VALUE rb_str_format_ary(int argc, const VALUE *argv, VALUE fmt, VALUE ary);
133VALUE rb_str_eql(VALUE str1, VALUE str2);
134VALUE rb_id_quote_unprintable(ID);
135VALUE rb_sym_proc_call(ID mid, int argc, const VALUE *argv, int kw_splat, VALUE passed_proc);
136VALUE rb_enc_literal_str(const char *ptr, rb_len_t len, rb_encoding *enc);
137
139VALUE rb_ec_str_resurrect(struct rb_execution_context_struct *ec, VALUE str, bool chilled);
140
141#define rb_fstring_lit(str) rb_fstring_new((str), rb_strlen_lit(str))
142#define rb_fstring_literal(str) rb_fstring_lit(str)
143#define rb_fstring_enc_lit(str, enc) rb_fstring_enc_new((str), rb_strlen_lit(str), (enc))
144#define rb_fstring_enc_literal(str, enc) rb_fstring_enc_lit(str, enc)
145
146static inline VALUE
147QUOTE(VALUE v)
148{
149 return rb_str_quote_unprintable(v);
150}
151
152static inline VALUE
153QUOTE_ID(ID i)
154{
155 return rb_id_quote_unprintable(i);
156}
157
158static inline bool
159STR_EMBED_P(VALUE str)
160{
161 return ! FL_TEST_RAW(str, STR_NOEMBED);
162}
163
164static inline bool
165STR_SHARED_P(VALUE str)
166{
167 return FL_ALL_RAW(str, STR_NOEMBED | STR_SHARED);
168}
169
170static inline bool
171CHILLED_STRING_P(VALUE obj)
172{
173 return RB_TYPE_P(obj, T_STRING) && FL_TEST_RAW(obj, STR_CHILLED);
174}
175
176static inline void
177CHILLED_STRING_MUTATED(VALUE str)
178{
179 if (RB_FL_TEST_RAW(str, STR_CHILLED)) {
180 FL_UNSET_RAW(str, STR_CHILLED);
181 rb_warn_unchilled_literal(str);
182 }
183}
184
185static inline bool
186is_ascii_string(VALUE str)
187{
188 return rb_enc_str_coderange(str) == ENC_CODERANGE_7BIT;
189}
190
191static inline bool
192is_broken_string(VALUE str)
193{
194 return rb_enc_str_coderange(str) == ENC_CODERANGE_BROKEN;
195}
196
197NORETURN(void rb_str_invalid_byte_sequence(VALUE str));
198static inline void
199mustnot_broken(VALUE str)
200{
201 if (is_broken_string(str)) rb_str_invalid_byte_sequence(str);
202}
203
204NORETURN(void rb_str_unexpect_wchar(VALUE str));
205static inline void
206mustnot_wchar(VALUE str)
207{
208 rb_encoding *enc = rb_enc_from_index(ENCODING_GET(str));
209 if (rb_enc_mbminlen(enc) > 1) rb_str_unexpect_wchar(str);
210}
211
212static inline bool
213at_char_boundary(const char *s, const char *p, const char *e, rb_encoding *enc)
214{
215 return rb_enc_left_char_head(s, p, e, enc) == p;
216}
217
218static inline bool
219at_char_right_boundary(const char *s, const char *p, const char *e, rb_encoding *enc)
220{
221 RUBY_ASSERT(s <= p);
222 RUBY_ASSERT(p <= e);
223
224 return rb_enc_right_char_head(s, p, e, enc) == p;
225}
226
227/* expect tail call optimization */
228// YJIT needs this function to never allocate and never raise
229static inline VALUE
230rb_str_eql_internal(const VALUE str1, const VALUE str2)
231{
232 const rb_len_t len = RSTRING_LEN(str1);
233 const char *ptr1, *ptr2;
234
235 if (len != RSTRING_LEN(str2)) return Qfalse;
236 if (!rb_str_comparable(str1, str2)) return Qfalse;
237 if ((ptr1 = RSTRING_PTR(str1)) == (ptr2 = RSTRING_PTR(str2)))
238 return Qtrue;
239 if (memcmp(ptr1, ptr2, len) == 0)
240 return Qtrue;
241 return Qfalse;
242}
243
244static inline bool
245rb_streql_cstr(VALUE str, const char *lit, size_t len)
246{
247 if ((size_t)RSTRING_LEN(str) != len) return false;
248 return memcmp(RSTRING_PTR(str), lit, len) == 0;
249}
250#define rb_streql_lit(str, lit) rb_streql_cstr(str, lit, rb_strlen_lit(lit))
251
252#if __has_builtin(__builtin_constant_p)
253# define rb_fstring_cstr(str) \
254 (__builtin_constant_p(str) ? \
255 rb_fstring_new((str), (rb_len_t)strlen(str)) : \
256 (rb_fstring_cstr)(str))
257#endif
258#endif /* INTERNAL_STRING_H */
static VALUE RB_FL_TEST_RAW(VALUE obj, VALUE flags)
This is an implementation detail of RB_FL_TEST().
Definition fl_type.h:407
#define ENC_CODERANGE_7BIT
Old name of RUBY_ENC_CODERANGE_7BIT.
Definition coderange.h:180
#define FL_UNSET_RAW
Old name of RB_FL_UNSET_RAW.
Definition fl_type.h:130
#define T_STRING
Old name of RUBY_T_STRING.
Definition value_type.h:78
#define ENCODING_GET(obj)
Old name of RB_ENCODING_GET.
Definition encoding.h:109
#define FL_TEST_RAW
Old name of RB_FL_TEST_RAW.
Definition fl_type.h:128
#define Qtrue
Old name of RUBY_Qtrue.
#define Qfalse
Old name of RUBY_Qfalse.
#define ENC_CODERANGE_BROKEN
Old name of RUBY_ENC_CODERANGE_BROKEN.
Definition coderange.h:182
#define FL_ALL_RAW
Old name of RB_FL_ALL_RAW.
Definition fl_type.h:120
#define ENCODING_GET_INLINED(obj)
Old name of RB_ENCODING_GET_INLINED.
Definition encoding.h:108
#define RUBY_ASSERT(...)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:219
Encoding relates APIs.
static char * rb_enc_left_char_head(const char *s, const char *p, const char *e, rb_encoding *enc)
Queries the left boundary of a character.
Definition encoding.h:683
static char * rb_enc_right_char_head(const char *s, const char *p, const char *e, rb_encoding *enc)
Queries the right boundary of a character.
Definition encoding.h:704
int rb_str_comparable(VALUE str1, VALUE str2)
Checks if two strings are comparable each other or not.
Definition string.c:4357
int capa
Designed capacity of the buffer.
Definition io.h:11
int len
Length of the buffer.
Definition io.h:8
C99 shim for <stdbool.h>
Ruby's String.
Definition rstring.h:196
long rb_len_t
A signed integer type for lengths and indices of objects such as String and Array.
Definition value.h:142
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
static bool RB_TYPE_P(VALUE obj, enum ruby_value_type t)
Queries if the given object is of given type.
Definition value_type.h:376