mruby 3.3.0
mruby is the lightweight implementation of the Ruby language
Loading...
Searching...
No Matches
string.h File Reference

More...

#include "common.h"
Include dependency graph for string.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  RString
 
struct  RStringEmbed
 

Macros

#define RSTRING_EMBED_LEN_MAX    ((mrb_int)(sizeof(void*) * 3 + sizeof(void*) - 32 / CHAR_BIT - 1))
 
#define RSTR_SET_TYPE_FLAG(s, type)
 
#define RSTR_UNSET_TYPE_FLAG(s)
 
#define RSTR_EMBED_P(s)
 
#define RSTR_SET_EMBED_FLAG(s)
 
#define RSTR_UNSET_EMBED_FLAG(s)
 
#define RSTR_SET_EMBED_LEN(s, n)
 
#define RSTR_SET_LEN(s, n)
 
#define RSTR_EMBED_PTR(s)
 
#define RSTR_EMBED_LEN(s)
 
#define RSTR_EMBEDDABLE_P(len)
 
#define RSTR_PTR(s)
 
#define RSTR_LEN(s)
 
#define RSTR_CAPA(s)
 
#define RSTR_SHARED_P(s)
 
#define RSTR_SET_SHARED_FLAG(s)
 
#define RSTR_UNSET_SHARED_FLAG(s)
 
#define RSTR_FSHARED_P(s)
 
#define RSTR_SET_FSHARED_FLAG(s)
 
#define RSTR_UNSET_FSHARED_FLAG(s)
 
#define RSTR_NOFREE_P(s)
 
#define RSTR_SET_NOFREE_FLAG(s)
 
#define RSTR_UNSET_NOFREE_FLAG(s)
 
#define RSTR_ASCII_P(s)
 
#define RSTR_SET_ASCII_FLAG(s)
 
#define RSTR_UNSET_ASCII_FLAG(s)
 
#define RSTR_WRITE_ASCII_FLAG(s, v)
 
#define RSTR_COPY_ASCII_FLAG(dst, src)
 
#define mrb_str_ptr(s)
 Returns a pointer from a Ruby string.
 
#define RSTRING(s)
 
#define RSTRING_PTR(s)
 
#define RSTRING_EMBED_LEN(s)
 
#define RSTRING_LEN(s)
 
#define RSTRING_CAPA(s)
 
#define RSTRING_END(s)
 
#define RSTRING_CSTR(mrb, s)
 
#define MRB_STR_SHARED   1
 
#define MRB_STR_FSHARED   2
 
#define MRB_STR_NOFREE   4
 
#define MRB_STR_EMBED   8 /* type flags up to here */
 
#define MRB_STR_ASCII   16
 
#define MRB_STR_EMBED_LEN_SHIFT   6
 
#define MRB_STR_EMBED_LEN_BIT   5
 
#define MRB_STR_EMBED_LEN_MASK   (((1 << MRB_STR_EMBED_LEN_BIT) - 1) << MRB_STR_EMBED_LEN_SHIFT)
 
#define MRB_STR_TYPE_MASK   15
 
#define mrb_str_index_lit(mrb, str, lit, off)
 
#define mrb_str_buf_new(mrb, capa)
 
#define mrb_string_value_ptr(mrb, str)
 
#define mrb_string_value_len(mrb, str)
 
#define mrb_str_strlen(mrb, s)
 
#define mrb_str_to_inum(mrb, str, base, badcheck)
 
#define mrb_str_cat_lit(mrb, str, lit)
 
#define mrb_str_cat2(mrb, str, ptr)
 
#define mrb_str_buf_cat(mrb, str, ptr, len)
 
#define mrb_str_buf_append(mrb, str, str2)
 

Functions

void mrb_str_modify (mrb_state *mrb, struct RString *s)
 
void mrb_str_modify_keep_ascii (mrb_state *mrb, struct RString *s)
 
mrb_int mrb_str_index (mrb_state *mrb, mrb_value str, const char *p, mrb_int len, mrb_int offset)
 Finds the index of a substring in a string.
 
void mrb_str_concat (mrb_state *mrb, mrb_value self, mrb_value other)
 Appends self to other.
 
mrb_value mrb_str_plus (mrb_state *mrb, mrb_value a, mrb_value b)
 Adds two strings together.
 
mrb_value mrb_ptr_to_str (mrb_state *mrb, void *p)
 Converts pointer into a Ruby string.
 
