src/misc.c

   1 /*
   2 Copyright (C) 2001-2010, Parrot Foundation.
   3 $Id$
   4
   5 =head1 NAME
   6
   7 src/misc.c - Miscellaneous functions
   8
   9 =head1 DESCRIPTION
  10
  11 Miscellaneous functions, mainly the C<Parrot_sprintf> family.
  12
  13 Uses a generalized formatting algorithm (F<src/spf_render.c>) with
  14 a specialized vtable (F<src/spf_vtable.c>) to handle argument extraction.
  15
  16 =head2 Functions
  17
  18 The naming convention used is:
  19
  20 =over 4
  21
  22 =item C<Parrot_v?n?sprintf>
  23
  24 A (nearly) drop-in replacement for v?n?sprintf.
  25
  26 =item  C<Parrot_v?sprintf_c>
  27
  28 Takes a C-string format, returns a Parrot string.
  29
  30 =item  C<Parrot_v?sprintf_s>
  31
  32 Takes a Parrot string format, returns a Parrot string.
  33
  34 So the C<_> means "returns Parrot string" and the other letter indicates
  35 the type for the format.
  36
  37 =cut
  38
  39 */
  40
  41 #define IN_SPF_SYSTEM
  42
  43 #include "parrot/parrot.h"
  44
  45 /* HEADERIZER HFILE: include/parrot/misc.h */
  46
  47 /*
  48
  49 =item C<STRING * Parrot_vsprintf_s(PARROT_INTERP, STRING *pat, va_list args)>
  50
  51 Almost all the other sprintf variants in this file are implemented in
  52 terms of this function (see C<Parrot_psprintf()> for the exception). It
  53 in turn calls C<Parrot_sprintf_format()> (see F<src/spf_render.c>).
  54
  55 =cut
  56
  57 */
  58
  59 PARROT_EXPORT
  60 PARROT_WARN_UNUSED_RESULT
  61 PARROT_CANNOT_RETURN_NULL
  62 STRING *
  63 Parrot_vsprintf_s(PARROT_INTERP, ARGIN(STRING *pat), va_list args)
  64 {
  65     ASSERT_ARGS(Parrot_vsprintf_s)
  66     SPRINTF_OBJ obj = va_core;
  67     obj.data = PARROT_VA_TO_VAPTR(args);
  68
  69     return Parrot_sprintf_format(interp, pat, &obj);
  70 }
  71
  72 /*
  73
  74 =item C<STRING * Parrot_vsprintf_c(PARROT_INTERP, const char *pat, va_list
  75 args)>
  76
  77 C string version of C<Parrot_vsprintf_s()>.
  78
  79 =cut
  80
  81 */
  82
  83 PARROT_EXPORT
  84 PARROT_CANNOT_RETURN_NULL
  85 PARROT_WARN_UNUSED_RESULT
  86 STRING *
  87 Parrot_vsprintf_c(PARROT_INTERP, ARGIN(const char *pat), va_list args)
  88 {
  89     ASSERT_ARGS(Parrot_vsprintf_c)
  90     STRING * const realpat = string_make(interp, pat, strlen(pat),
  91                                   NULL, PObj_external_FLAG);
  92
  93     STRING * const ret = Parrot_vsprintf_s(interp, realpat, args);
  94
  95     return ret;
  96 }
  97
  98 /*
  99
 100 =item C<void Parrot_vsnprintf(PARROT_INTERP, char *targ, size_t len, const char
 101 *pat, va_list args)>
 102
 103 Similar to C<Parrot_vsprintf()> but with an option to specify the length
 104 (C<len>) of the returned C string.
 105
 106 =cut
 107
 108 */
 109
 110 PARROT_EXPORT
 111 void
 112 Parrot_vsnprintf(PARROT_INTERP, ARGOUT(char *targ),
 113                  size_t len, ARGIN(const char *pat), va_list args)
 114 {
 115     ASSERT_ARGS(Parrot_vsnprintf)
 116
 117     if (len == 0)
 118         return;
 119     --len;
 120     if (len) {
 121         const STRING * const ret = Parrot_vsprintf_c(interp, pat, args);
 122         /* string_transcode(interp, ret, NULL, NULL, &ret); */
 123
 124         char     * const str_ret = Parrot_str_to_cstring(interp, ret);
 125         const    size_t  str_len = strlen(str_ret);
 126         if (len > str_len) {
 127             len = str_len;
 128         }
 129
 130         if (len)
 131             memcpy(targ, str_ret, len);
 132         Parrot_str_free_cstring(str_ret);
 133     }
 134     targ[len] = 0;
 135 }
 136
 137 /*
 138
 139 =item C<STRING * Parrot_sprintf_s(PARROT_INTERP, STRING *pat, ...)>
 140
 141 Calls C<Parrot_vsprintf_s()> with the C<va_list> obtained from C<...>.
 142
 143 =cut
 144
 145 */
 146
 147 PARROT_EXPORT
 148 PARROT_WARN_UNUSED_RESULT
 149 PARROT_CANNOT_RETURN_NULL
 150 STRING *
 151 Parrot_sprintf_s(PARROT_INTERP, ARGIN(STRING *pat), ...)
 152 {
 153     ASSERT_ARGS(Parrot_sprintf_s)
 154     STRING *ret;
 155     va_list args;
 156
 157     va_start(args, pat);
 158
 159     ret = Parrot_vsprintf_s(interp, pat, args);
 160
 161     va_end(args);
 162
 163     return ret;
 164 }
 165
 166 /*
 167
 168 =item C<STRING * Parrot_sprintf_c(PARROT_INTERP, const char *pat, ...)>
 169
 170 C string version of C<Parrot_sprintf_s()>.
 171
 172 =cut
 173
 174 */
 175
 176 PARROT_EXPORT
 177 PARROT_WARN_UNUSED_RESULT
 178 PARROT_CANNOT_RETURN_NULL
 179 STRING *
 180 Parrot_sprintf_c(PARROT_INTERP, ARGIN(const char *pat), ...)
 181 {
 182     ASSERT_ARGS(Parrot_sprintf_c)
 183     STRING *ret;
 184     va_list args;
 185
 186     va_start(args, pat);
 187
 188     ret = Parrot_vsprintf_c(interp, pat, args);
 189
 190     va_end(args);
 191
 192     return ret;
 193 }
 194
 195 /*
 196
 197 =item C<void Parrot_snprintf(PARROT_INTERP, char *targ, size_t len, const char
 198 *pat, ...)>
 199
 200 Similar to C<Parrot_sprintf()> but with an option to specify the length
 201 (C<len>) of the returned C string.
 202
 203 =cut
 204
 205 */
 206
 207 PARROT_EXPORT
 208 void
 209 Parrot_snprintf(PARROT_INTERP, ARGOUT(char *targ), size_t len,
 210                 ARGIN(const char *pat), ...)
 211 {
 212     ASSERT_ARGS(Parrot_snprintf)
 213     va_list args;
 214
 215     va_start(args, pat);
 216
 217     Parrot_vsnprintf(interp, targ, len, pat, args);
 218
 219     va_end(args);
 220 }
 221
 222 /*
 223
 224 =item C<STRING * Parrot_psprintf(PARROT_INTERP, STRING *pat, PMC *ary)>
 225
 226 Calls C<Parrot_sprintf_format()> with the insertion arguments in an
 227 C<Array> PMC.
 228
 229 =cut
 230
 231 */
 232
 233 PARROT_EXPORT
 234 PARROT_WARN_UNUSED_RESULT
 235 PARROT_CANNOT_RETURN_NULL
 236 STRING *
 237 Parrot_psprintf(PARROT_INTERP, ARGIN(STRING *pat), ARGOUT(PMC *ary))
 238 {
 239     ASSERT_ARGS(Parrot_psprintf)
 240     SPRINTF_OBJ obj = pmc_core;
 241     obj.data = ary;
 242
 243     return Parrot_sprintf_format(interp, pat, &obj);
 244 }
 245
 246 /*
 247
 248 =item C<int Parrot_secret_snprintf(char *buffer, const size_t len, const char
 249 *format, ...)>
 250
 251 A simulation of C<snprintf> for systems that do not support it.
 252
 253 =cut
 254
 255 */
 256
 257
 258 PARROT_EXPORT
 259 PARROT_IGNORABLE_RESULT
 260 int
 261 Parrot_secret_snprintf(ARGOUT(char *buffer), SHIM(const size_t len),
 262         ARGIN(const char *format), ...)
 263 {
 264     ASSERT_ARGS(Parrot_secret_snprintf)
 265     int retval;
 266     va_list ap;
 267     va_start(ap, format);
 268     retval = vsprintf(buffer, format, ap);
 269     va_end(ap);
 270
 271     return retval;
 272 }
 273
 274
 275 /*
 276
 277 =back
 278
 279 =head1 SEE ALSO
 280
 281 F<src/misc.h>, F<src/spf_vtable.c>, F<src/spf_render.c>.
 282
 283 =head1 HISTORY
 284
 285 This was once a simple, vararg-based implementation that existed
 286 completely within this file.  When the file grew to be nearly 1000
 287 lines long, I split it into three. --BD
 288
 289 =cut
 290
 291 */
 292
 293
 294 /*
 295  * Local variables:
 296  *   c-file-style: "parrot"
 297  * End:
 298  * vim: expandtab shiftwidth=4:
 299  */