Header: mruby/string.h

Overview

String class

Function Summary

• mrb_int mrb_str_strlen(mrb_state*, struct RString*)
• void mrb_str_modify(mrb_state *, struct RString *)
• void mrb_str_modify_keep_ascii(mrb_state *, struct RString *)

  mrb_str_modify() with keeping ASCII flag if set.

• mrb_int mrb_str_index(mrb_state *, mrb_value, const char *, mrb_int, mrb_int)

  Finds the index of a substring in a string.

• void mrb_str_concat(mrb_state *, mrb_value, mrb_value)

  Appends self to other.

• mrb_value mrb_str_plus(mrb_state *, mrb_value, mrb_value)

  Adds two strings together.

• mrb_value mrb_ptr_to_str(mrb_state *, void *)

  Converts pointer into a Ruby string.

• mrb_value mrb_obj_as_string(mrb_state *, mrb_value)

  Returns an object as a Ruby string.

• mrb_value mrb_str_resize(mrb_state *, mrb_value, mrb_int)

  Resizes the string’s length.

• mrb_value mrb_str_substr(mrb_state *, mrb_value, mrb_int, mrb_int)

  Returns a sub string.

• mrb_value mrb_ensure_string_type(mrb_state *, mrb_value)

  Returns a Ruby string type.

• mrb_value mrb_check_string_type(mrb_state *, mrb_value)
• mrb_value mrb_string_type(mrb_state *, mrb_value)

  obsolete: use mrb_ensure_string_type() instead.

• mrb_value mrb_str_new_capa(mrb_state *, size_t)
• mrb_value mrb_str_buf_new(mrb_state *, size_t)
• mrb_int mrb_string_value_len(mrb_state *, mrb_value)

  obslete: use RSTRING_LEN().

• mrb_value mrb_str_dup(mrb_state *, mrb_value)

  Duplicates a string object.

• mrb_value mrb_str_intern(mrb_state *, mrb_value)

  Returns a symbol from a passed in Ruby string.

• mrb_value mrb_str_to_inum(mrb_state *, mrb_value, mrb_int, mrb_bool)
• mrb_value mrb_cstr_to_inum(mrb_state *, const char *, mrb_int, mrb_bool)
• double mrb_str_to_dbl(mrb_state *, mrb_value, mrb_bool)
• double mrb_cstr_to_dbl(mrb_state *, const char *, mrb_bool)
• mrb_value mrb_str_to_str(mrb_state *, mrb_value)

  Returns a converted string type.

• mrb_bool mrb_str_equal(mrb_state *, mrb_value, mrb_value)

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

• mrb_value mrb_str_cat(mrb_state *, mrb_value, const char *, size_t)

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

• mrb_value mrb_str_cat_cstr(mrb_state *, mrb_value, const char *)

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

• mrb_value mrb_str_cat_str(mrb_state *, mrb_value, mrb_value)
• mrb_value mrb_str_append(mrb_state *, mrb_value, mrb_value)

  Adds str2 to the end of str1.

• int mrb_str_cmp(mrb_state *, mrb_value, mrb_value)

  Returns 0 if both Ruby strings are equal.

• char * mrb_str_to_cstr(mrb_state *, mrb_value)

  Returns a newly allocated C string from a Ruby string.

Define Summary

#define MRUBY_STRING_H

#define RSTRING_EMBED_LEN_MAX

#define RSTR_SET_TYPE_FLAG

#define RSTR_UNSET_TYPE_FLAG

#define RSTR_EMBED_P

#define RSTR_SET_EMBED_FLAG

#define RSTR_UNSET_EMBED_FLAG

#define RSTR_SET_EMBED_LEN

#define RSTR_SET_LEN

#define RSTR_EMBED_PTR

#define RSTR_EMBED_LEN

#define RSTR_EMBEDDABLE_P

#define RSTR_PTR

#define RSTR_LEN

#define RSTR_CAPA

#define RSTR_SHARED_P

#define RSTR_SET_SHARED_FLAG

#define RSTR_UNSET_SHARED_FLAG

#define RSTR_FSHARED_P

#define RSTR_SET_FSHARED_FLAG

#define RSTR_UNSET_FSHARED_FLAG

#define RSTR_NOFREE_P

#define RSTR_SET_NOFREE_FLAG

#define RSTR_UNSET_NOFREE_FLAG

#define RSTR_ASCII_P

#define RSTR_SET_ASCII_FLAG

#define RSTR_UNSET_ASCII_FLAG

#define RSTR_WRITE_ASCII_FLAG

#define RSTR_COPY_ASCII_FLAG

#define RSTR_POOL_P

#define RSTR_SET_POOL_FLAG

#define mrb_str_ptr

Returns a pointer from a Ruby string

#define RSTRING

#define RSTRING_PTR

#define RSTRING_EMBED_LEN

#define RSTRING_LEN

#define RSTRING_CAPA

#define RSTRING_END

#define RSTRING_CSTR

#define MRB_STR_SHARED

#define MRB_STR_FSHARED

#define MRB_STR_NOFREE

#define MRB_STR_EMBED

#define MRB_STR_POOL