mrb_value mrb_obj_as_string (mrb_state *mrb, mrb_value obj)
 Returns an object as a Ruby string.
 
mrb_value mrb_str_resize (mrb_state *mrb, mrb_value str, mrb_int len)
 Resizes the string's length.
 
mrb_value mrb_str_substr (mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len)
 Returns a sub string.
 
mrb_value mrb_str_new_capa (mrb_state *mrb, mrb_int capa)
 
const char * mrb_string_cstr (mrb_state *mrb, mrb_value str)
 
const char * mrb_string_value_cstr (mrb_state *mrb, mrb_value *str)
 
mrb_value mrb_str_dup (mrb_state *mrb, mrb_value str)
 Duplicates a string object.
 
mrb_value mrb_str_intern (mrb_state *mrb, mrb_value self)
 Returns a symbol from a passed in Ruby string.
 
mrb_value mrb_str_to_integer (mrb_state *mrb, mrb_value str, mrb_int base, mrb_bool badcheck)
 
double mrb_str_to_dbl (mrb_state *mrb, mrb_value str, mrb_bool badcheck)
 
mrb_bool mrb_str_equal (mrb_state *mrb, mrb_value str1, mrb_value str2)
 Returns true if the strings match and false if the strings don't match.
 
mrb_value mrb_str_cat (mrb_state *mrb, mrb_value str, const char *ptr, size_t len)
 Returns a concatenated string comprised of a Ruby string and a C string.
 
mrb_value mrb_str_cat_cstr (mrb_state *mrb, mrb_value str, const char *ptr)
 Returns a concatenated string comprised of a Ruby string and a C string.
 
mrb_value mrb_str_cat_str (mrb_state *mrb, mrb_value str, mrb_value str2)
 
mrb_value mrb_str_append (mrb_state *mrb, mrb_value str, mrb_value str2)
 Adds str2 to the end of str1.
 
int mrb_str_cmp (mrb_state *mrb, mrb_value str1, mrb_value str2)
 Returns 0 if both Ruby strings are equal.
 
char * mrb_str_to_cstr (mrb_state *mrb, mrb_value str)
 Returns a newly allocated C string from a Ruby string.
 

Variables

const char mrb_digitmap []
 String class.
 

Detailed Description

  • String class

See Copyright Notice in mruby.h

Macro Definition Documentation

◆ mrb_str_buf_append

#define mrb_str_buf_append ( mrb,
str,
str2 )
Value:
mrb_str_cat_str(mrb, str, str2)

◆ mrb_str_buf_cat

#define mrb_str_buf_cat ( mrb,
str,
ptr,
len )
Value:
mrb_str_cat(mrb, str, ptr, len)
mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len)
Returns a concatenated string comprised of a Ruby string and a C string.
Definition string.c:2701

◆ mrb_str_buf_new

#define mrb_str_buf_new ( mrb,
capa )
Value:
mrb_str_new_capa(mrb, (capa))

◆ mrb_str_cat2

#define mrb_str_cat2 ( mrb,
str,
ptr )
Value:
mrb_str_cat_cstr(mrb, str, ptr)
mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr)
Returns a concatenated string comprised of a Ruby string and a C string.
Definition string.c:2736

◆ mrb_str_cat_lit

#define mrb_str_cat_lit ( mrb,
str,
lit )
Value:
mrb_str_cat(mrb, str, lit, mrb_strlen_lit(lit))

◆ mrb_str_index_lit

#define mrb_str_index_lit ( mrb,
str,
lit,
off )
Value:
mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off);
mrb_int mrb_str_index(mrb_state *mrb, mrb_value str, const char *p, mrb_int len, mrb_int offset)
Finds the index of a substring in a string.
Definition string.c:599

◆ mrb_str_ptr

#define mrb_str_ptr ( s)
Value:
((struct RString*)(mrb_ptr(s)))
Definition string.h:22

Returns a pointer from a Ruby string.

◆ mrb_str_strlen

#define mrb_str_strlen ( mrb,
s )
Value:
strlen(RSTR_PTR(s))

◆ mrb_str_to_inum

#define mrb_str_to_inum ( mrb,
str,
base,
badcheck )
Value:
mrb_str_to_integer(mrb, str, base, badcheck)

◆ mrb_string_value_len

#define mrb_string_value_len ( mrb,
str )
Value:
RSTRING_LEN(str)

◆ mrb_string_value_ptr

#define mrb_string_value_ptr ( mrb,
str )
Value:
RSTRING_PTR(str)

