# core¶

## core.utils¶

core.utils.float_to_fraction(quantity, denominator=16)

Convert the given quantity into a fraction string, rounded to the nearest 1 / denominator increment. For example, if denominator is 16, round the result to the nearest 1/16th.

If quantity is less than 1.0, a simple fraction is returned:

```>>> float_to_fraction(0.5)
u"1/2"
```
```>>> float_to_fraction(0.33)
u"1/3"
```
```>>> float_to_fraction(0.25)
u"1/4"
```
```>>> float_to_fraction(0.125)
u"1/8"
```
```>>> float_to_fraction(0.1)
u"1/10"
```

If quantity is 1.0 or greater, a mixed fraction is returned, with a hyphen separating the integer part from the fractional part.

```>>> float_to_fraction(1.25)
u"1-1/4"
```
```>>> float_to_fraction(2.75)
u"2-3/4"
```
```>>> float_to_fraction(9.33)
u"9-1/3"
```

All results are rounded to the nearest 1 / denominator increment, so you can decide how precise you need the result to be:

```>>> float_to_fraction(0.1875, 16)
u"3/16"
```
```>>> float_to_fraction(0.1875, 8)
u"1/5"
```
```>>> float_to_fraction(0.1875, 4)
u"1/4"
```
core.utils.fraction_to_float(fraction_string)

Convert a fraction string into a floating-point value.

Simple fractions take the form of “n/d”:

```>>> fraction_to_float("1/2")
0.5
>>> fraction_to_float("3/8")
0.375
```

Mixed fractions may be separated by one or more spaces or hyphens.

```>>> fraction_to_float("1 1/4")
1.25
>>> fraction_to_float("1-1/4")
1.25
>>> fraction_to_float("1 - 1/4")
1.25
```

Any string that is already a decimal expression is just converted to its numeric form:

```>>> fraction_to_float("5.75")
5.75
>>> fraction_to_float(".5")
0.5
```
core.utils.pluralize(noun)

Pluralize the given noun, using a simple heuristic. Will pluralize some nouns incorrectly because English is beastly complicated.

Consonant + ‘o’ gets ‘-es’:

```>>> pluralize('potato')
'potatoes'
```

Sibilants get ‘-es’:

```>>> pluralize('batch')
'batches'
>>> pluralize('box')
'boxes'
```

Consonant + ‘y’ becomes ‘-ies’:

```>>> pluralize('cherry')
'cherries'
```

Endings of ‘f’ or ‘fe’ become ‘-ves’:

```>>> pluralize('loaf')
'loaves'
>>> pluralize('bay leaf')
'bay leaves'
>>> pluralize('knife')
'knives'
```

Simple ‘s’ ending:

```>>> pluralize('ounce')
'ounces'
>>> pluralize('egg')
'eggs'
```
core.utils.format_food_unit(quantity, unit, food)

Return a unicode string describing the given quantity of food. quantity may be an actual number (int or float), or a string containing a decimal or fraction as understood by fraction_to_float().

If a unit is given, the unit is pluralized when appropriate:

```>>> format_food_unit(2, 'cup', 'flour')
u"2 cups flour"
>>> format_food_unit(1.5, 'teaspoon', 'salt')
u"1-1/2 teaspoons salt"
>>> format_food_unit('1-3/4', 'ounce', 'butter')
u"1-3/4 ounces butter"
```

If no unit is given, the food is pluralized:

```>>> format_food_unit(3, None, 'egg')
u"3 eggs"
>>> format_food_unit(2, None, 'potato')
u"2 potatoes"
>>> format_food_unit('4-1/2', None, 'bell pepper')
u"4-1/2 bell peppers"
```

In all cases, if the quantity is <= 1, no pluralization is done:

```>>> format_food_unit(1, None, 'egg')
u"1 egg"
>>> format_food_unit(0.75, 'cup', 'flour')
u"3/4 cup flour"
>>> format_food_unit(0.5, 'cup', 'oil')
u"1/2 cup oil"
>>> format_food_unit('1/4', 'teaspoon', 'baking powder')
u"1/4 teaspoon baking powder"
```

## core.helpers¶

core.helpers.convert_unit(unit, to_unit)

Convert unit to the equivalent quantity to_unit. Requires that an Equivalence be defined for the relevant units; if no Equivalence is found, raise a NoEquivalence exception.

core.helpers.to_grams(unit, food=None)

Return the given unit in terms of grams. If unit is a volume, attempt to convert based on the given food’s density (g/ml). If food is not given, assume a density of 1.0 g/ml.

core.helpers.to_ml(unit, food=None)

Return the given unit in terms of milliliters. If unit is a weight, attempt to convert based on the given food‘s density (g/ml). If food is not given, assume a density of 1.0 g/ml.

core.helpers.convert_amount(quantity, unit, to_unit)

Convert a quantity in a given unit to the equivalent quantity in another unit. Requires that an Equivalence be defined for the relevant units; if no Equivalence is found, raise a NoEquivalence exception.

Add two amounts together (possibly using different units), and return the resulting quantity in terms of the first unit.

core.helpers.subtract_amount(quantity, unit, to_quantity, to_unit)

Subtract one amount from another (possibly using different units), and return the resulting quantity in terms of the first unit.

core.helpers.group_by_category(queryset)

Group objects in queryset by category name, and return a list of (category_name, [matching_objects]) for each category.

Objects in queryset must have a category attribute, where category itself has a name attribute.