BSSize

BSSize — a class facilitating work with sizes in bytes

Functions

BSSize * bs_size_new ()
BSSize * bs_size_new_from_bytes ()
BSSize * bs_size_new_from_str ()
BSSize * bs_size_new_from_size ()
guint64 bs_size_get_bytes ()
gint bs_size_sgn ()
gchar * bs_size_get_bytes_str ()
gchar * bs_size_convert_to ()
gchar * 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 ()
guint64 bs_size_div ()
BSSize * bs_size_div_int ()
BSSize * bs_size_shrink_div_int ()
gchar * bs_size_true_div ()
gchar * bs_size_true_div_int ()
BSSize * bs_size_mod ()
BSSize * bs_size_round_to_nearest ()
gint bs_size_cmp ()
gint bs_size_cmp_bytes ()

Types and Values

Includes

#include <bs_size.h>

Description

A BSSize is class 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 G_MAXUINT64 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.

Functions

bs_size_new ()

BSSize *
bs_size_new (void);

Creates a new BSSize instance initialized to 0.

[constructor]

Returns

a new BSSize initialized to 0.


bs_size_new_from_bytes ()

BSSize *
bs_size_new_from_bytes (guint64 bytes,
                        gint sgn);

Creates a new BSSize instance.

[constructor]

Parameters

bytes

number of bytes

 

sgn

sign of the size -- if being -1, the size is initialized to -bytes , other values are ignored

 

Returns

a new BSSize


bs_size_new_from_str ()

BSSize *
bs_size_new_from_str (const gchar *size_str,
                      GError **error);

Creates a new BSSize instance.

[constructor]

Parameters

size_str

string representing the size as a number and an optional unit (e.g. "1 GiB")

 

Returns

a new BSSize


bs_size_new_from_size ()

BSSize *
bs_size_new_from_size (const BSSize *size);

Creates a new instance of BSSize.

[constructor]

Parameters

size

the size to create a new instance from (a copy of)

 

Returns

a new BSSize instance which is copy of size .

[transfer full]


bs_size_get_bytes ()

guint64
bs_size_get_bytes (const BSSize *size,
                   gint *sgn,
                   GError **error);

Get the number of bytes of the size .

Parameters

sgn

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


bs_size_sgn ()

gint
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


bs_size_get_bytes_str ()

gchar *
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]


bs_size_convert_to ()

gchar *
bs_size_convert_to (const BSSize *size,
                    BSUnit unit,
                    GError **error);

Get the size converted to unit as a string representing a floating-point number.

Parameters

unit

the unit to convert size to

 

Returns

a string representing the floating-point number that equals to size converted to unit .

[transfer full]


bs_size_human_readable ()

gchar *
bs_size_human_readable (const BSSize *size,
                        BSBunit min_unit,
                        gint max_places,
                        gboolean xlate);

Get a human-readable representation of size .

Parameters

min_unit

the smallest unit the returned representation should use

 

max_places

maximum number of decimal places the representation should use

 

xlate

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]


bs_size_add ()

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]


bs_size_grow ()

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]


bs_size_add_bytes ()

BSSize *
bs_size_add_bytes (const BSSize *size,
                   guint64 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]


bs_size_grow_bytes ()

BSSize *
bs_size_grow_bytes (BSSize *size,
                    guint64 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]


bs_size_sub ()

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]


bs_size_shrink ()

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]


bs_size_sub_bytes ()