◆ RSTR_ASCII_P

#define RSTR_ASCII_P ( s)
Value:
(void)0

◆ RSTR_CAPA

#define RSTR_CAPA ( s)
Value:
(RSTR_EMBED_P(s) ? RSTRING_EMBED_LEN_MAX : (s)->as.heap.aux.capa)

◆ RSTR_COPY_ASCII_FLAG

#define RSTR_COPY_ASCII_FLAG ( dst,
src )
Value:
(void)0

◆ RSTR_EMBED_LEN

#define RSTR_EMBED_LEN ( s)
Value:
(mrb_int)(((s)->flags & MRB_STR_EMBED_LEN_MASK) >> MRB_STR_EMBED_LEN_SHIFT)

◆ RSTR_EMBED_P

#define RSTR_EMBED_P ( s)
Value:
((s)->flags & MRB_STR_EMBED)

◆ RSTR_EMBED_PTR

#define RSTR_EMBED_PTR ( s)
Value:
(((struct RStringEmbed*)(s))->ary)
Definition string.h:36

◆ RSTR_EMBEDDABLE_P

#define RSTR_EMBEDDABLE_P ( len)
Value:
((len) <= RSTRING_EMBED_LEN_MAX)

◆ RSTR_FSHARED_P

#define RSTR_FSHARED_P ( s)
Value:
((s)->flags & MRB_STR_FSHARED)

◆ RSTR_LEN

#define RSTR_LEN ( s)
Value:
((RSTR_EMBED_P(s)) ? RSTR_EMBED_LEN(s) : (s)->as.heap.len)

◆ RSTR_NOFREE_P

#define RSTR_NOFREE_P ( s)
Value:
((s)->flags & MRB_STR_NOFREE)

◆ RSTR_PTR

#define RSTR_PTR ( s)
Value:
((RSTR_EMBED_P(s)) ? RSTR_EMBED_PTR(s) : (s)->as.heap.ptr)

◆ RSTR_SET_ASCII_FLAG

#define RSTR_SET_ASCII_FLAG ( s)
Value:
(void)0

◆ RSTR_SET_EMBED_FLAG

#define RSTR_SET_EMBED_FLAG ( s)
Value:
((s)->flags |= MRB_STR_EMBED)

◆ RSTR_SET_EMBED_LEN

#define RSTR_SET_EMBED_LEN ( s,
n )
Value:
do {\
size_t tmp_n = (n);\
(s)->flags &= ~MRB_STR_EMBED_LEN_MASK;\
(s)->flags |= (tmp_n) << MRB_STR_EMBED_LEN_SHIFT;\
} while (0)

◆ RSTR_SET_FSHARED_FLAG

#define RSTR_SET_FSHARED_FLAG ( s)
Value:
((s)->flags |= MRB_STR_FSHARED)

◆ RSTR_SET_LEN

#define RSTR_SET_LEN ( s,
n )
Value:
do {\
if (RSTR_EMBED_P(s)) {\
RSTR_SET_EMBED_LEN((s),(n));\
}\
else {\
(s)->as.heap.len = (mrb_ssize)(n);\
}\
} while (0)

◆ RSTR_SET_NOFREE_FLAG

#define RSTR_SET_NOFREE_FLAG ( s)
Value:
((s)->flags |= MRB_STR_NOFREE)

◆ RSTR_SET_SHARED_FLAG

#define RSTR_SET_SHARED_FLAG ( s)
Value:
((s)->flags |= MRB_STR_SHARED)

◆ RSTR_SET_TYPE_FLAG

#define RSTR_SET_TYPE_FLAG ( s,
type )
Value:
(RSTR_UNSET_TYPE_FLAG(s), (s)->flags |= MRB_STR_##type)

◆ RSTR_SHARED_P

#define RSTR_SHARED_P ( s)
Value:
((s)->flags & MRB_STR_SHARED)

◆ RSTR_UNSET_ASCII_FLAG

#define RSTR_UNSET_ASCII_FLAG ( s)
Value:
(void)0

◆ RSTR_UNSET_EMBED_FLAG

#define RSTR_UNSET_EMBED_FLAG ( s)
Value:
((s)->flags &= ~(MRB_STR_EMBED|MRB_STR_EMBED_LEN_MASK))

◆ RSTR_UNSET_FSHARED_FLAG

#define RSTR_UNSET_FSHARED_FLAG ( s)
Value:
((s)->flags &= ~MRB_STR_FSHARED)

◆ RSTR_UNSET_NOFREE_FLAG

#define RSTR_UNSET_NOFREE_FLAG ( s)
Value:
((s)->flags &= ~MRB_STR_NOFREE)

◆ RSTR_UNSET_SHARED_FLAG

#define RSTR_UNSET_SHARED_FLAG ( s)
Value:
((s)->flags &= ~MRB_STR_SHARED)

◆ RSTR_UNSET_TYPE_FLAG

#define RSTR_UNSET_TYPE_FLAG ( s)
Value:
((s)->flags &= ~(MRB_STR_TYPE_MASK|MRB_STR_EMBED_LEN_MASK))

◆ RSTR_WRITE_ASCII_FLAG

#define RSTR_WRITE_ASCII_FLAG ( s,
v )
Value:
(void)0

