Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Functions
sprintf.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Our own private printf(3). More...

#include "ruby/internal/attr/format.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
Include dependency graph for sprintf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

VALUE rb_f_sprintf (int argc, const VALUE *argv)
 Identical to rb_str_format(), except how the arguments are arranged. More...
 
VALUE rb_sprintf (const char *fmt,...)
 Ruby's extended sprintf(3). More...
 
VALUE rb_vsprintf (const char *fmt, va_list ap)
 Identical to rb_sprintf(), except it takes a va_list. More...
 
VALUE rb_str_catf (VALUE dst, const char *fmt,...)
 Identical to rb_sprintf(), except it renders the output to the specified object rather than creating a new one. More...
 
VALUE rb_str_vcatf (VALUE dst, const char *fmt, va_list ap)
 Identical to rb_str_catf(), except it takes a va_list. More...
 
VALUE rb_str_format (int argc, const VALUE *argv, VALUE fmt)
 Formats a string. More...
 

Detailed Description

Our own private printf(3).

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
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.

Definition in file sprintf.h.

Function Documentation

◆ rb_f_sprintf()

VALUE rb_f_sprintf ( int  argc,
const VALUE argv 
)

Identical to rb_str_format(), except how the arguments are arranged.

Parameters
[in]argcNumber of objects of argv.
[in]argvA format string, followed by its arguments.
Returns
A rendered new instance of rb_cString.

Definition at line 209 of file sprintf.c.

Referenced by rb_io_printf().

◆ rb_sprintf()

VALUE rb_sprintf ( const char *  fmt,
  ... 
)

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:

rb_sprintf("|%"PRIsVALUE"|", RUBY_Qtrue); // => "|true|"
rb_sprintf("%+"PRIsVALUE, rb_stdin); // => "#<IO:<STDIN>>"
VALUE rb_stdin
STDIN constant.
Definition: io.c:201
VALUE rb_sprintf(const char *fmt,...)
Ruby's extended sprintf(3).
Definition: sprintf.c:1217
@ RUBY_Qtrue
Parameters
[in]fmtA printf-like format specifier.
[in]...Variadic number of contents to format.
Returns
A rendered new instance of rb_cString.

Definition at line 1217 of file sprintf.c.

Referenced by rb_any_to_s(), rb_attr(), rb_error_frozen_object(), rb_f_global_variables(), rb_profile_frame_classpath(), and rb_profile_frame_full_label().

◆ rb_str_catf()

VALUE rb_str_catf ( VALUE  dst,
const char *  fmt,
  ... 
)

Identical to rb_sprintf(), except it renders the output to the specified object rather than creating a new one.

Parameters
[out]dstString to modify.
[in]fmtA printf-like format specifier.
[in]...Variadic number of contents to format.
Exceptions
rb_eTypeErrordst is not a String.
Returns
Passed dst.
Postcondition
dst has the rendered output appended to its end.

Definition at line 1240 of file sprintf.c.

Referenced by rb_str_format().

◆ rb_str_format()

VALUE rb_str_format ( int  argc,
const VALUE argv,
VALUE  fmt 
)

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
VALUE type(ANYARGS)
ANYARGS-ed function type.
Definition: cxxanyargs.hpp:56

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

Parameters
[in]argcNumber of objects in argv.
[in]argvFormat arguments.
[in]fmtA printf-like format specifier.
Exceptions
rb_eTypeErrorfmt is not a string.
rb_eArgErrorFailed to parse fmt.
Returns
A rendered new instance of rb_cString.
Note
Everything it takes must be Ruby objects.

Definition at line 215 of file sprintf.c.

Referenced by rb_f_sprintf().

◆ rb_str_vcatf()

VALUE rb_str_vcatf ( VALUE  dst,
const char *  fmt,
va_list  ap 
)

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.

Parameters
[out]dstString to modify.
[in]fmtA printf-like format specifier.
[in]apContents to format.
Exceptions
rb_eTypeErrordst is not a String.
Returns
Passed dst.
Postcondition
dst has the rendered output appended to its end.

Definition at line 1230 of file sprintf.c.

Referenced by rb_str_catf().

◆ rb_vsprintf()

VALUE rb_vsprintf ( const char *  fmt,
va_list  ap 
)

Identical to rb_sprintf(), except it takes a va_list.

Parameters
[in]fmtA printf-like format specifier.
[in]apContents to format.
Returns
A rendered new instance of rb_cString.

Definition at line 1211 of file sprintf.c.

Referenced by rb_frozen_error_raise(), rb_name_error(), rb_name_error_str(), rb_raise(), and rb_sprintf().