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	RSTR_POOL_P(s) ((s)->flags & MRB_STR_POOL)

#define	RSTR_SET_POOL_FLAG(s) ((s)->flags \|= MRB_STR_POOL)

#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_POOL 16 /* status flags from here */

#define	MRB_STR_ASCII 32

#define	MRB_STR_EMBED_LEN_SHIFT 6

#define	MRB_STR_EMBED_LEN_BITSIZE 5

#define	MRB_STR_EMBED_LEN_MASK (((1 << MRB_STR_EMBED_LEN_BITSIZE) - 1) << MRB_STR_EMBED_LEN_SHIFT)

#define	MRB_STR_TYPE_MASK (MRB_STR_POOL - 1)

#define	mrb_str_index_lit(mrb, str, lit, off) mrb_str_index(mrb, str, lit, mrb_strlen_lit(lit), off);

#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
mrb_int	mrb_str_strlen (mrb_state , struct RString )

void	mrb_gc_free_str (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_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, mrb_value self, mrb_value other)
	Appends self to other. More...

mrb_value	mrb_str_plus (mrb_state *mrb, mrb_value a, mrb_value b)
	Adds two strings together. More...

mrb_value	mrb_ptr_to_str (mrb_state mrb, void p)
	Converts pointer into a Ruby string. More...

mrb_value	mrb_obj_as_string (mrb_state *mrb, mrb_value obj)
	Returns an object as a Ruby string. More...

mrb_value	mrb_str_resize (mrb_state *mrb, mrb_value str, mrb_int len)
	Resizes the string's length. More...

mrb_value	mrb_str_substr (mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len)
	Returns a sub string. More...

mrb_value	mrb_ensure_string_type (mrb_state *mrb, mrb_value str)
	Returns a Ruby string type. More...

mrb_value	mrb_check_string_type (mrb_state *mrb, mrb_value str)

mrb_value	mrb_string_type (mrb_state *mrb, mrb_value str)

mrb_value	mrb_str_new_capa (mrb_state *mrb, size_t capa)

mrb_value	mrb_str_buf_new (mrb_state *mrb, size_t capa)

const char *	mrb_string_cstr (mrb_state *mrb, mrb_value str)

const char *	mrb_string_value_cstr (mrb_state mrb, mrb_value str)

const char *	mrb_string_value_ptr (mrb_state *mrb, mrb_value str)

mrb_int	mrb_string_value_len (mrb_state *mrb, mrb_value str)

mrb_value	mrb_str_dup (mrb_state *mrb, mrb_value str)
	Duplicates a string object. More...

mrb_value	mrb_str_intern (mrb_state *mrb, mrb_value self)
	Returns a symbol from a passed in Ruby string. More...

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

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

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

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

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

char *	mrb_str_to_cstr (mrb_state *mrb, mrb_value str)
	Returns a newly allocated C string from a Ruby string. More...

mrb_value	mrb_str_pool (mrb_state *mrb, mrb_value str)

uint32_t	mrb_str_hash (mrb_state *mrb, mrb_value str)

mrb_value	mrb_str_dump (mrb_state *mrb, mrb_value str)

mrb_value	mrb_str_inspect (mrb_state *mrb, mrb_value str)
	Returns a printable version of str, surrounded by quote marks, with special characters escaped.

mrb_bool	mrb_str_beg_len (mrb_int str_len, mrb_int begp, mrb_int lenp)

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

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_int)(n);\
  }\
} while (0)

Function Documentation

◆ mrb_ensure_string_type()

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_obj_as_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_ptr_to_str()

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

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_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_str_cmp()

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.

◆ mrb_str_concat()

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

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

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

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

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

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

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

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.

◆ mrb_str_to_str()

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.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RSTR_SET_EMBED_LEN

◆ RSTR_SET_LEN

Function Documentation

◆ mrb_ensure_string_type()

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

◆ mrb_str_to_str()