◆ RSTRING

#define RSTRING ( s)
Value:
#define mrb_str_ptr(s)
Returns a pointer from a Ruby string.
Definition string.h:98

◆ RSTRING_CAPA

#define RSTRING_CAPA ( s)
Value:
RSTR_CAPA(RSTRING(s))

◆ RSTRING_CSTR

#define RSTRING_CSTR ( mrb,
s )
Value:
mrb_string_cstr(mrb, s)

◆ RSTRING_EMBED_LEN

#define RSTRING_EMBED_LEN ( s)
Value:
RSTR_EMBED_LEN(RSTRING(s))

◆ RSTRING_END

#define RSTRING_END ( s)
Value:
(RSTRING_PTR(s) + RSTRING_LEN(s))

◆ RSTRING_LEN

#define RSTRING_LEN ( s)
Value:
RSTR_LEN(RSTRING(s))

◆ RSTRING_PTR

#define RSTRING_PTR ( s)
Value:
RSTR_PTR(RSTRING(s))

Function Documentation

◆ mrb_obj_as_string()

mrb_value mrb_obj_as_string ( mrb_state * mrb,
mrb_value obj )
extern

Returns an object as a Ruby string.

Parameters
mrbThe current mruby state.
objAn object to return as a Ruby string.
Returns
[mrb_value] An object as a Ruby string.

◆ mrb_ptr_to_str()

mrb_value mrb_ptr_to_str ( mrb_state * mrb,
void * p )
extern

Converts pointer into a Ruby string.

Parameters
mrbThe current mruby state.
pThe pointer to convert to Ruby string.
Returns
[mrb_value] Returns a new Ruby String.

◆ mrb_str_cat()

mrb_value mrb_str_cat ( mrb_state * mrb,
mrb_value str,
const char * ptr,
size_t len )
extern

Returns a concatenated string comprised of a Ruby string and a C string.

Parameters
mrbThe current mruby state.
strRuby string.
ptrA C string.
lenlength of C string.
Returns
[mrb_value] A Ruby string.
See also
mrb_str_cat_cstr

◆ mrb_str_cat_cstr()

mrb_value mrb_str_cat_cstr ( mrb_state * mrb,
mrb_value str,
const char * ptr )
extern

Returns a concatenated string comprised of a Ruby string and a C string.

Parameters
mrbThe current mruby state.
strRuby string.
ptrA C string.
Returns
[mrb_value] A Ruby string.
See also
mrb_str_cat

◆ mrb_str_cmp()

int mrb_str_cmp ( mrb_state * mrb,
mrb_value str1,
mrb_value str2 )
extern

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.

◆ mrb_str_concat()

void mrb_str_concat ( mrb_state * mrb,
mrb_value self,
mrb_value other )
extern

Appends self to other.

Returns self as a concatenated string.

Example:

int
main(int argc,
     char **argv)
{
  // Variable declarations.
  mrb_value str1;
  mrb_value str2;

  mrb_state *mrb = mrb_open();
  if (!mrb)
  {
     // handle error
  }

  // Creates new Ruby strings.
  str1 = mrb_str_new_lit(mrb, "abc");
  str2 = mrb_str_new_lit(mrb, "def");

  // Concatenates str2 to str1.
  mrb_str_concat(mrb, str1, str2);

  // Prints new Concatenated Ruby string.
  mrb_p(mrb, str1);

  mrb_close(mrb);
  return 0;
}

Result:

=> "abcdef"
Parameters
mrbThe current mruby state.
selfString to concatenate.
otherString to append to self.
Returns
[mrb_value] Returns a new String appending other to self.

◆ mrb_str_dup()

mrb_value mrb_str_dup ( mrb_state * mrb,
mrb_value str )
extern