BSSize *
bs_size_sub_bytes (const BSSize *size,
                   guint64 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 is equals to size - bytes .

[transfer full]


bs_size_shrink_bytes ()

BSSize *
bs_size_shrink_bytes (BSSize *size,
                      guint64 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]


bs_size_mul_int ()

BSSize *
bs_size_mul_int (const BSSize *size,
                 guint64 times);

Multiply size by times .

Returns

a new instance of BSSize which is equals to size * times .

[transfer full]


bs_size_grow_mul_int ()

BSSize *
bs_size_grow_mul_int (BSSize *size,
                      guint64 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]


bs_size_mul_float_str ()

BSSize *
bs_size_mul_float_str (const BSSize *size,
                       const gchar *float_str,
                       GError **error);

Multiply size by the floating-point number float_str represents.

Returns

a new BSSize instance which equals to size * times_str .

[transfer full]


bs_size_grow_mul_float_str ()

BSSize *
bs_size_grow_mul_float_str (BSSize *size,
                            const gchar *float_str,
                            GError **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]


bs_size_div ()

guint64
bs_size_div (const BSSize *size1,
             const BSSize *size2,
             gint *sgn,
             GError **error);

Divide size1 by size2 . Gives the answer to the question "How many times does size2 fit in size1 ?".

Parameters

sgn

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)


bs_size_div_int ()

BSSize *
bs_size_div_int (const BSSize *size,
                 guint64 divisor,
                 GError **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?"

Returns

a BSSize instance x so that x * divisor = size , rounded to a number of bytes.

[transfer full]


bs_size_shrink_div_int ()

BSSize *
bs_size_shrink_div_int (BSSize *size,
                        guint64 shrink_divisor,
                        GError **error);

Shrink size by dividing by divisor . IOW, divide size by divisor in-place.

Basically an in-place variant of bs_size_div_int().

Returns

size modified by division by divisor .

[transfer none]


bs_size_true_div ()

gchar *
bs_size_true_div (const BSSize *size1,
                  const BSSize *size2,
                  GError **error);

Divides size1 by size2 .

Returns

a string representing the floating-point number that equals to size1 / size2 .

[transfer full]


bs_size_true_div_int ()

gchar *
bs_size_true_div_int (const BSSize *size,
                      guint64 divisor,
                      GError **error);

Divides size by divisor .

Returns

a string representing the floating-point number that equals to size / divisor .

[transfer full]


bs_size_mod ()

BSSize *
bs_size_mod (const BSSize *size1,
             const BSSize *size2,
             GError **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]


bs_size_round_to_nearest ()

BSSize *
bs_size_round_to_nearest (const BSSize *size,
                          const BSSize *round_to,
                          BSRoundDir dir,
                          GError **error);

Round size to the nearest multiple of round_to according to the direction given by dir .

Parameters

round_to

to a multiple of what to round size

 

dir

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]


bs_size_cmp ()

gint
bs_size_cmp (const BSSize *size1,
             const BSSize *size2,
             gboolean abs);

Compare size1 and size2 . This function behaves like the standard *cmp*() functions.

Parameters

abs

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


bs_size_cmp_bytes ()

gint
bs_size_cmp_bytes (const BSSize *size1,
                   guint64 bytes,
                   gboolean abs);

Compare size and bytes , i.e. the number of bytes size has with bytes . This function behaves like the standard *cmp*() functions.

Parameters

abs

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

Types and Values

BS_SIZE_ERROR

#define BS_SIZE_ERROR bs_size_error_quark ()

Error domain for errors generated by attempts to do inappropriate operations with BSSize instances.


enum BSSizeError

Error codes that identify various errors that can occur while working with BSSize instances.

Members

BS_SIZE_ERROR_INVALID_SPEC

invalid size or unit spec provided

 

BS_SIZE_ERROR_OVER

a value is over the limits imposed by a type

 

BS_SIZE_ERROR_ZERO_DIV

an attemtp to do division by zero

 

enum BSBunit

Binary units (multiples of 1024) of size in bytes.

Members

BS_BUNIT_B

   

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

   

enum BSDunit

Decimal units (multiples of 1000) of size in bytes.

Members

BS_DUNIT_B

   

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

   

enum BSRoundDir

Rounding direction for rounding operations.

Members

BS_ROUND_DIR_UP

   

BS_ROUND_DIR_DOWN

   

BSUnit

Generic unit fo size in bytes.

Members

BSBunit bunit;

a binary unit

 

BSDunit dunit;

a decimal unit

 

BS_FLOAT_PREC_BITS

#define BS_FLOAT_PREC_BITS 256

Precision (in bits) of floating-point numbers used internally.