src/misc.c

   1 /*
   2 Copyright (C) 2001-2008, 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 STRING *
  86 Parrot_vsprintf_c(PARROT_INTERP, ARGIN(const char *pat), va_list args)
  87 {
  88     ASSERT_ARGS(Parrot_vsprintf_c)
  89     STRING * const realpat = string_make(interp, pat, strlen(pat),
  90                                   NULL, PObj_external_FLAG);
  91
  92     STRING * const ret = Parrot_vsprintf_s(interp, realpat, args);
  93
  94     return ret;
  95 }
  96
  97 /*
  98
  99 =item C<void Parrot_vsnprintf(PARROT_INTERP, char *targ, size_t len, const char
 100 *pat, va_list args)>
 101
 102 Similar to C<Parrot_vsprintf()> but with an option to specify the length
 103 (C<len>) of the returned C string.
 104
 105 =cut
 106
 107 */
 108
 109 PARROT_EXPORT
 110 void
 111 Parrot_vsnprintf(PARROT_INTERP, ARGOUT(char *targ),
 112                  size_t len, ARGIN(const char *pat), va_list args)
 113 {
 114     ASSERT_ARGS(Parrot_vsnprintf)
 115     if (len == 0)
 116         return;
 117     len--;
 118     if (len) {
 119         const STRING * const ret = Parrot_vsprintf_c(interp, pat, args);
 120         /* string_transcode(interp, ret, NULL, NULL, &ret); */
 121
 122         if (len > ret->bufused) {
 123             len = ret->bufused;
 124         }
 125
 126         if (len)
 127             memcpy(targ, ret->strstart, len);
 128     }
 129     targ[len] = 0;
 130 }
 131
 132 /*
 133
 134 =item C<STRING * Parrot_sprintf_s(PARROT_INTERP, STRING *pat, ...)>
 135
 136 Calls C<Parrot_vsprintf_s()> with the C<va_list> obtained from C<...>.
 137
 138 =cut
 139
 140 */
 141
 142 PARROT_EXPORT
 143 PARROT_WARN_UNUSED_RESULT
 144 PARROT_CANNOT_RETURN_NULL
 145 STRING *
 146 Parrot_sprintf_s(PARROT_INTERP, ARGIN(STRING *pat), ...)
 147 {
 148     ASSERT_ARGS(Parrot_sprintf_s)
 149     STRING *ret;
 150     va_list args;
 151
 152     va_start(args, pat);
 153
 154     ret = Parrot_vsprintf_s(interp, pat, args);
 155
 156     va_end(args);
 157
 158     return ret;
 159 }
 160
 161 /*
 162
 163 =item C<STRING * Parrot_sprintf_c(PARROT_INTERP, const char *pat, ...)>
 164
 165 C string version of C<Parrot_sprintf_s()>.
 166
 167 =cut
 168
 169 */
 170
 171 PARROT_EXPORT
 172 PARROT_WARN_UNUSED_RESULT
 173 PARROT_CANNOT_RETURN_NULL
 174 STRING *
 175 Parrot_sprintf_c(PARROT_INTERP, ARGIN(const char *pat), ...)
 176 {
 177     ASSERT_ARGS(Parrot_sprintf_c)
 178     STRING *ret;
 179     va_list args;
 180
 181     va_start(args, pat);
 182
 183     ret = Parrot_vsprintf_c(interp, pat, args);
 184
 185     va_end(args);
 186
 187     return ret;
 188 }
 189
 190 /*
 191
 192 =item C<void Parrot_snprintf(PARROT_INTERP, char *targ, size_t len, const char
 193 *pat, ...)>
 194
 195 Similar to C<Parrot_sprintf()> but with an option to specify the length
 196 (C<len>) of the returned C string.
 197
 198 =cut
 199
 200 */
 201
 202 PARROT_EXPORT
 203 void
 204 Parrot_snprintf(PARROT_INTERP, ARGOUT(char *targ), size_t len,
 205                 ARGIN(const char *pat), ...)
 206 {
 207     ASSERT_ARGS(Parrot_snprintf)
 208     va_list args;
 209
 210     va_start(args, pat);
 211
 212     Parrot_vsnprintf(interp, targ, len, pat, args);
 213
 214     va_end(args);
 215 }
 216
 217 /*
 218
 219 =item C<STRING * Parrot_psprintf(PARROT_INTERP, STRING *pat, PMC *ary)>
 220
 221 Calls C<Parrot_sprintf_format()> with the insertion arguments in an
 222 C<Array> PMC.
 223
 224 =cut
 225
 226 */
 227
 228 PARROT_EXPORT
 229 PARROT_WARN_UNUSED_RESULT
 230 PARROT_CANNOT_RETURN_NULL
 231 STRING *
 232 Parrot_psprintf(PARROT_INTERP, ARGIN(STRING *pat), ARGOUT(PMC *ary))
 233 {
 234     ASSERT_ARGS(Parrot_psprintf)
 235     SPRINTF_OBJ obj = pmc_core;
 236     obj.data = ary;
 237
 238     return Parrot_sprintf_format(interp, pat, &obj);
 239 }
 240
 241 /*
 242
 243 =item C<int Parrot_secret_snprintf(char *buffer, const size_t len, const char
 244 *format, ...)>
 245
 246 A simulation of C<snprintf> for systems that do not support it.
 247
 248 =cut
 249
 250 */
 251
 252
 253 PARROT_EXPORT
 254 int
 255 Parrot_secret_snprintf(ARGOUT(char *buffer), SHIM(const size_t len),
 256         ARGIN(const char *format), ...)
 257 {
 258     ASSERT_ARGS(Parrot_secret_snprintf)
 259     int retval;
 260     va_list ap;
 261     va_start(ap, format);
 262     retval = vsprintf(buffer, format, ap);
 263     va_end(ap);
 264
 265     return retval;
 266 }
 267
 268
 269 /*
 270
 271 =back
 272
 273 =head1 SEE ALSO
 274
 275 F<src/misc.h>, F<src/spf_vtable.c>, F<src/spf_render.c>.
 276
 277 =head1 HISTORY
 278
 279 This was once a simple, vararg-based implementation that existed
 280 completely within this file.  When the file grew to be nearly 1000
 281 lines long, I split it into three. --BD
 282
 283 =cut
 284
 285 */
 286
 287
 288 /*
 289  * Local variables:
 290  *   c-file-style: "parrot"
 291  * End:
 292  * vim: expandtab shiftwidth=4:
 293  */