diff options
Diffstat (limited to 'include/ruby/internal/intern/sprintf.h')
| -rw-r--r-- | include/ruby/internal/intern/sprintf.h | 159 |
1 files changed, 0 insertions, 159 deletions
diff --git a/include/ruby/internal/intern/sprintf.h b/include/ruby/internal/intern/sprintf.h deleted file mode 100644 index aedc0f9ab1..0000000000 --- a/include/ruby/internal/intern/sprintf.h +++ /dev/null @@ -1,159 +0,0 @@ -#ifndef RBIMPL_INTERN_SPRINTF_H /*-*-C++-*-vi:se ft=cpp:*/ -#define RBIMPL_INTERN_SPRINTF_H -/** - * @file - * @author Ruby developers <ruby-core@ruby-lang.org> - * @copyright This file is a part of the programming language Ruby. - * Permission is hereby granted, to either redistribute and/or - * modify this file, provided that the conditions mentioned in the - * file COPYING are met. Consult the file for details. - * @warning Symbols prefixed with either `RBIMPL` or `rbimpl` are - * implementation details. Don't take them as canon. They could - * rapidly appear then vanish. The name (path) of this header file - * is also an implementation detail. Do not expect it to persist - * at the place it is now. Developers are free to move it anywhere - * anytime at will. - * @note To ruby-core: remember that this header can be possibly - * recursively included from extension libraries written in C++. - * Do not expect for instance `__VA_ARGS__` is always available. - * We assume C99 for ruby itself but we don't assume languages of - * extension libraries. They could be written in C++98. - * @brief Our own private `printf(3)`. - */ -#include "ruby/internal/attr/format.h" -#include "ruby/internal/attr/nonnull.h" -#include "ruby/internal/dllexport.h" -#include "ruby/internal/value.h" - -RBIMPL_SYMBOL_EXPORT_BEGIN() - -/* sprintf.c */ - -/** - * Identical to rb_str_format(), except how the arguments are arranged. - * - * @param[in] argc Number of objects of `argv`. - * @param[in] argv A format string, followed by its arguments. - * @return A rendered new instance of ::rb_cString. - * - * @internal - * - * You can safely pass NULL to `argv`. Doesn't make any sense though. - */ -VALUE rb_f_sprintf(int argc, const VALUE *argv); - -RBIMPL_ATTR_NONNULL((1)) -RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) -/** - * Ruby's extended `sprintf(3)`. We ended up reinventing the entire `printf` - * business because we don't want to depend on locales. OS-provided `printf` - * routines might or might not, which caused instabilities of the result - * strings. - * - * The format sequence is a mixture of format specifiers and other verbatim - * contents. Each format specifier starts with a `%`, and has the following - * structure: - * - * ``` - * %[flags][width][.precision][length]conversion - * ``` - * - * This function supports flags of ` `, `#`, `+`, `-`, `0`, width of - * non-negative decimal integer and `*`, precision of non-negative decimal - * integers and `*`, length of `L`, `h`, `t`, `z`, `l`, `ll`, `q`, conversions - * of `A`, `D`, `E`, `G`, `O`, `U`, `X`, `a`, `c`, `d`, `e`, `f`, `g`, `i`, - * `n`, `o`, `p`, `s`, `u`, `x`, and `%`. In case of `_WIN32` it also supports - * `I`. And additionally, it supports magical `PRIsVALUE` macro that can - * stringise arbitrary Ruby objects: - * - * ```CXX - * rb_sprintf("|%"PRIsVALUE"|", RUBY_Qtrue); // => "|true|" - * rb_sprintf("%+"PRIsVALUE, rb_stdin); // => "#<IO:<STDIN>>" - * ``` - * - * @param[in] fmt A `printf`-like format specifier. - * @param[in] ... Variadic number of contents to format. - * @return A rendered new instance of ::rb_cString. - * - * @internal - * - * :FIXME: We can improve this document. - */ -VALUE rb_sprintf(const char *fmt, ...); - -RBIMPL_ATTR_NONNULL((1)) -RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 0) -/** - * Identical to rb_sprintf(), except it takes a `va_list`. - * - * @param[in] fmt A `printf`-like format specifier. - * @param[in] ap Contents to format. - * @return A rendered new instance of ::rb_cString. - */ -VALUE rb_vsprintf(const char *fmt, va_list ap); - -RBIMPL_ATTR_NONNULL((2)) -RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) -/** - * Identical to rb_sprintf(), except it renders the output to the specified - * object rather than creating a new one. - * - * @param[out] dst String to modify. - * @param[in] fmt A `printf`-like format specifier. - * @param[in] ... Variadic number of contents to format. - * @exception rb_eTypeError `dst` is not a String. - * @return Passed `dst`. - * @post `dst` has the rendered output appended to its end. - */ -VALUE rb_str_catf(VALUE dst, const char *fmt, ...); - -RBIMPL_ATTR_NONNULL((2)) -RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 0) -/** - * Identical to rb_str_catf(), except it takes a `va_list`. It can also be - * seen as a routine identical to rb_vsprintf(), except it renders the output - * to the specified object rather than creating a new one. - * - * @param[out] dst String to modify. - * @param[in] fmt A `printf`-like format specifier. - * @param[in] ap Contents to format. - * @exception rb_eTypeError `dst` is not a String. - * @return Passed `dst`. - * @post `dst` has the rendered output appended to its end. - */ -VALUE rb_str_vcatf(VALUE dst, const char *fmt, va_list ap); - -/** - * Formats a string. - * - * Returns the string resulting from applying `fmt` to `argv`. The format - * sequence is a mixture of format specifiers and other verbatim contents. - * Each format specifier starts with a `%`, and has the following structure: - * - * ``` - * %[flags][width][.precision]type - * ``` - * - * ... which is different from that of rb_sprintf(). Because ruby has no - * `short` or `long`, there is no way to specify a "length" of an argument. - * - * This function supports flags of ` `, `#`, `+`, `-`, `<>`, `{}`, with of - * non-negative decimal integer and `$`, `*`, precision of non-negative decimal - * integer and `$`, `*`, type of `A`, `B`, `E`, `G`, `X`, `a`, `b`, `c`, `d`, - * `e`, `f`, `g`, `i`, `o`, `p`, `s`, `u`, `x`, `%`. This list is also - * (largely the same but) not identical to that of rb_sprintf(). - * - * @param[in] argc Number of objects in `argv`. - * @param[in] argv Format arguments. - * @param[in] fmt A printf-like format specifier. - * @exception rb_eTypeError `fmt` is not a string. - * @exception rb_eArgError Failed to parse `fmt`. - * @return A rendered new instance of ::rb_cString. - * @note Everything it takes must be Ruby objects. - * - */ -VALUE rb_str_format(int argc, const VALUE *argv, VALUE fmt); - -RBIMPL_SYMBOL_EXPORT_END() - -#endif /* RBIMPL_INTERN_SPRINTF_H */ |