third-party/mruby/include/mruby/string.h

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