#define MRB_STR_ASCII

#define MRB_STR_EMBED_LEN_SHIFT

#define MRB_STR_EMBED_LEN_BITSIZE

#define MRB_STR_EMBED_LEN_MASK

#define MRB_STR_TYPE_MASK

#define mrb_str_index_lit

#define mrb_str_cat_lit

#define mrb_str_cat2

For backward compatibility

#define mrb_str_buf_cat

#define mrb_str_buf_append

Function Details

mrb_int mrb_str_strlen(mrb_state* , struct RString* )

void mrb_str_modify(mrb_state * mrb, struct RString * s)

void mrb_str_modify_keep_ascii(mrb_state * mrb, struct RString * s)

mrb_str_modify() with keeping ASCII flag if set

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. 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:

• mrb —

  The current mruby state.

• self —

  String to concatenate.

• other —

  String to append to self.

Returns:

• (mrb_value) —

  Returns a new String appending other to self.

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

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:

• mrb —

  The current mruby state.

• a —

  First string to concatenate.

• b —

  Second string to concatenate.

Returns:

• (mrb_value) —

  Returns a new String containing a concatenated to b.

mrb_value mrb_ptr_to_str(mrb_state * mrb, void * p)

Converts pointer into a Ruby string.

Parameters:

• mrb —

  The current mruby state.

• p —

  The pointer to convert to Ruby string.

Returns:

• (mrb_value) —

  Returns a new Ruby String.

mrb_value mrb_obj_as_string(mrb_state * mrb, mrb_value obj)

Returns an object as a Ruby string.

Parameters:

• mrb —

  The current mruby state.

• obj —

  An object to return as a Ruby string.

Returns:

• (mrb_value) —

  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. 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:

• mrb —

  The current mruby state.

• str —

  The Ruby string to resize.

• len —

  The length.

Returns:

• (mrb_value) —

  An object as a Ruby string.

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

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:

• mrb —

  The current mruby state.

• str —

  Ruby string.

• beg —

  The beginning point of the sub-string.

• len —

  The end point of the sub-string.

Returns:

• (mrb_value) —

  An object as a Ruby sub-string.

mrb_value mrb_ensure_string_type(mrb_state * mrb, mrb_value str)

Returns a Ruby string type.

Parameters:

• mrb —

  The current mruby state.

• str —

  Ruby string.

Returns:

• (mrb_value) —

  A Ruby string.

mrb_value mrb_check_string_type(mrb_state * mrb, mrb_value str)

mrb_value mrb_string_type(mrb_state * mrb, mrb_value str)

obsolete: use mrb_ensure_string_type() instead

mrb_value mrb_str_new_capa(mrb_state * mrb, size_t capa)

mrb_value mrb_str_buf_new(mrb_state * mrb, size_t capa)

mrb_int mrb_string_value_len(mrb_state * mrb, mrb_value str)

obslete: use RSTRING_LEN()

mrb_value mrb_str_dup(mrb_state * mrb, mrb_value str)

Duplicates a string object.

Parameters:

• mrb —

  The current mruby state.

• str —

  Ruby string.

Returns:

• (mrb_value) —

  Duplicated Ruby string.

mrb_value mrb_str_intern(mrb_state * mrb, mrb_value self)

Returns a symbol from a passed in Ruby string.

Parameters:

• mrb —

  The current mruby state.

• self —

  Ruby string.

Returns:

• (mrb_value) —

  A symbol.

mrb_value mrb_str_to_inum(mrb_state * mrb, mrb_value str, mrb_int base, mrb_bool badcheck)

mrb_value mrb_cstr_to_inum(mrb_state * mrb, const char * s, mrb_int base, mrb_bool badcheck)

double mrb_str_to_dbl(mrb_state * mrb, mrb_value str, mrb_bool badcheck)

double mrb_cstr_to_dbl(mrb_state * mrb, const char * s, mrb_bool badcheck)

mrb_value mrb_str_to_str(mrb_state * mrb, mrb_value str)

Returns a converted string type. For type checking, non converting mrb_to_str is recommended.

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.

Parameters:

• mrb —

  The current mruby state.

• str1 —

  Ruby string to compare.

• str2 —

  Ruby string to compare.

Returns:

• (mrb_value) —

  boolean value.

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.

Parameters:

• mrb —

  The current mruby state.

• str —

  Ruby string.

• ptr —

  A C string.

• len —

  length of C string.

Returns:

• (mrb_value) —

  A Ruby string.

See Also:

• mrb_str_cat_cstr

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.

Parameters:

• mrb —

  The current mruby state.

• str —

  Ruby string.

• ptr —

  A C string.

Returns:

• (mrb_value) —

  A Ruby string.

See Also:

• mrb_str_cat

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. Returns a value < 0 if Ruby str1 is less than Ruby str2. Returns a value > 0 if Ruby str2 is greater than Ruby str1.

char * mrb_str_to_cstr(mrb_state * mrb, mrb_value str)

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.
• Retured 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:

• mrb —

  The current mruby state.

• str —

  Ruby string. Must be an instance of String.

Returns:

• (char *) —

  A newly allocated C string.