1 /** 2 ** @file mruby/string.h - String class 3 ** 4 ** See Copyright Notice in mruby.h 5 */ 6 7 #ifndef MRUBY_STRING_H 8 #define MRUBY_STRING_H 9 10 #include "common.h" 11 12 /** 13 * String class 14 */ 15 MRB_BEGIN_DECL 16 17 extern const char mrb_digitmap[]; 18 19 #define RSTRING_EMBED_LEN_MAX \ 20 ((mrb_int)(sizeof(void*) * 3 + sizeof(void*) - 32 / CHAR_BIT - 1)) 21 22 struct RString { 23 MRB_OBJECT_HEADER; 24 union { 25 struct { 26 mrb_ssize len; 27 union { 28 mrb_ssize capa; 29 struct mrb_shared_string *shared; 30 struct RString *fshared; 31 } aux; 32 char *ptr; 33 } heap; 34 } as; 35 }; 36 struct RStringEmbed { 37 MRB_OBJECT_HEADER; 38 char ary[]; 39 }; 40 41 #define RSTR_SET_TYPE_FLAG(s, type) (RSTR_UNSET_TYPE_FLAG(s), (s)->flags |= MRB_STR_##type) 42 #define RSTR_UNSET_TYPE_FLAG(s) ((s)->flags &= ~(MRB_STR_TYPE_MASK|MRB_STR_EMBED_LEN_MASK)) 43 44 #define RSTR_EMBED_P(s) ((s)->flags & MRB_STR_EMBED) 45 #define RSTR_SET_EMBED_FLAG(s) ((s)->flags |= MRB_STR_EMBED) 46 #define RSTR_UNSET_EMBED_FLAG(s) ((s)->flags &= ~(MRB_STR_EMBED|MRB_STR_EMBED_LEN_MASK)) 47 #define RSTR_SET_EMBED_LEN(s, n) do {\ 48 size_t tmp_n = (n);\ 49 (s)->flags &= ~MRB_STR_EMBED_LEN_MASK;\ 50 (s)->flags |= (tmp_n) << MRB_STR_EMBED_LEN_SHIFT;\ 51 } while (0) 52 #define RSTR_SET_LEN(s, n) do {\ 53 if (RSTR_EMBED_P(s)) {\ 54 RSTR_SET_EMBED_LEN((s),(n));\ 55 }\ 56 else {\ 57 (s)->as.heap.len = (mrb_ssize)(n);\ 58 }\ 59 } while (0) 60 #define RSTR_EMBED_PTR(s) (((struct RStringEmbed*)(s))->ary) 61 #define RSTR_EMBED_LEN(s)\ 62 (mrb_int)(((s)->flags & MRB_STR_EMBED_LEN_MASK) >> MRB_STR_EMBED_LEN_SHIFT) 63 #define RSTR_EMBEDDABLE_P(len) ((len) <= RSTRING_EMBED_LEN_MAX) 64 65 #define RSTR_PTR(s) ((RSTR_EMBED_P(s)) ? RSTR_EMBED_PTR(s) : (s)->as.heap.ptr) 66 #define RSTR_LEN(s) ((RSTR_EMBED_P(s)) ? RSTR_EMBED_LEN(s) : (s)->as.heap.len) 67 #define RSTR_CAPA(s) (RSTR_EMBED_P(s) ? RSTRING_EMBED_LEN_MAX : (s)->as.heap.aux.capa) 68 69 #define RSTR_SHARED_P(s) ((s)->flags & MRB_STR_SHARED) 70 #define RSTR_SET_SHARED_FLAG(s) ((s)->flags |= MRB_STR_SHARED) 71 #define RSTR_UNSET_SHARED_FLAG(s) ((s)->flags &= ~MRB_STR_SHARED) 72 73 #define RSTR_FSHARED_P(s) ((s)->flags & MRB_STR_FSHARED) 74 #define RSTR_SET_FSHARED_FLAG(s) ((s)->flags |= MRB_STR_FSHARED) 75 #define RSTR_UNSET_FSHARED_FLAG(s) ((s)->flags &= ~MRB_STR_FSHARED) 76 77 #define RSTR_NOFREE_P(s) ((s)->flags & MRB_STR_NOFREE) 78 #define RSTR_SET_NOFREE_FLAG(s) ((s)->flags |= MRB_STR_NOFREE) 79 #define RSTR_UNSET_NOFREE_FLAG(s) ((s)->flags &= ~MRB_STR_NOFREE) 80 81 #ifdef MRB_UTF8_STRING 82 # define RSTR_ASCII_P(s) ((s)->flags & MRB_STR_ASCII) 83 # define RSTR_SET_ASCII_FLAG(s) ((s)->flags |= MRB_STR_ASCII) 84 # define RSTR_UNSET_ASCII_FLAG(s) ((s)->flags &= ~MRB_STR_ASCII) 85 # define RSTR_WRITE_ASCII_FLAG(s, v) (RSTR_UNSET_ASCII_FLAG(s), (s)->flags |= v) 86 # define RSTR_COPY_ASCII_FLAG(dst, src) RSTR_WRITE_ASCII_FLAG(dst, RSTR_ASCII_P(src)) 87 #else 88 # define RSTR_ASCII_P(s) (void)0 89 # define RSTR_SET_ASCII_FLAG(s) (void)0 90 # define RSTR_UNSET_ASCII_FLAG(s) (void)0 91 # define RSTR_WRITE_ASCII_FLAG(s, v) (void)0 92 # define RSTR_COPY_ASCII_FLAG(dst, src) (void)0 93 #endif 94 95 #define RSTR_POOL_P(s) ((s)->flags & MRB_STR_POOL) 96 #define RSTR_SET_POOL_FLAG(s) ((s)->flags |= MRB_STR_POOL) 97 98 /** 99 * Returns a pointer from a Ruby string 100 */ 101 #define mrb_str_ptr(s) ((struct RString*)(mrb_ptr(s))) 102 #define RSTRING(s) mrb_str_ptr(s) 103 #define RSTRING_PTR(s) RSTR_PTR(RSTRING(s)) 104 #define RSTRING_EMBED_LEN(s) RSTR_EMBED_LEN(RSTRING(s)) 105 #define RSTRING_LEN(s) RSTR_LEN(RSTRING(s)) 106 #define RSTRING_CAPA(s) RSTR_CAPA(RSTRING(s)) 107 #define RSTRING_END(s) (RSTRING_PTR(s) + RSTRING_LEN(s)) 108 MRB_API mrb_int mrb_str_strlen(mrb_state*, struct RString*); 109 #define RSTRING_CSTR(mrb,s) mrb_string_cstr(mrb, s) 110 111 #define MRB_STR_SHARED 1 112 #define MRB_STR_FSHARED 2 113 #define MRB_STR_NOFREE 4 114 #define MRB_STR_EMBED 8 /* type flags up to here */ 115 #define MRB_STR_POOL 16 /* status flags from here */ 116 #define MRB_STR_ASCII 32 117 #define MRB_STR_EMBED_LEN_SHIFT 6 118 #define MRB_STR_EMBED_LEN_BIT 5 119 #define MRB_STR_EMBED_LEN_MASK (((1 << MRB_STR_EMBED_LEN_BIT) - 1) << MRB_STR_EMBED_LEN_SHIFT) 120 #define MRB_STR_TYPE_MASK (MRB_STR_POOL - 1) 121 122 123 void mrb_gc_free_str(mrb_state*, struct RString*); 124 125 MRB_API void mrb_str_modify(mrb_state *mrb, struct RString *s); 126 /* mrb_str_modify() with keeping ASCII flag if set */ 127 MRB_API void mrb_str_modify_keep_ascii(mrb_state *mrb, struct RString *s); 128 129 /** 130 * Finds the index of a substring in a string 131 */ 132 MRB_API mrb_int mrb_str_index(mrb_state *mrb, mrb_value str, const char *p, mrb_int len, mrb_int offset); 133 #define mrb_str_index_lit(mrb, str, lit, off) mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off); 134 135 /** 136 * Appends self to other. Returns self as a concatenated string. 137 * 138 * 139 * Example: 140 * 141 * int 142 * main(int argc, 143 * char **argv) 144 * { 145 * // Variable declarations. 146 * mrb_value str1; 147 * mrb_value str2; 148 * 149 * mrb_state *mrb = mrb_open(); 150 * if (!mrb) 151 * { 152 * // handle error 153 * } 154 * 155 * // Creates new Ruby strings. 156 * str1 = mrb_str_new_lit(mrb, "abc"); 157 * str2 = mrb_str_new_lit(mrb, "def"); 158 * 159 * // Concatenates str2 to str1. 160 * mrb_str_concat(mrb, str1, str2); 161 * 162 * // Prints new Concatenated Ruby string. 163 * mrb_p(mrb, str1); 164 * 165 * mrb_close(mrb); 166 * return 0; 167 * } 168 * 169 * Result: 170 * 171 * => "abcdef" 172 * 173 * @param mrb The current mruby state. 174 * @param self String to concatenate. 175 * @param other String to append to self. 176 * @return [mrb_value] Returns a new String appending other to self. 177 */ 178 MRB_API void mrb_str_concat(mrb_state *mrb, mrb_value self, mrb_value other); 179 180 /** 181 * Adds two strings together. 182 * 183 * 184 * Example: 185 * 186 * int 187 * main(int argc, 188 * char **argv) 189 * { 190 * // Variable declarations. 191 * mrb_value a; 192 * mrb_value b; 193 * mrb_value c; 194 * 195 * mrb_state *mrb = mrb_open(); 196 * if (!mrb) 197 * { 198 * // handle error 199 * } 200 * 201 * // Creates two Ruby strings from the passed in C strings. 202 * a = mrb_str_new_lit(mrb, "abc"); 203 * b = mrb_str_new_lit(mrb, "def"); 204 * 205 * // Prints both C strings. 206 * mrb_p(mrb, a); 207 * mrb_p(mrb, b); 208 * 209 * // Concatenates both Ruby strings. 210 * c = mrb_str_plus(mrb, a, b); 211 * 212 * // Prints new Concatenated Ruby string. 213 * mrb_p(mrb, c); 214 * 215 * mrb_close(mrb); 216 * return 0; 217 * } 218 * 219 * 220 * Result: 221 * 222 * => "abc" # First string 223 * => "def" # Second string 224 * => "abcdef" # First & Second concatenated. 225 * 226 * @param mrb The current mruby state. 227 * @param a First string to concatenate. 228 * @param b Second string to concatenate. 229 * @return [mrb_value] Returns a new String containing a concatenated to b. 230 */ 231 MRB_API mrb_value mrb_str_plus(mrb_state *mrb, mrb_value a, mrb_value b); 232 233 /** 234 * Converts pointer into a Ruby string. 235 * 236 * @param mrb The current mruby state. 237 * @param p The pointer to convert to Ruby string. 238 * @return [mrb_value] Returns a new Ruby String. 239 */ 240 MRB_API mrb_value mrb_ptr_to_str(mrb_state *mrb, void *p); 241 242 /** 243 * Returns an object as a Ruby string. 244 * 245 * @param mrb The current mruby state. 246 * @param obj An object to return as a Ruby string. 247 * @return [mrb_value] An object as a Ruby string. 248 */ 249 MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj); 250 251 /** 252 * Resizes the string's length. Returns the amount of characters 253 * in the specified by len. 254 * 255 * Example: 256 * 257 * int 258 * main(int argc, 259 * char **argv) 260 * { 261 * // Variable declaration. 262 * mrb_value str; 263 * 264 * mrb_state *mrb = mrb_open(); 265 * if (!mrb) 266 * { 267 * // handle error 268 * } 269 * // Creates a new string. 270 * str = mrb_str_new_lit(mrb, "Hello, world!"); 271 * // Returns 5 characters of 272 * mrb_str_resize(mrb, str, 5); 273 * mrb_p(mrb, str); 274 * 275 * mrb_close(mrb); 276 * return 0; 277 * } 278 * 279 * Result: 280 * 281 * => "Hello" 282 * 283 * @param mrb The current mruby state. 284 * @param str The Ruby string to resize. 285 * @param len The length. 286 * @return [mrb_value] An object as a Ruby string. 287 */ 288 MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len); 289 290 /** 291 * Returns a sub string. 292 * 293 * Example: 294 * 295 * int 296 * main(int argc, 297 * char const **argv) 298 * { 299 * // Variable declarations. 300 * mrb_value str1; 301 * mrb_value str2; 302 * 303 * mrb_state *mrb = mrb_open(); 304 * if (!mrb) 305 * { 306 * // handle error 307 * } 308 * // Creates new string. 309 * str1 = mrb_str_new_lit(mrb, "Hello, world!"); 310 * // Returns a sub-string within the range of 0..2 311 * str2 = mrb_str_substr(mrb, str1, 0, 2); 312 * 313 * // Prints sub-string. 314 * mrb_p(mrb, str2); 315 * 316 * mrb_close(mrb); 317 * return 0; 318 * } 319 * 320 * Result: 321 * 322 * => "He" 323 * 324 * @param mrb The current mruby state. 325 * @param str Ruby string. 326 * @param beg The beginning point of the sub-string. 327 * @param len The end point of the sub-string. 328 * @return [mrb_value] An object as a Ruby sub-string. 329 */ 330 MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len); 331 332 /** 333 * Returns a Ruby string type. 334 * 335 * 336 * @param mrb The current mruby state. 337 * @param str Ruby string. 338 * @return [mrb_value] A Ruby string. 339 */ 340 MRB_API mrb_value mrb_ensure_string_type(mrb_state *mrb, mrb_value str); 341 MRB_API mrb_value mrb_check_string_type(mrb_state *mrb, mrb_value str); 342 /* obsolete: use mrb_ensure_string_type() instead */ 343 MRB_API mrb_value mrb_string_type(mrb_state *mrb, mrb_value str); 344 345 346 MRB_API mrb_value mrb_str_new_capa(mrb_state *mrb, size_t capa); 347 MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa); 348 349 /* NULL terminated C string from mrb_value */ 350 MRB_API const char *mrb_string_cstr(mrb_state *mrb, mrb_value str); 351 /* NULL terminated C string from mrb_value; `str` will be updated */ 352 MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *str); 353 /* obslete: use RSTRING_PTR() */ 354 MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str); 355 /* obslete: use RSTRING_LEN() */ 356 MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str); 357 358 /** 359 * Duplicates a string object. 360 * 361 * 362 * @param mrb The current mruby state. 363 * @param str Ruby string. 364 * @return [mrb_value] Duplicated Ruby string. 365 */ 366 MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str); 367 368 /** 369 * Returns a symbol from a passed in Ruby string. 370 * 371 * @param mrb The current mruby state. 372 * @param self Ruby string. 373 * @return [mrb_value] A symbol. 374 */ 375 MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self); 376 377 MRB_API mrb_value mrb_str_to_inum(mrb_state *mrb, mrb_value str, mrb_int base, mrb_bool badcheck); 378 MRB_API mrb_value mrb_cstr_to_inum(mrb_state *mrb, const char *s, mrb_int base, mrb_bool badcheck); 379 MRB_API double mrb_str_to_dbl(mrb_state *mrb, mrb_value str, mrb_bool badcheck); 380 MRB_API double mrb_cstr_to_dbl(mrb_state *mrb, const char *s, mrb_bool badcheck); 381 382 /** 383 * Returns a converted string type. 384 * For type checking, non converting `mrb_to_str` is recommended. 385 */ 386 MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str); 387 388 /** 389 * Returns true if the strings match and false if the strings don't match. 390 * 391 * @param mrb The current mruby state. 392 * @param str1 Ruby string to compare. 393 * @param str2 Ruby string to compare. 394 * @return [mrb_value] boolean value. 395 */ 396 MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2); 397 398 /** 399 * Returns a concatenated string comprised of a Ruby string and a C string. 400 * 401 * @param mrb The current mruby state. 402 * @param str Ruby string. 403 * @param ptr A C string. 404 * @param len length of C string. 405 * @return [mrb_value] A Ruby string. 406 * @see mrb_str_cat_cstr 407 */ 408 MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len); 409 410 /** 411 * Returns a concatenated string comprised of a Ruby string and a C string. 412 * 413 * @param mrb The current mruby state. 414 * @param str Ruby string. 415 * @param ptr A C string. 416 * @return [mrb_value] A Ruby string. 417 * @see mrb_str_cat 418 */ 419 MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr); 420 MRB_API mrb_value mrb_str_cat_str(mrb_state *mrb, mrb_value str, mrb_value str2); 421 #define mrb_str_cat_lit(mrb, str, lit) mrb_str_cat(mrb, str, lit, mrb_strlen_lit(lit)) 422 423 /** 424 * Adds str2 to the end of str1. 425 */ 426 MRB_API mrb_value mrb_str_append(mrb_state *mrb, mrb_value str, mrb_value str2); 427 428 /** 429 * Returns 0 if both Ruby strings are equal. Returns a value < 0 if Ruby str1 is less than Ruby str2. Returns a value > 0 if Ruby str2 is greater than Ruby str1. 430 */ 431 MRB_API int mrb_str_cmp(mrb_state *mrb, mrb_value str1, mrb_value str2); 432 433 /** 434 * Returns a newly allocated C string from a Ruby string. 435 * This is an utility function to pass a Ruby string to C library functions. 436 * 437 * - Returned string does not contain any NUL characters (but terminator). 438 * - It raises an ArgumentError exception if Ruby string contains 439 * NUL characters. 440 * - Retured string will be freed automatically on next GC. 441 * - Caller can modify returned string without affecting Ruby string 442 * (e.g. it can be used for mkstemp(3)). 443 * 444 * @param mrb The current mruby state. 445 * @param str Ruby string. Must be an instance of String. 446 * @return [char *] A newly allocated C string. 447 */ 448 MRB_API char *mrb_str_to_cstr(mrb_state *mrb, mrb_value str); 449 450 mrb_value mrb_str_pool(mrb_state *mrb, const char *s, mrb_int len, mrb_bool nofree); 451 uint32_t mrb_str_hash(mrb_state *mrb, mrb_value str); 452 mrb_value mrb_str_dump(mrb_state *mrb, mrb_value str); 453 454 /** 455 * Returns a printable version of str, surrounded by quote marks, with special characters escaped. 456 */ 457 mrb_value mrb_str_inspect(mrb_state *mrb, mrb_value str); 458 459 /* For backward compatibility */ 460 #define mrb_str_cat2(mrb, str, ptr) mrb_str_cat_cstr(mrb, str, ptr) 461 #define mrb_str_buf_cat(mrb, str, ptr, len) mrb_str_cat(mrb, str, ptr, len) 462 #define mrb_str_buf_append(mrb, str, str2) mrb_str_cat_str(mrb, str, str2) 463 464 mrb_bool mrb_str_beg_len(mrb_int str_len, mrb_int *begp, mrb_int *lenp); 465 mrb_value mrb_str_byte_subseq(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len); 466 467 #ifdef MRB_UTF8_STRING 468 mrb_int mrb_utf8len(const char *str, const char *end); 469 mrb_int mrb_utf8_strlen(const char *str, mrb_int byte_len); 470 #endif 471 472 MRB_END_DECL 473 474 #endif /* MRUBY_STRING_H */ 475