String class

#include "common.h"

Include dependency graph for string.h:

This graph shows which files directly or indirectly include 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) (RSTR_UNSET_TYPE_FLAG(s), (s)->flags \|= MRB_STR_##type)

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

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

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

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

#define	RSTR_SET_EMBED_LEN(s, n)

#define	RSTR_SET_LEN(s, n)

#define	RSTR_EMBED_PTR(s) (((struct RStringEmbed*)(s))->ary)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#define	RSTR_ASCII_P(s) (void)0

#define	RSTR_SET_ASCII_FLAG(s) (void)0

#define	RSTR_UNSET_ASCII_FLAG(s) (void)0

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

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

#define	mrb_str_ptr(s) ((struct RString*)(mrb_ptr(s)))
	Returns a pointer from a Ruby string.

#define	RSTRING(s) mrb_str_ptr(s)

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

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

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

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

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

#define	RSTRING_CSTR(mrb, s) mrb_string_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) mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off);

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

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

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

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

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

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

#define	mrb_str_cat2(mrb, str, ptr) mrb_str_cat_cstr(mrb, str, ptr)

#define	mrb_str_buf_cat(mrb, str, ptr, len) mrb_str_cat(mrb, str, ptr, len)

#define	mrb_str_buf_append(mrb, str, str2) mrb_str_cat_str(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

◆ 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_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)

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

mrb	The current mruby state.
obj	An 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

mrb	The current mruby state.
p	The 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

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_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

mrb	The current mruby state.
str	Ruby string.
ptr	A 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

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_str_dup()

mrb_value mrb_str_dup	(	mrb_state *	mrb,
		mrb_value	str )

extern

Duplicates a string object.

Parameters

mrb	The current mruby state.
str	Ruby 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

mrb	The current mruby state.
str1	Ruby string to compare.
str2	Ruby 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

mrb	The current mruby state.
self	Ruby 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

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_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

mrb	The current mruby state.
str	The Ruby string to resize.
len	The 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

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_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

mrb	The current mruby state.
str	Ruby string. Must be an instance of String.

Returns: [char *] A newly allocated C string.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RSTR_SET_EMBED_LEN

◆ RSTR_SET_LEN

Function Documentation

◆ mrb_obj_as_string()

◆ mrb_ptr_to_str()

◆ mrb_str_cat()

◆ mrb_str_cat_cstr()

◆ mrb_str_cmp()

◆ mrb_str_concat()

◆ mrb_str_dup()

◆ mrb_str_equal()

◆ mrb_str_intern()

◆ mrb_str_plus()

◆ mrb_str_resize()

◆ mrb_str_substr()

◆ mrb_str_to_cstr()