[FFmpeg-devel] [PATCH] Improve documentation for libavutil/base64.h

[Stefano Sabatini]

On date Saturday 2009-02-07 03:11:45 +0100, Michael Niedermayer encoded:
> On Sat, Feb 07, 2009 at 01:27:15AM +0100, Stefano Sabatini wrote:
> > On date Wednesday 2009-01-28 01:03:29 +0100, Stefano Sabatini encoded:
> > [...]
> > > Index: libavutil/base64.h
> > > ===================================================================
> > > --- libavutil/base64.h	(revision 16838)
> > > +++ libavutil/base64.h	(working copy)
> > > @@ -25,16 +25,29 @@
> > >  #include <stdint.h>
> > >  
> > >  /**
> > > - * decodes base64
> > > - * param order as strncpy()
> > > + * Decodes the base64-encoded string in \p src and puts the decoded
> > > + * data in \p dst.
> > > + *
> > > + * @param dst_size size in bytes of the \p dst buffer, it should be at
> > > + * least 3/4 of the length of \p src
> > > + * @return the number of bytes written, or a negative value in case of
> > > + * error
> > >   */
> > > -int av_base64_decode(uint8_t * out, const char *in, int out_length);
> > > +int av_base64_decode(uint8_t *dst, const char *src, int dst_size);
> > >  
> > >  /**
> > > - * encodes base64
> > > - * @param src data, not a string
> > > - * @param buf output string
> > > + * Encodes in base64 the data in \p src and puts the resulting string
> > > + * in \p dst.
> > > + *
> > > + * @param dst_size size in bytes of the \p dst string
> > > + * @warning While the encoded string size is 4/3 * N + 1, N being the
> > > + * smaller multiple of 3 greater than or equal to \p src_size, you may
> > > + * need to overallocate by few bytes the \p dst buffer, or the
> > > + * function may fail.
> > > + * @param src_size size in bytes of the \p src buffer
> > > + * @return the string containing the encoded data, or NULL in case of
> > > + * error
> > >   */
> > > -char *av_base64_encode(char * buf, int buf_len, const uint8_t * src, int len);
> > > +char *av_base64_encode(char *dst, int dst_size, const uint8_t *src, int src_size);
> > >  
> > >  #endif /* AVUTIL_BASE64_H */
> > 
> > Ping?
> 
> rejected :)
> "While the encoded string size is 4/3 * N + 1, N being the
> smaller multiple of 3 greater than or equal to \p src_size"
> 
> that be confusing
> i dont remember exactly but possibly i suggested a clean variant already
> somewhere in the thread but then maybe not ...

Well it was my fault to erroneosly infer that that variant was
correct, it overallocates two bytes in the worst case.

Your variant: f(N) = floor(4 * (N+2) / 3)

N' = { smaller multiple of 3 greater than or equal to N } = N + R, R < 3.

We can have (I'm using the property:
floor(X + Y) = floor(X) + floor(Y) if X is integer):

1) N = N'
f(N) = floor ((4 * (N' + 2))/ 3)
     = floor (4*N'/3) + floor (4 * 2/3) = 4*N'/3 + 2

2) N = N'-1
f(N) = floor ((4 * (N'-1 + 2))/ 3) =
     = floor ((4 * (N'+1))/ 3) =
     = floor (4*N'/3) + floor (4 * 1/3) = 4*N'/3 + 1

2) N = N'-2
f(N) = floor ((4 * (N'-2 + 2))/ 3) =
     = floor ((4 * (N'))/ 3) =
     = floor (4*N'/3) + floor (4 * 0/3) = 4*N'/3 + 0

The more compact way to express "the smaller multiple of 3 greater
than or equal to \p src_size" I can find using C semantics is: 
((src_size + 2)/3) * 3

but I don't think it is much more clear, suggestion are very welcome
otherwise I'd say to commit this version *or* if we don't want to
waste too much time on this to strip it from documentation and leave
it to the guess of the user.

I also propose to reduce the overallocation required for the dst
buffer, as in the attached patch.

Regards.
-- 
FFmpeg = Frenzy and Fundamental Multimedia Philosophical Extroverse Guru
-------------- next part --------------
A non-text attachment was scrubbed...
Name: reduce-base64-overalloc.patch
Type: text/x-diff
Size: 408 bytes
Desc: not available
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20090207/de62280f/attachment.patch>