| Top |
| BSSize | bs_size_new () |
| BSSize | bs_size_new_from_bytes () |
| BSSize | bs_size_new_from_str () |
| BSSize | bs_size_new_from_size () |
| void | bs_size_free () |
| void | bs_clear_error () |
| uint64_t | bs_size_get_bytes () |
| int | bs_size_sgn () |
| char * | bs_size_get_bytes_str () |
| char * | bs_size_convert_to () |
| char * | bs_size_human_readable () |
| BSSize | bs_size_add () |
| BSSize | bs_size_grow () |
| BSSize | bs_size_add_bytes () |
| BSSize | bs_size_grow_bytes () |
| BSSize | bs_size_sub () |
| BSSize | bs_size_shrink () |
| BSSize | bs_size_sub_bytes () |
| BSSize | bs_size_shrink_bytes () |
| BSSize | bs_size_mul_int () |
| BSSize | bs_size_grow_mul_int () |
| BSSize | bs_size_mul_float_str () |
| BSSize | bs_size_grow_mul_float_str () |
| uint64_t | bs_size_div () |
| BSSize | bs_size_div_int () |
| BSSize | bs_size_shrink_div_int () |
| char * | bs_size_true_div () |
| char * | bs_size_true_div_int () |
| BSSize | bs_size_mod () |
| BSSize | bs_size_round_to_nearest () |
| int | bs_size_cmp () |
| int | bs_size_cmp_bytes () |
| typedef | BSSize |
| enum | BSErrorCode |
| BSError | |
| enum | BSBunit |
| enum | BSDunit |
| enum | BSRoundDir |
| BSUnit | |
| #define | BS_FLOAT_PREC_BITS |
BSSize is a type that facilitates work with sizes in bytes by providing
functions/methods that are required for parsing users input when entering
size, showing size in nice human-readable format, storing sizes bigger than
UINT64_MAX and doing calculations with sizes without loss of
precision/information. The class is able to hold negative sizes and do
operations on/with them, but some of the (division and multiplication)
operations simply ignore the signs of the operands (check the documentation).
The reason why some functions take or return a float as a string instead of a float directly is because a string "0.3" can be translated into 0.3 with appropriate precision while 0.3 as float is probably something like 0.294343... with unknown precision.
BSSize
bs_size_new (void);
Creates a new BSSize instance initialized to 0.
[constructor]
BSSize bs_size_new_from_bytes (uint64_t bytes,int sgn);
Creates a new BSSize instance.
[constructor]
BSSize bs_size_new_from_str (const char *size_str,BSError **error);
Creates a new BSSize instance.
[constructor]
BSSize
bs_size_new_from_size (const BSSize size);
Creates a new instance of BSSize.
[constructor]
void
bs_clear_error (BSError **error);
Clears error
and frees the allocated resources.
uint64_t bs_size_get_bytes (const BSSize size,int *sgn,BSError **error);
Get the number of bytes of the size
.
char *
bs_size_get_bytes_str (const BSSize size);
Get the number of bytes in size
as a string. This way, the caller doesn't
have to care about the limitations of some particular integer type.
char * bs_size_convert_to (const BSSize size,BSUnit unit,BSError **error);
Get the size
converted to unit
as a string representing a floating-point
number.
char * bs_size_human_readable (const BSSize size,BSBunit min_unit,int max_places,bool xlate);
Get a human-readable representation of size
.
BSSize bs_size_grow (BSSize size1,const BSSize size2);
Grows size1
by size2
. IOW, adds size2
to size1
in-place (modifying
size1
).
Basically an in-place variant of bs_size_add().
BSSize bs_size_add_bytes (const BSSize size,uint64_t bytes);
Add bytes
to the size
. To add a negative number of bytes use
bs_size_sub_bytes().
BSSize bs_size_grow_bytes (BSSize size,uint64_t bytes);
Grows size
by bytes
. IOW, adds bytes
to size
in-place (modifying size
).
Basically an in-place variant of bs_size_add_bytes().
BSSize bs_size_sub (const BSSize size1,const BSSize size2);
Subtract size2
from size1
.
BSSize bs_size_shrink (BSSize size1,const BSSize size2);
Shrinks size1
by size2
. IOW, subtracts size2
from size1
in-place
(modifying size1
).
Basically an in-place variant of bs_size_sub().
BSSize bs_size_sub_bytes (const BSSize size,uint64_t bytes);
Subtract bytes
from the size
. To subtract a negative number of bytes use
bs_size_add_bytes().
BSSize bs_size_shrink_bytes (BSSize size,uint64_t bytes);
Shrinks size
by bytes
. IOW, subtracts bytes
from size
in-place
(modifying size
). To shrink by a negative number of bytes use
bs_size_grow_bytes().
Basically an in-place variant of bs_size_sub_bytes().
BSSize bs_size_mul_int (const BSSize size,uint64_t times);
Multiply size
by times
.
BSSize bs_size_grow_mul_int (BSSize size,uint64_t times);
Grow size
times
times. IOW, multiply size
by times
in-place.
Basically an in-place variant of bs_size_mul_int().
BSSize bs_size_mul_float_str (const BSSize size,const char *float_str,BSError **error);
Multiply size
by the floating-point number float_str
represents.
BSSize bs_size_grow_mul_float_str (BSSize size,const char *float_str,BSError **error);
Grow size
by the floating-point number float_str
represents times. IOW,
multiply size
by float_str
in-place.
Basically an in-place variant of bs_size_grow_mul_float_str().
uint64_t bs_size_div (const BSSize size1,const BSSize size2,int *sgn,BSError **error);
Divide size1
by size2
. Gives the answer to the question "How many times
does size2
fit in size1
?".
BSSize bs_size_div_int (const BSSize size,uint64_t divisor,BSError **error);
Divide size
by divisor
. Gives the answer to the question "What is the size
of each chunk if size
is split into a divisor
number of pieces?"
Note: Due to the limitations of the current implementation the maximum value
divisor
is ULONG_MAX (which can differ from UINT64_MAX). An error
(BS_ERROR_OVER) is returned if overflow happens.
a BSSize instance x so that x * divisor
= size
,
rounded to a number of bytes.
[transfer full]
BSSize bs_size_shrink_div_int (BSSize size,uint64_t shrink_divisor,BSError **error);
Shrink size
by dividing by divisor
. IOW, divide size
by divisor
in-place.
Basically an in-place variant of bs_size_div_int().
Note: Due to the limitations of the current implementation the maximum value
divisor
is ULONG_MAX (which can differ from UINT64_MAX). An error
(BS_ERROR_OVER) is returned if overflow happens.
char * bs_size_true_div (const BSSize size1,const BSSize size2,BSError **error);
Divides size1
by size2
.
char * bs_size_true_div_int (const BSSize size,uint64_t divisor,BSError **error);
Divides size
by divisor
.
Note: Due to the limitations of the current implementation the maximum value
divisor
is ULONG_MAX (which can differ from UINT64_MAX). An error
(BS_ERROR_OVER) is returned if overflow happens.
BSSize bs_size_mod (const BSSize size1,const BSSize size2,BSError **error);
Gives size1
modulo size2
(i.e. the remainder of integer division size1
/
size2
). Gives the answer to the question "If I split size1
into chunks of
size size2
, what will be the remainder?"
**This function ignores the signs of the sizes.**
a BSSize instance that is a remainder of
size1
/ size2
using integer division.
[transfer full]
BSSize bs_size_round_to_nearest (const BSSize size,const BSSize round_to,BSRoundDir dir,BSError **error);
Round size
to the nearest multiple of round_to
according to the direction
given by dir
.
round_to |
to a multiple of what to round |
|
dir |
|
a new instance of BSSize that is size
rounded to
a multiple of round_to
according to dir
.
[transfer full]
int bs_size_cmp (const BSSize size1,const BSSize size2,bool abs);
Compare size1
and size2
. This function behaves like the standard *cmp*()
functions.
int bs_size_cmp_bytes (const BSSize size1,uint64_t bytes,bool abs);
Compare size
and bytes
, i.e. the number of bytes size
has with
bytes
. This function behaves like the standard *cmp*() functions.
BS_ERROR_INVALID_SPEC
: invalid size or unit spec provided
BS_ERROR_OVER
: a value is over the limits imposed by a type
BS_ERROR_ZERO_DIV
: an attempt to do division by zero
Error codes that identify various errors that can occur while working with BSSize instances.
typedef struct {
BSErrorCode code;
char *msg;
} BSError;
code
: error code
msg
: optional error message