Ruby 3.5.0dev (2025-09-06 revision c0d168068f92e53c7ca67702d6d46fee35e2cc6d)
string.h
Go to the documentation of this file.
1#ifndef RBIMPL_INTERN_STRING_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RBIMPL_INTERN_STRING_H
23#include "ruby/internal/config.h"
24
25#ifdef STDC_HEADERS
26# include <stddef.h>
27#endif
28
29#ifdef HAVE_STRING_H
30# include <string.h>
31#endif
32
33#ifdef HAVE_STDINT_H
34# include <stdint.h>
35#endif
36
42#include "ruby/internal/value.h"
43#include "ruby/internal/variable.h" /* rb_gvar_setter_t */
44#include "ruby/st.h" /* st_index_t */
45
47
48/* string.c */
49
50
63VALUE rb_str_new(const char *ptr, long len);
64
76VALUE rb_str_new_cstr(const char *ptr);
77
91
103
123VALUE rb_str_new_with_class(VALUE obj, const char *ptr, long len);
124
143VALUE rb_external_str_new(const char *ptr, long len);
144
164VALUE rb_external_str_new_cstr(const char *ptr);
165
186VALUE rb_locale_str_new(const char *ptr, long len);
187
207VALUE rb_locale_str_new_cstr(const char *ptr);
208
229VALUE rb_filesystem_str_new(const char *ptr, long len);
230
250VALUE rb_filesystem_str_new_cstr(const char *ptr);
251
262
278VALUE rb_str_buf_new_cstr(const char *ptr);
279
289
303VALUE rb_usascii_str_new(const char *ptr, long len);
304
318VALUE rb_usascii_str_new_cstr(const char *ptr);
319
331VALUE rb_utf8_str_new(const char *ptr, long len);
332
346VALUE rb_utf8_str_new_cstr(const char *ptr);
347
375VALUE rb_str_new_static(const char *ptr, long len);
376
392VALUE rb_usascii_str_new_static(const char *ptr, long len);
393
409VALUE rb_utf8_str_new_static(const char *ptr, long len);
410
431VALUE rb_str_to_interned_str(VALUE str);
432
452VALUE rb_interned_str(const char *ptr, long len);
453
468VALUE rb_interned_str_cstr(const char *ptr);
469
485void rb_str_free(VALUE str);
486
503void rb_str_shared_replace(VALUE dst, VALUE src);
504
521
523VALUE rb_str_buf_cat(VALUE, const char*, long);
524
527
542VALUE rb_str_buf_cat_ascii(VALUE dst, const char *src);
543
553
567
582void rb_must_asciicompat(VALUE obj);
583
592
602
615
625
628
630#define rb_str_dup_frozen rb_str_new_frozen
631
648VALUE rb_str_plus(VALUE lhs, VALUE rhs);
649
658VALUE rb_str_times(VALUE str, VALUE num);
659
671long rb_str_sublen(VALUE str, long pos);
672
723VALUE rb_str_substr(VALUE str, long beg, long len);
724
736VALUE rb_str_subseq(VALUE str, long beg, long len);
737
751char *rb_str_subpos(VALUE str, long beg, long *len);
752
764void rb_str_modify(VALUE str);
765
779void rb_str_modify_expand(VALUE str, long capa);
780
789
813void rb_str_set_len(VALUE str, long len);
814
829VALUE rb_str_resize(VALUE str, long len);
830
842VALUE rb_str_cat(VALUE dst, const char *src, long srclen);
843
857VALUE rb_str_cat_cstr(VALUE dst, const char *src);
858
860VALUE rb_str_cat2(VALUE, const char*);
861
876
892
893/* random.c */
894
907st_index_t rb_memhash(const void *ptr, long len);
908
935st_index_t rb_hash_start(st_index_t i);
936
938#define rb_hash_uint32(h, i) st_hash_uint32((h), (i))
939
941#define rb_hash_uint(h, i) st_hash_uint((h), (i))
942
944#define rb_hash_end(h) st_hash_end(h)
945
946/* string.c */
947
964st_index_t rb_str_hash(VALUE str);
965
982int rb_str_hash_cmp(VALUE str1, VALUE str2);
983
1000int rb_str_comparable(VALUE str1, VALUE str2);
1001
1014int rb_str_cmp(VALUE lhs, VALUE rhs);
1015
1029VALUE rb_str_equal(VALUE str1, VALUE str2);
1030
1047VALUE rb_str_drop_bytes(VALUE str, long len);
1048
1067void rb_str_update(VALUE dst, long beg, long len, VALUE src);
1068
1084
1107
1121
1138VALUE rb_str_split(VALUE str, const char *delim);
1139
1146
1147/* symbol.c */
1148
1163
1164/* string.c */
1165
1178
1188long rb_str_strlen(VALUE str);
1189
1197
1207long rb_str_offset(VALUE str, long pos);
1208
1217size_t rb_str_capacity(VALUE str);
1218
1233VALUE rb_str_ellipsize(VALUE str, long len);
1234
1264VALUE rb_str_scrub(VALUE str, VALUE repl);
1265
1336VALUE rb_str_succ(VALUE orig);
1337
1347static inline long
1348rbimpl_strlen(const char *str)
1349{
1350 return RBIMPL_CAST((long)strlen(str));
1351}
1352
1362static inline VALUE
1363rbimpl_str_new_cstr(const char *str)
1364{
1365 long len = rbimpl_strlen(str);
1366 return rb_str_new_static(str, len);
1367}
1368
1378static inline VALUE
1379rbimpl_usascii_str_new_cstr(const char *str)
1380{
1381 long len = rbimpl_strlen(str);
1382 return rb_usascii_str_new_static(str, len);
1383}
1384
1394static inline VALUE
1395rbimpl_utf8_str_new_cstr(const char *str)
1396{
1397 long len = rbimpl_strlen(str);
1398 return rb_utf8_str_new_static(str, len);
1399}
1400
1410static inline VALUE
1411rbimpl_external_str_new_cstr(const char *str)
1412{
1413 long len = rbimpl_strlen(str);
1414 return rb_external_str_new(str, len);
1415}
1416
1426static inline VALUE
1427rbimpl_locale_str_new_cstr(const char *str)
1428{
1429 long len = rbimpl_strlen(str);
1430 return rb_locale_str_new(str, len);
1431}
1432
1442static inline VALUE
1443rbimpl_str_buf_new_cstr(const char *str)
1444{
1445 long len = rbimpl_strlen(str);
1446 VALUE buf = rb_str_buf_new(len);
1447 return rb_str_buf_cat(buf, str, len);
1448}
1449
1460static inline VALUE
1461rbimpl_str_cat_cstr(VALUE buf, const char *str)
1462{
1463 long len = rbimpl_strlen(str);
1464 return rb_str_cat(buf, str, len);
1465}
1466
1477static inline VALUE
1478rbimpl_exc_new_cstr(VALUE exc, const char *str)
1479{
1480 long len = rbimpl_strlen(str);
1481 return rb_exc_new(exc, str, len);
1482}
1483
1497#define rb_str_new(str, len) \
1498 ((RBIMPL_CONSTANT_P(str) && \
1499 RBIMPL_CONSTANT_P(len) ? \
1500 rb_str_new_static : \
1501 rb_str_new) ((str), (len)))
1502
1513#define rb_str_new_cstr(str) \
1514 ((RBIMPL_CONSTANT_P(str) ? \
1515 rbimpl_str_new_cstr : \
1516 rb_str_new_cstr) (str))
1517
1531#define rb_usascii_str_new(str, len) \
1532 ((RBIMPL_CONSTANT_P(str) && \
1533 RBIMPL_CONSTANT_P(len) ? \
1534 rb_usascii_str_new_static : \
1535 rb_usascii_str_new) ((str), (len)))
1536
1548#define rb_utf8_str_new(str, len) \
1549 ((RBIMPL_CONSTANT_P(str) && \
1550 RBIMPL_CONSTANT_P(len) ? \
1551 rb_utf8_str_new_static : \
1552 rb_utf8_str_new) ((str), (len)))
1553
1566#define rb_usascii_str_new_cstr(str) \
1567 ((RBIMPL_CONSTANT_P(str) ? \
1568 rbimpl_usascii_str_new_cstr : \
1569 rb_usascii_str_new_cstr) (str))
1570
1582#define rb_utf8_str_new_cstr(str) \
1583 ((RBIMPL_CONSTANT_P(str) ? \
1584 rbimpl_utf8_str_new_cstr : \
1585 rb_utf8_str_new_cstr) (str))
1586
1603#define rb_external_str_new_cstr(str) \
1604 ((RBIMPL_CONSTANT_P(str) ? \
1605 rbimpl_external_str_new_cstr : \
1606 rb_external_str_new_cstr) (str))
1607
1624#define rb_locale_str_new_cstr(str) \
1625 ((RBIMPL_CONSTANT_P(str) ? \
1626 rbimpl_locale_str_new_cstr : \
1627 rb_locale_str_new_cstr) (str))
1628
1638#define rb_str_buf_new_cstr(str) \
1639 ((RBIMPL_CONSTANT_P(str) ? \
1640 rbimpl_str_buf_new_cstr : \
1641 rb_str_buf_new_cstr) (str))
1642
1655#define rb_str_cat_cstr(buf, str) \
1656 ((RBIMPL_CONSTANT_P(str) ? \
1657 rbimpl_str_cat_cstr : \
1658 rb_str_cat_cstr) ((buf), (str)))
1659
1669#define rb_exc_new_cstr(exc, str) \
1670 ((RBIMPL_CONSTANT_P(str) ? \
1671 rbimpl_exc_new_cstr : \
1672 rb_exc_new_cstr) ((exc), (str)))
1673
1674#define rb_str_new2 rb_str_new_cstr
1675#define rb_str_new3 rb_str_new_shared
1676#define rb_str_new4 rb_str_new_frozen
1677#define rb_str_new5 rb_str_new_with_class
1678#define rb_str_buf_new2 rb_str_buf_new_cstr
1679#define rb_usascii_str_new2 rb_usascii_str_new_cstr
1680#define rb_str_buf_cat rb_str_cat
1681#define rb_str_buf_cat2 rb_str_cat_cstr
1682#define rb_str_cat2 rb_str_cat_cstr
1691#define rb_strlen_lit(str) ((sizeof(str "") / sizeof(str ""[0])) - 1)
1692
1704#define rb_str_new_lit(str) rb_str_new_static((str), rb_strlen_lit(str))
1705
1718#define rb_usascii_str_new_lit(str) rb_usascii_str_new_static((str), rb_strlen_lit(str))
1719
1732#define rb_utf8_str_new_lit(str) rb_utf8_str_new_static((str), rb_strlen_lit(str))
1733
1747#define rb_enc_str_new_lit(str, enc) rb_enc_str_new_static((str), rb_strlen_lit(str), (enc))
1748
1749#define rb_str_new_literal(str) rb_str_new_lit(str)
1750#define rb_usascii_str_new_literal(str) rb_usascii_str_new_lit(str)
1751#define rb_utf8_str_new_literal(str) rb_utf8_str_new_lit(str)
1752#define rb_enc_str_new_literal(str, enc) rb_enc_str_new_lit(str, enc)
1755
1756#endif /* RBIMPL_INTERN_STRING_H */
Defines RBIMPL_CONSTANT_P.
Defines RBIMPL_ATTR_DEPRECATED.
Tweaking visibility of C variables/functions.
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
#define rb_str_buf_cat2
Old name of rb_usascii_str_new_cstr.
Definition string.h:1681
#define rb_str_cat2
Old name of rb_str_cat_cstr.
Definition string.h:1682
VALUE rb_exc_new(VALUE etype, const char *ptr, long len)
Creates an instance of the passed exception class.
Definition error.c:1468
void rb_str_free(VALUE str)
Destroys the given string for no reason.
Definition string.c:1717
VALUE rb_str_new_shared(VALUE str)
Identical to rb_str_new_cstr(), except it takes a Ruby's string instead of C's.
Definition string.c:1487
VALUE rb_str_plus(VALUE lhs, VALUE rhs)
Generates a new string, concatenating the former to the latter.
Definition string.c:2447
#define rb_utf8_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "UTF-8" encoding.
Definition string.h:1582
VALUE rb_str_append(VALUE dst, VALUE src)
Identical to rb_str_buf_append(), except it converts the right hand side before concatenating.
Definition string.c:3757
VALUE rb_filesystem_str_new(const char *ptr, long len)
Identical to rb_str_new(), except it generates a string of "filesystem" encoding.
Definition string.c:1398
VALUE rb_sym_to_s(VALUE sym)
This is an rb_sym2str() + rb_str_dup() combo.
Definition string.c:12281
VALUE rb_str_times(VALUE str, VALUE num)
Repetition of a string.
Definition string.c:2520
VALUE rb_external_str_new(const char *ptr, long len)
Identical to rb_str_new(), except it generates a string of "default external" encoding.
Definition string.c:1374
VALUE rb_str_tmp_new(long len)
Allocates a "temporary" string.
Definition string.c:1711
long rb_str_offset(VALUE str, long pos)
"Inverse" of rb_str_sublen().
Definition string.c:3016
VALUE rb_str_succ(VALUE orig)
Searches for the "successor" of a string.
Definition string.c:5392
int rb_str_hash_cmp(VALUE str1, VALUE str2)
Compares two strings.
Definition string.c:4121
VALUE rb_str_subseq(VALUE str, long beg, long len)
Identical to rb_str_substr(), except the numbers are interpreted as byte offsets instead of character...
Definition string.c:3113
VALUE rb_str_ellipsize(VALUE str, long len)
Shortens str and adds three dots, an ellipsis, if it is longer than len characters.
Definition string.c:11580
st_index_t rb_memhash(const void *ptr, long len)
This is a universal hash function.
Definition random.c:1782
#define rb_str_new(str, len)
Allocates an instance of rb_cString.
Definition string.h:1497
void rb_str_shared_replace(VALUE dst, VALUE src)
Replaces the contents of the former with the latter.
Definition string.c:1753
#define rb_str_buf_cat
Just another name of rb_str_cat.
Definition string.h:1680
VALUE rb_str_new_static(const char *ptr, long len)
Identical to rb_str_new(), except it takes a C string literal.
Definition string.c:1164
#define rb_usascii_str_new(str, len)
Identical to rb_str_new, except it generates a string of "US ASCII" encoding.
Definition string.h:1531
size_t rb_str_capacity(VALUE str)
Queries the capacity of the given string.
Definition string.c:986
VALUE rb_str_new_frozen(VALUE str)
Creates a frozen copy of the string, if necessary.
Definition string.c:1493
VALUE rb_str_dup(VALUE str)
Duplicates a string.
Definition string.c:1956
void rb_str_modify(VALUE str)
Declares that the string is about to be modified.
Definition string.c:2696
st_index_t rb_str_hash(VALUE str)
Calculates a hash value of a string.
Definition string.c:4107
VALUE rb_str_cat(VALUE dst, const char *src, long srclen)
Destructively appends the passed contents to the string.
Definition string.c:3525
VALUE rb_str_locktmp(VALUE str)
Obtains a "temporary lock" of the string.
long rb_str_strlen(VALUE str)
Counts the number of characters (not bytes) that are stored inside of the given string.
Definition string.c:2383
VALUE rb_str_resurrect(VALUE str)
Like rb_str_dup(), but always create an instance of rb_cString regardless of the given object's class...
Definition string.c:1974
#define rb_str_buf_new_cstr(str)
Identical to rb_str_new_cstr, except done differently.
Definition string.h:1638
#define rb_usascii_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "US ASCII" encoding.
Definition string.h:1566
VALUE rb_str_replace(VALUE dst, VALUE src)
Replaces the contents of the former object with the stringised contents of the latter.
Definition string.c:6644
char * rb_str_subpos(VALUE str, long beg, long *len)
Identical to rb_str_substr(), except it returns a C's string instead of Ruby's.
Definition string.c:3121
rb_gvar_setter_t rb_str_setter
This is a rb_gvar_setter_t that refutes non-string assignments.
Definition string.h:1145
VALUE rb_interned_str_cstr(const char *ptr)
Identical to rb_interned_str(), except it assumes the passed pointer is a pointer to a C's string.
Definition string.c:12645
VALUE rb_filesystem_str_new_cstr(const char *ptr)
Identical to rb_filesystem_str_new(), except it assumes the passed pointer is a pointer to a C string...
Definition string.c:1404
#define rb_external_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "default external" encoding.
Definition string.h:1603
VALUE rb_str_buf_append(VALUE dst, VALUE src)
Identical to rb_str_cat_cstr(), except it takes Ruby's string instead of C's.
Definition string.c:3723
long rb_str_sublen(VALUE str, long pos)
Byte offset to character offset conversion.
Definition string.c:3063
VALUE rb_str_equal(VALUE str1, VALUE str2)
Equality of two strings.
Definition string.c:4228
void rb_str_set_len(VALUE str, long len)
Overwrites the length of the string.
Definition string.c:3347
st_index_t rb_hash_start(st_index_t i)
Starts a series of hashing.
Definition random.c:1776
VALUE rb_str_inspect(VALUE str)
Generates a "readable" version of the receiver.
Definition string.c:7311
void rb_must_asciicompat(VALUE obj)
Asserts that the given string's encoding is (Ruby's definition of) ASCII compatible.
Definition string.c:2750
VALUE rb_interned_str(const char *ptr, long len)
Identical to rb_str_new(), except it returns an infamous "f"string.
Definition string.c:12638
int rb_str_cmp(VALUE lhs, VALUE rhs)
Compares two strings, as in strcmp(3).
Definition string.c:4175
VALUE rb_str_concat(VALUE dst, VALUE src)
Identical to rb_str_append(), except it also accepts an integer as a codepoint.
Definition string.c:3994
int rb_str_comparable(VALUE str1, VALUE str2)
Checks if two strings are comparable each other or not.
Definition string.c:4150
VALUE rb_str_buf_cat_ascii(VALUE dst, const char *src)
Identical to rb_str_cat_cstr(), except it additionally assumes the source string be a NUL terminated ...
Definition string.c:3699
VALUE rb_str_freeze(VALUE str)
This is the implementation of String#freeze.
Definition string.c:3238
void rb_str_update(VALUE dst, long beg, long len, VALUE src)
Replaces some (or all) of the contents of the given string.
Definition string.c:5902
VALUE rb_str_scrub(VALUE str, VALUE repl)
"Cleanses" the string.
Definition string.c:11638
#define rb_locale_str_new_cstr(str)
Identical to rb_external_str_new_cstr, except it generates a string of "locale" encoding instead of "...
Definition string.h:1624
VALUE rb_str_new_with_class(VALUE obj, const char *ptr, long len)
Identical to rb_str_new(), except it takes the class of the allocating object.
Definition string.c:1667
#define rb_str_dup_frozen
Just another name of rb_str_new_frozen.
Definition string.h:630
VALUE rb_check_string_type(VALUE obj)
Try converting an object to its stringised representation using its to_str method,...
Definition string.c:2910
VALUE rb_str_substr(VALUE str, long beg, long len)
This is the implementation of two-argumented String#slice.
Definition string.c:3210
#define rb_str_cat_cstr(buf, str)
Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1655
VALUE rb_str_unlocktmp(VALUE str)
Releases a lock formerly obtained by rb_str_locktmp().
Definition string.c:3329
VALUE rb_utf8_str_new_static(const char *ptr, long len)
Identical to rb_str_new_static(), except it generates a string of "UTF-8" encoding instead of "binary...
Definition string.c:1176
#define rb_utf8_str_new(str, len)
Identical to rb_str_new, except it generates a string of "UTF-8" encoding.
Definition string.h:1548
void rb_str_modify_expand(VALUE str, long capa)
Identical to rb_str_modify(), except it additionally expands the capacity of the receiver.
Definition string.c:2704
VALUE rb_str_dump(VALUE str)
"Inverse" of rb_eval_string().
Definition string.c:7418
VALUE rb_locale_str_new(const char *ptr, long len)
Identical to rb_str_new(), except it generates a string of "locale" encoding.
Definition string.c:1386
VALUE rb_str_buf_new(long capa)
Allocates a "string buffer".
Definition string.c:1683
VALUE rb_str_length(VALUE)
Identical to rb_str_strlen(), except it returns the value in rb_cInteger.
Definition string.c:2397
#define rb_str_new_cstr(str)
Identical to rb_str_new, except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1513
VALUE rb_str_drop_bytes(VALUE str, long len)
Shrinks the given string for the given number of bytes.
Definition string.c:5820
VALUE rb_str_split(VALUE str, const char *delim)
Divides the given string based on the given delimiter.
Definition string.c:9479
VALUE rb_usascii_str_new_static(const char *ptr, long len)
Identical to rb_str_new_static(), except it generates a string of "US ASCII" encoding instead of "bin...
Definition string.c:1170
VALUE rb_str_intern(VALUE str)
Identical to rb_to_symbol(), except it assumes the receiver being an instance of RString.
Definition symbol.c:937
VALUE rb_obj_as_string(VALUE obj)
Try converting an object to its stringised representation using its to_s method, if any.
Definition string.c:1815
Declares rb_define_variable().
void rb_gvar_setter_t(VALUE val, ID id, VALUE *data)
Type that represents a global variable setter function.
Definition variable.h:46
int capa
Designed capacity of the buffer.
Definition io.h:11
int len
Length of the buffer.
Definition io.h:8
Defines RBIMPL_ATTR_NONNULL.
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull))
Definition nonnull.h:30
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition defines.h:91
Defines RBIMPL_ATTR_PURE.
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition pure.h:33
Defines VALUE and ID.
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40