From 7e04e0b480d83dcbd82d6470b2199de69fce6c04 Mon Sep 17 00:00:00 2001 From: Laurent Callarec Date: Tue, 14 Apr 2020 16:06:36 +0200 Subject: [PATCH] Add documentation --- README.md | 244 ++++++++++++++++++++++++++++++++++++++++++- meson.build | 2 +- resources/united.png | Bin 0 -> 2408 bytes src/Prefix.vala | 1 - 4 files changed, 243 insertions(+), 4 deletions(-) create mode 100644 resources/united.png diff --git a/README.md b/README.md index 7bd5322..7f20862 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,243 @@ -# United -WIP / Units manipulation in Vala made easy +![United logo](resources/united.png) + +![CI](https://github.com/lcallarec/united/workflows/CI/badge.svg) +[![codecov](https://codecov.io/gh/lcallarec/united/branch/master/graph/badge.svg)](https://codecov.io/gh/lcallarec/united) +[![Release](https://img.shields.io/github/release/lcallarec/united.svg)](https://github.com/lcallarec/united/releases) +[![License](https://img.shields.io/github/license/lcallarec/united)](https://github.com/lcallarec/united/blob/master/LICENSE) + +#### Unit manipulation made easy + +# Units + +There's two main units in [United](https://github.com/lcallarec/united/) : + +* [`Value`](#value), which hold any [SI derived units](https://en.wikipedia.org/wiki/International_System_of_Units) +* [`Bytes`](#bytes), which can be SI prefixed (ex. kB, MB...) or IEC / Binary prefixed (ex. KiB, GiB...) + +And lists of prefixes : + +* [`Prefix`](#prefixes), which represent some [SI derived prefixes](https://en.wikipedia.org/wiki/International_System_of_Units) +* [`BinaryPrefix`](#binary-prefixes), which meant to represent [Binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) to be used with `Bytes`. + + +## Value + +* Create a value : + +```vala +// From value and unit (potentially prefixed) +var weight = new Value(5, "g"); +var weight = new Value(5.97, "kg"); + +// From string +var weight = new Value.from_string("15,8g"); + +//From known attributes +var weight = new Value.from_attributes(8.15, "g", Prefix.kilo()); +``` + +* Public attributes and presentation methods + +```vala +var power = new Value.from_string("2.21GW"); + +power.measure; // 2.21 +power.unit; // "W" +power.prefix; // Prefix.GIGA +power.to_string(); // "2.21GW" +power.to_string("%.1f"); // "2.2GW" +``` + +* Convert to another Prefix + +```vala +var power_in_GW = new Value(2.21, "GW"); + +power_in_GW.measure; // 2.21 +power_in_GW.unit; // "W" +power_in_GW.prefix; // Prefix.GIGA +power_in_GW.to_string(); // "2.21GW" + + +var power_in_kW = power_in_GW.to(Prefix.KILO); + +power_in_kW.measure; // 2210000 +power_in_kW.unit; // "W" +power_in_kW.prefix; // Prefix.KILO +power_in_kW.to_string(); // "2210000kW" +``` + +* Convert to an human readable format + +Humans don't like to read 2210000000W. They prefer reading number lower than 1000. + +```vala +var power_in_GW = new Value(2210000000, "W"); + +var human_readable = power_in_GW.to_human(); + +human_readable.measure; // 2.21 +human_readable.unit; // "W" +human_readable.prefix; // Prefix.GIGA +human_readable.to_string(); // "2.21GW" +``` + +# Prefixes + +Prefixes are mostly used to convert a value to another value, or print a custom value. + +```vala +var yotta = Prefix.yotta(); //Shortcut for new Prefix(Prefix.YOTTA); +var zeta = Prefix.zeta(); //Shortcut for new Prefix(Prefix.ZETA); +var exa = Prefix.exa(); //Shortcut for new Prefix(Prefix.EXA); +var peta = Prefix.peta(); //Shortcut for new Prefix(Prefix.PETA); +var tera = Prefix.tera(); //Shortcut for new Prefix(Prefix.TERA); +var giga = Prefix.giga(); //Shortcut for new Prefix(Prefix.GIGA); +var mega = Prefix.mega(); //Shortcut for new Prefix(Prefix.MEGA); +var kilo = Prefix.kilo(); //Shortcut for new Prefix(Prefix.KILO); +var none = Prefix.none(); //Shortcut for new Prefix(Prefix.NONE); +var milli = Prefix.milli(); //Shortcut for new Prefix(Prefix.MILLI); +var micro = Prefix.micro(); //Shortcut for new Prefix(Prefix.MICRO); +var nano = Prefix.nano(); //Shortcut for new Prefix(Prefix.NANO); +var pico = Prefix.pico(); //Shortcut for new Prefix(Prefix.PICO); +var femto = Prefix.femto(); //Shortcut for new Prefix(Prefix.FEMTO); +var atto = Prefix.atto(); //Shortcut for new Prefix(Prefix.ATTO); +var zepto = Prefix.zepto(); //Shortcut for new Prefix(Prefix.ZEPTO); +var yocto = Prefix.yocto(); //Shortcut for new Prefix(Prefix.YOCTO); + +// Convert +var power = new Value(2.21, "GW"); +var MW = power.to(Prefix.mega()); + +MW.measure; // 2210 +MW.unit; // "W" +MW.prefix; // Prefix.MEGA +MW.to_string(); // "2210MW" + +``` + +Print a prefix : + +```vala +yotta.to_string(); // "Y" +zeta.to_string(); // "Z" +exa.to_string(); // "E" +peta.to_string(); // "P" +tera.to_string(); // "T" +giga.to_string(); // "G" +mega.to_string(); // "M" +kilo.to_string(); // "k" +none.to_string(); // "" +milli.to_string(); // "m" +micro.to_string(); // "μ" +nano.to_string(); // "n" +pico.to_string(); // "p" +femto.to_string(); // "f" +atto.to_string(); // "a" +zepto.to_string(); // "z" +yocto.to_string(); // "y" +``` + +## Bytes + +Bytes share most of the `Value` features. + +* Create a Bytes : + +```vala +// From value and unit (potentially prefixed) +var size = new Bytes(5, "B"); +var size = new Value(5.97, "MB"); + +``` + +* Public attributes and presentation methods + +```vala +var size = new Bytes(2097152, "B"); + +size.value; // 2097152 +size.unit; // "B" +size.prefix; // Prefix.NONE +size.to_string(); // "2097152BW" +``` + +* Convert to another Prefix + +SI prefixes : + +```vala +var b = new Bytes(2097152, "B"); + +var kb = b.to(Prefix.kilo()); + +kb.value; // 2097,152 +kb.unit; // "B" +kb.prefix; // Prefix.KILO +kb.to_string(); // "2097,152kB" +``` + +To binary prefixes : + +```vala +var b = new Bytes(2097152, "B"); +var kb = b.to(Prefix.kilo()); +var MiB = kb.to(BinaryPrefix.mebi()); + +kb.value; // 2 +kb.unit; // "B" +kb.prefix; // BinaryPrefix.MEBI; +kb.to_string(); // "2MiB" +``` + +* Convert to an human readable format + +Humans don't like to read 2097152B. They prefer reading number lower than 1000. + +```vala +var b = new Bytes(2097152, "B"); +var human_readable = b.to_human(); + +human_readable.to_string(); // "2MiB" +``` + +# Binary prefixes + +Binary prefixes should only be used with Bytes type. + +```vala +var yobi = BinaryPrefix.yobi(); // Shortcut for new BinaryPrefix(BinaryPrefix.YOBI); +var zebi = BinaryPrefix.zebi(); // Shortcut for new BinaryPrefix(BinaryPrefix.ZEBI); +var exbi = BinaryPrefix.exbi(); // Shortcut for new BinaryPrefix(BinaryPrefix.EXBI); +var pebi = BinaryPrefix.pebi(); // Shortcut for new BinaryPrefix(BinaryPrefix.PEBI); +var tebi = BinaryPrefix.tebi(); // Shortcut for new BinaryPrefix(BinaryPrefix.TEBI); +var gibi = BinaryPrefix.gibi(); // Shortcut for new BinaryPrefix(BinaryPrefix.GIBI); +var mebi = BinaryPrefix.mebi(); // Shortcut for new BinaryPrefix(BinaryPrefix.MEBI); +var kibi = BinaryPrefix.kibi(); // Shortcut for new BinaryPrefix(BinaryPrefix.KIBI); +var none = BinaryPrefix.none(); // Shortcut for new BinaryPrefix(BinaryPrefix.NONE); + +// Convert +var size = new Bytes(1024); +var KB = size.to(BinaryPrefix.kilo()); + +KB.value; // 1 +KB.unit; // "B" +KB.prefix; // BinaryPrefix.KILO; +KB.to_string(); // "1KiB" + +``` + +Print a prefix : + +```vala +yobi.to_string(); // "Yi" +zebi.to_string(); // "Zi" +exbi.to_string(); // "Ei" +pebi.to_string(); // "Pi" +tebi.to_string(); // "Ti" +gibi.to_string(); // "Gi" +mebi.to_string(); // "Mi" +kibi.to_string(); // "Ki" +none.to_string(); // "" +``` \ No newline at end of file diff --git a/meson.build b/meson.build index 4a8e29b..6d99b4a 100644 --- a/meson.build +++ b/meson.build @@ -1,4 +1,4 @@ -project('united', ['vala', 'c'], version: '0.1') +project('united', ['vala', 'c'], version: '0.7') cc = meson.get_compiler('c') libm = cc.find_library('m', required: true) diff --git a/resources/united.png b/resources/united.png new file mode 100644 index 0000000000000000000000000000000000000000..6707124b574cf69abcb4ac7e1cfec3285847a51d GIT binary patch literal 2408 zcmcImX;70%8vYoOLLef;6pjai7(5UHl945VsN6va2pJF}r%5&2wup%(RHdD2=Tl-`GSkphczwYXO>+AP<-skBn zo;YWO+IBSvf)H322QLUx8Ux=HRTa<=e;j`R2IXiwEM66~WL4s2FyF>-JjL*)kr{Cz zbP^PHmPRF+M4zFPNN1zNX$<*>r?y}dYJHPEofN`|pqSV9kmlLu=YGLF?kl@4p%#A`sf%5ydOX zrj0y}W^wO4XD-F|S@EU{#j1>_t9xFlS7EaOf^f>3_26&UJbny>pq-)dO3=B>?>0iu z$|^@SZ4y4U{jerB%5fR$=(sH3SzA|!Ap`|2vb=qL!wTJ;`Z}T_BKSHwI!Hfzd;8dh z4=1q$Aq%TtlUC;5T|i1@!@PmMzPHvDc%$L|3XhG%7)P+Lg6QtwpvD1QWBxBgI!-QyxM*nNntPq@8_Q&DIQ}e5FU*d2We|-HhB-7K66xK^Jag8oHrNC@-SdR<6 zs|$D2=0HMPc6(^7V#@va9^UeDVgr5hDpESxS@8L7%LXw9pzu*tr&y#VHYi^>-rJR& z=I-VuyJq`?ii!$Sa^j8`7gu*0_nP0;2x!vD1^AP~@Pz;s7A-Y3@b!Vx-cBnL&kwt= zHr@t>5zo!d9oL(zc|HAbBKcML!mVts9Dq9EkI>NAxo~ndGBnhV-W+W9MDn!7xf_Bk z+vdK5-fn4Chkmu!FomGahZ?_q5nsD<9)LbFHuhO}XZDMfFj*$iJc2+VG)Mar2pg%f zcwb*aT-;-%^f_}!tbFVU)@N_-111w8#v_7V@IwSf8YQhig7BM=Dg*46j#ZxiFSuUx#T!x`&n zKYRrOXHH;#b1-;RR|hyUAP^9CrS-z=r&S0xA%NI9xyg>lQPx%=5ZPeQmkr zW_HoPmE{`?;J=Pn3cnt6cFvs8y!bZ@i{+jn&G~qdm6cVpL>-Do0*&%6M;h z`JhN-oUoZfp>R&4)VI$z`o_e>V7W6=sUe1JT@%);NS3sX|8jgs)AQ#}{HD2@#e$=k z;t~@4%p1X(X7p$KGSB;ylO!?b{IO$wWaoQ$80ZdQO+Ki+rUZo(jJCF>jE;`NY`498 z8hoyJGHP*pE z3%d`^D=ONKz2-$A6uaYauH2WC+=a0%dg(kgHQLri3Oc{x1z_Q9DK%G8DB z(oDhnuUjV)HgJwNZLXl*w<-EdRV-5USrl8 zOB++n(dhBQ!U;-p^6C8A`}gk$Ij@#Z(lNtJcPlD1mn~N!BO_g7Ia3meA?wppBiq}e zIFI3#^`j#~%=WIp`6VSaAf;xBE1x+g zD3mJ~b^1v#@TcZzV1GxFzjy*KF> zLU83{0q})`Knd7oWxJ&_Gcd8ct7~X#>h6F1Sjcp#=pT6f+JG