|
|
|
libbytesize Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
#include <bs_size.h> typedef BSSize; enum BSErrorCode; BSError; enum BSBunit; enum BSDunit; enum BSRoundDir; BSUnit; #define BS_FLOAT_PREC_BITS BSSize bs_size_new (void); BSSize bs_size_new_from_bytes (uint64_t bytes,int sgn); BSSize bs_size_new_from_str (const char *size_str,BSError **error); BSSize bs_size_new_from_size (const BSSize size); void bs_size_free (BSSize size); void bs_clear_error (BSError **error); uint64_t bs_size_get_bytes (const BSSize size,int *sgn,BSError **error); int bs_size_sgn (const BSSize size); char * bs_size_get_bytes_str (const BSSize size); char * bs_size_convert_to (const BSSize size,BSUnit unit,BSError **error); char * bs_size_human_readable (const BSSize size,BSBunit min_unit,int max_places,bool xlate); BSSize bs_size_add (const BSSize size1,const BSSize size2); BSSize bs_size_grow (BSSize size1,const BSSize size2); BSSize bs_size_add_bytes (const BSSize size,uint64_t bytes); BSSize bs_size_grow_bytes (BSSize size,uint64_t bytes); BSSize bs_size_sub (const BSSize size1,const BSSize size2); BSSize bs_size_shrink (BSSize size1,const BSSize size2); BSSize bs_size_sub_bytes (const BSSize size,uint64_t bytes); BSSize bs_size_shrink_bytes (BSSize size,uint64_t bytes); BSSize bs_size_mul_int (const BSSize size,uint64_t times); BSSize bs_size_grow_mul_int (BSSize size,uint64_t times); BSSize bs_size_mul_float_str (const BSSize size,const char *float_str,BSError **error); BSSize bs_size_grow_mul_float_str (BSSize size,const char *float_str,BSError **error); uint64_t bs_size_div (const BSSize size1,const BSSize size2,int *sgn,BSError **error); BSSize bs_size_div_int (const BSSize size,uint64_t divisor,BSError **error); BSSize bs_size_shrink_div_int (BSSize size,uint64_t shrink_divisor,BSError **error); char * bs_size_true_div (const BSSize size1,const BSSize size2,BSError **error); char * bs_size_true_div_int (const BSSize size,uint64_t divisor,BSError **error); BSSize bs_size_mod (const BSSize size1,const BSSize size2,BSError **error); BSSize bs_size_round_to_nearest (const BSSize size,const BSSize round_to,BSRoundDir dir,BSError **error); int bs_size_cmp (const BSSize size1,const BSSize size2,bool abs); int bs_size_cmp_bytes (const BSSize size1,uint64_t bytes,bool abs);
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.
typedef struct _BSSize * BSSize;
The BSSize struct contains only private fields and should not be directly accessed.
typedef enum {
BS_ERROR_INVALID_SPEC,
BS_ERROR_OVER,
BS_ERROR_ZERO_DIV,
BS_ERROR_FAIL
} BSErrorCode;
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
typedef enum {
BS_BUNIT_B = 0, BS_BUNIT_KiB, BS_BUNIT_MiB, BS_BUNIT_GiB, BS_BUNIT_TiB,
BS_BUNIT_PiB, BS_BUNIT_EiB, BS_BUNIT_ZiB, BS_BUNIT_YiB, BS_BUNIT_UNDEF,
} BSBunit;
Binary units (multiples of 1024) of size in bytes.
typedef enum {
BS_DUNIT_B = 20, BS_DUNIT_KB, BS_DUNIT_MB, BS_DUNIT_GB, BS_DUNIT_TB,
BS_DUNIT_PB, BS_DUNIT_EB, BS_DUNIT_ZB, BS_DUNIT_YB, BS_DUNIT_UNDEF,
} BSDunit;
Decimal units (multiples of 1000) of size in bytes.
typedef enum {
BS_ROUND_DIR_UP = 0,
BS_ROUND_DIR_DOWN = 1,
BS_ROUND_DIR_HALF_UP = 2
} BSRoundDir;
Rounding direction for rounding operations.
#define BS_FLOAT_PREC_BITS 256
Precision (in bits) of floating-point numbers used internally.
BSSize bs_size_new (void);
Creates a new BSSize instance initialized to 0.
Returns : |
a new BSSize initialized to 0. |
BSSize bs_size_new_from_bytes (uint64_t bytes,int sgn);
Creates a new BSSize instance.
|
number of bytes |
|
sign of the size -- if being -1, the size is initialized to
-bytes, other values are ignored |
Returns : |
a new BSSize |
BSSize bs_size_new_from_str (const char *size_str,BSError **error);
Creates a new BSSize instance.
|
string representing the size as a number and an optional unit (e.g. "1 GiB") |
Returns : |
a new BSSize |
BSSize bs_size_new_from_size (const BSSize size);
Creates a new instance of BSSize.
|
the size to create a new instance from (a copy of) |
Returns : |
a new BSSize instance which is copy of size. [transfer full]
|
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.
|
sign of the size - -1, 0 or 1 for negative, zero or positive
size respectively. [allow-none][out]
|
Returns : |
the size in a number of bytes |
int bs_size_sgn (const BSSize size);
Get the sign of the size.
Returns : |
-1, 0 or 1 if size is negative, zero or positive, respectively |
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.
Returns : |
the string representing the size as a number of bytes. [transfer full]
|
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.
|
the unit to convert size to |
Returns : |
a string representing the floating-point number
that equals to size converted to unit. [transfer full]
|
char * bs_size_human_readable (const BSSize size,BSBunit min_unit,int max_places,bool xlate);
Get a human-readable representation of size.
|
the smallest unit the returned representation should use |
|
maximum number of decimal places the representation should use |
|
whether to try to translate the representation or not |
Returns : |
a string which is human-readable representation of
size according to the restrictions given by the
other parameters. [transfer full]
|
BSSize bs_size_add (const BSSize size1,const BSSize size2);
Add two sizes.
Returns : |
a new instance of BSSize which is a sum of size1 and size2. [transfer full]
|
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().
Returns : |
size1 modified by adding size2 to it. [transfer none]
|
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().
Returns : |
a new instance of BSSize which is a sum of size and bytes. [transfer full]
|
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().
Returns : |
size modified by adding bytes to it. [transfer none]
|
BSSize bs_size_sub (const BSSize size1,const BSSize size2);
Subtract size2 from size1.
Returns : |
a new instance of BSSize which is equals to size1 - size2. [transfer full]
|
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().
Returns : |
size1 modified by subtracting size2 from it. [transfer none]
|
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().
Returns : |
a new instance of BSSize which equals to size - bytes. [transfer full]
|
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().
Returns : |
size modified by subtracting bytes from it. [transfer none]
|
BSSize bs_size_mul_int (const BSSize size,uint64_t times);
Multiply size by times.
Returns : |
a new instance of BSSize which equals to size * times. [transfer full]
|
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().
Returns : |
size modified by growing it times times. [transfer none]
|
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.
Returns : |
a new BSSize instance which equals to
size * times_str. [transfer full]
|
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().
Returns : |
size modified by growing it float_str times. [transfer none]
|
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?".
|
sign of the result. [allow-none][out] |
Returns : |
integer number x so that x * size1 < size2 and (x+1) * size1 > size2
(IOW, size1 / size2 using integer division) |
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.
Returns : |
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.
Returns : |
size modified by division by divisor. [transfer none]
|
char * bs_size_true_div (const BSSize size1,const BSSize size2,BSError **error);
Divides size1 by size2.
Returns : |
a string representing the floating-point number
that equals to size1 / size2. [transfer full]
|
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.
Returns : |
a string representing the floating-point number
that equals to size / divisor. [transfer full]
|
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.**
Returns : |
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.
|
to a multiple of what to round size
|
|
BS_ROUND_DIR_UP to round up (to the nearest multiple of round_to
bigger than size) or BS_ROUND_DIR_DOWN to round down (to the
nearest multiple of round_to smaller than size) |
Returns : |
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.
|
whether to compare absolute values of size1 and size2 instead |
Returns : |
-1, 0, or 1 if size1 is smaller, equal to or bigger than
size2 respectively comparing absolute values if abs is true
|
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.
|
whether to compare absolute values of size and bytes instead. |
Returns : |
-1, 0, or 1 if size is smaller, equal to or bigger than
bytes respectively comparing absolute values if abs is true
|