Duplicates a string object.

Parameters
mrbThe current mruby state.
strRuby string.
Returns
[mrb_value] Duplicated Ruby string.

◆ mrb_str_equal()

mrb_bool mrb_str_equal ( mrb_state * mrb,
mrb_value str1,
mrb_value str2 )
extern

Returns true if the strings match and false if the strings don't match.

Parameters
mrbThe current mruby state.
str1Ruby string to compare.
str2Ruby string to compare.
Returns
[mrb_value] boolean value.

◆ mrb_str_intern()

mrb_value mrb_str_intern ( mrb_state * mrb,
mrb_value self )
extern

Returns a symbol from a passed in Ruby string.

Parameters
mrbThe current mruby state.
selfRuby string.
Returns
[mrb_value] A symbol.

◆ mrb_str_plus()

mrb_value mrb_str_plus ( mrb_state * mrb,
mrb_value a,
mrb_value b )
extern

Adds two strings together.

Example:

int
main(int argc,
     char **argv)
{
  // Variable declarations.
  mrb_value a;
  mrb_value b;
  mrb_value c;

  mrb_state *mrb = mrb_open();
  if (!mrb)
  {
     // handle error
  }

  // Creates two Ruby strings from the passed in C strings.
  a = mrb_str_new_lit(mrb, "abc");
  b = mrb_str_new_lit(mrb, "def");

  // Prints both C strings.
  mrb_p(mrb, a);
  mrb_p(mrb, b);

  // Concatenates both Ruby strings.
  c = mrb_str_plus(mrb, a, b);

  // Prints new Concatenated Ruby string.
  mrb_p(mrb, c);

  mrb_close(mrb);
  return 0;
}

Result:

=> "abc"  # First string
=> "def"  # Second string
=> "abcdef" # First & Second concatenated.
Parameters
mrbThe current mruby state.
aFirst string to concatenate.
bSecond string to concatenate.
Returns
[mrb_value] Returns a new String containing a concatenated to b.

◆ mrb_str_resize()

mrb_value mrb_str_resize ( mrb_state * mrb,
mrb_value str,
mrb_int len )
extern

Resizes the string's length.

Returns the amount of characters in the specified by len.

Example:

int
main(int argc,
     char **argv)
{
    // Variable declaration.
    mrb_value str;

    mrb_state *mrb = mrb_open();
    if (!mrb)
    {
       // handle error
    }
    // Creates a new string.
    str = mrb_str_new_lit(mrb, "Hello, world!");
    // Returns 5 characters of
    mrb_str_resize(mrb, str, 5);
    mrb_p(mrb, str);

    mrb_close(mrb);
    return 0;
 }

Result:

 => "Hello"
Parameters
mrbThe current mruby state.
strThe Ruby string to resize.
lenThe length.
Returns
[mrb_value] An object as a Ruby string.

◆ mrb_str_substr()

mrb_value mrb_str_substr ( mrb_state * mrb,
mrb_value str,
mrb_int beg,
mrb_int len )
extern

Returns a sub string.

Example:

int
main(int argc,
char const **argv)
{
  // Variable declarations.
  mrb_value str1;
  mrb_value str2;

  mrb_state *mrb = mrb_open();
  if (!mrb)
  {
    // handle error
  }
  // Creates new string.
  str1 = mrb_str_new_lit(mrb, "Hello, world!");
  // Returns a sub-string within the range of 0..2
  str2 = mrb_str_substr(mrb, str1, 0, 2);

  // Prints sub-string.
  mrb_p(mrb, str2);

  mrb_close(mrb);
  return 0;
}

Result:

=> "He"
Parameters
mrbThe current mruby state.
strRuby string.
begThe beginning point of the sub-string.
lenThe end point of the sub-string.
Returns
[mrb_value] An object as a Ruby sub-string.

◆ mrb_str_to_cstr()

char * mrb_str_to_cstr ( mrb_state * mrb,
mrb_value str )
extern

Returns a newly allocated C string from a Ruby string.

This is an utility function to pass a Ruby string to C library functions.

  • Returned string does not contain any NUL characters (but terminator).
  • It raises an ArgumentError exception if Ruby string contains NUL characters.
  • Returned string will be freed automatically on next GC.
  • Caller can modify returned string without affecting Ruby string (e.g. it can be used for mkstemp(3)).
Parameters
mrbThe current mruby state.
strRuby string. Must be an instance of String.
Returns
[char *] A newly allocated C string.