From 189ad473467ce07919b2dcd9c6f1ad3022308b73 Mon Sep 17 00:00:00 2001 From: "Ralph Desir(Mav7)" Date: Sat, 23 Jul 2016 02:47:32 -0400 Subject: yard docs for string.h --- include/mruby/string.h | 215 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/mruby/string.h b/include/mruby/string.h index b94c355fe..b66bc0dd1 100644 --- a/include/mruby/string.h +++ b/include/mruby/string.h @@ -88,35 +88,215 @@ mrb_int mrb_str_strlen(mrb_state*, struct RString*); void mrb_gc_free_str(mrb_state*, struct RString*); MRB_API void mrb_str_modify(mrb_state*, struct RString*); +/* + * Appends self to other. Returns self as a concatnated string. + * + * + * Example: + * + * !!!c + * 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_cstr(mrb, "abc"); + * str2 = mrb_str_new_cstr(mrb, "def"); + * + * // Concatnates str2 to str1. + * mrb_str_concat(mrb, str1, str2); + * + * // Prints new Concatnated Ruby string. + * mrb_p(mrb, str1); + * + * mrb_close(mrb); + * return 0; + * } + * + * + * Result: + * + * => "abcdef" + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] self String to concatenate. + * @param [mrb_value] other String to append to self. + * @return [mrb_value] Returns a new String appending other to self. + */ MRB_API void mrb_str_concat(mrb_state*, mrb_value, mrb_value); /* * Adds two strings together. + * + * + * Example: + * + * !!!c + * 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_cstr(mrb, "abc"); + * b = mrb_str_new_cstr(mrb, "def"); + * + * // Prints both C strings. + * mrb_p(mrb, a); + * mrb_p(mrb, b); + * + * // Concatnates both Ruby strings. + * c = mrb_str_plus(mrb, a, b); + * + * // Prints new Concatnated Ruby string. + * mrb_p(mrb, c); + * + * mrb_close(mrb); + * return 0; + * } + * + * + * Result: + * + * => "abc" # First string + * => "def" # Second string + * => "abcdef" # First & Second concatnated. + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] a First string to concatenate. + * @param [mrb_value] b Second string to concatenate. + * @return [mrb_value] Returns a new String containing a concatenated to b. */ MRB_API mrb_value mrb_str_plus(mrb_state*, mrb_value, mrb_value); /* * Converts pointer into a Ruby string. + * + * @param [mrb_state] mrb The current mruby state. + * @param [void*] p The pointer to convert to Ruby string. + * @return [mrb_value] Returns a new Ruby String. */ MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*); /* * Returns an object as a Ruby string. + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] obj An object to return as a Ruby string. + * @return [mrb_value] An object as a Ruby string. */ MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj); /* - * Resizes the string's length. + * Resizes the string's length. Returns the amount of characters + * in the specified by len. + * + * Example: + * + * !!!c + * 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_cstr(mrb, "Hello, world!"); + * // Returns 5 characters of + * mrb_str_resize(mrb, str, 5); + * mrb_p(mrb, str); + * + * mrb_close(mrb); + * return 0; + * } + * + * Result: + * + * => "Hello" + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str The Ruby string to resize. + * @param [mrb_value] len The length. + * @return [mrb_value] An object as a Ruby string. */ MRB_API mrb_value mrb_str_resize(mrb_state *mrb, mrb_value str, mrb_int len); /* * Returns a sub string. + * + * Example: + * + * !!!c + * 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_cstr(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" + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @param [mrb_int] beg The beginning point of the sub-string. + * @param [mrb_int] len The end point of the sub-string. + * @return [mrb_value] An object as a Ruby sub-string. */ MRB_API mrb_value mrb_str_substr(mrb_state *mrb, mrb_value str, mrb_int beg, mrb_int len); /* * Returns a Ruby string type. + * + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @return [mrb_value] A Ruby string. */ MRB_API mrb_value mrb_string_type(mrb_state *mrb, mrb_value str); @@ -125,15 +305,32 @@ MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa); MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr); MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str); +/* + * Returns the length of the Ruby string. + * + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @return [mrb_int] The length of the passed in Ruby string. + */ MRB_API mrb_int mrb_string_value_len(mrb_state *mrb, mrb_value str); /* * Duplicates a string object. + * + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @return [mrb_value] Duplicated Ruby string. */ MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str); /* - * Returns a symbol from a passed in string. + * Returns a symbol from a passed in Ruby string. + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] self Ruby string. + * @return [mrb_value] A symbol. */ MRB_API mrb_value mrb_str_intern(mrb_state *mrb, mrb_value self); @@ -147,12 +344,22 @@ MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str); /* * Returns true if the strings match and false if the strings don't match. + * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str1 Ruby string to compare. + * @param [mrb_value] str2 Ruby string to compare. + * @return [mrb_value] boolean value. */ MRB_API mrb_bool mrb_str_equal(mrb_state *mrb, mrb_value str1, mrb_value str2); /* * Returns a concated string comprised of a Ruby string and a C string. * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @param [const char *] ptr A C string. + * @param [size_t] len length of C string. + * @return [mrb_value] A Ruby string. * @see mrb_str_cat_cstr */ MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, size_t len); @@ -160,6 +367,10 @@ MRB_API mrb_value mrb_str_cat(mrb_state *mrb, mrb_value str, const char *ptr, si /* * Returns a concated string comprised of a Ruby string and a C string. * + * @param [mrb_state] mrb The current mruby state. + * @param [mrb_value] str Ruby string. + * @param [const char *] ptr A C string. + * @return [mrb_value] A Ruby string. * @see mrb_str_cat */ MRB_API mrb_value mrb_str_cat_cstr(mrb_state *mrb, mrb_value str, const char *ptr); -- cgit v1.2.3