66add54 · elk · git.iko.soy

git.iko.soy/elk

Merge pull request #245 from mgold/dev

Convert Color, Dict, and Set docs.

commit66add54195c8eb32f21041118b75c1fb7c49d871 authorEvan Czaplicki <info@elm-lang.org> dateMon 9 Sep 2013, 22:47 (13 years ago) parent035e62b 9e600f2

3 files changed+137−69

compare with master

unifiedsplit

libraries/Color.elm+50−30 libraries/Dict.elm+49−25 libraries/Set.elm+38−14

libraries/Color.elm+50−30

@@ -1,31 +1,52 @@

22module Color where

4+{-| Library for working with colors. Includes

5+[RGB](https://en.wikipedia.org/wiki/RGB_color_model) and

6+[HSV](http://en.wikipedia.org/wiki/HSL_and_HSV) creation, gradients, and

7+built-in names.

9+# Creation

10+@docs rgb, rgba, hsv, hsva, grayscale, greyscale

11+

12+# From Other Colors

13+@docs complementary

14+

15+# Gradients

16+@docs linear radial

17+

18+# Built-in Colors

19+These come from the [Tango

20+palette](http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines).

21+@docs red, orange, yellow, green, blue, purple, brown, black, white, grey, gray, charcoal, lightRed, lightOrange, lightYellow, lightGreen, lightBlue, lightPurple, lightBrown, lightGrey, lightGray, lightCharcoal, darkRed, darkOrange, darkYellow, darkGreen, darkBlue, darkPurple, darkBrown, darkGrey, darkGray, darkCharcoal

22+

23+-}

24+

425import Native.Color

526import Basics ((-))

627

728data Color = Color Int Int Int Float

829

9−-- Create RGB colors with an alpha component for transparency.

10−-- The alpha component is specified with numbers between 0 and 1.

30+{-| Create RGB colors with an alpha component for transparency.

31+The alpha component is specified with numbers between 0 and 1. -}

1132rgba : Int -> Int -> Int -> Float -> Color

1233rgba = Color

1334

14−-- Create RGB colors from numbers between 0 and 255 inclusive.

35+{-| Create RGB colors from numbers between 0 and 255 inclusive. -}

1536rgb : Int -> Int -> Int -> Color

1637rgb r g b = Color r g b 1

1738

18−lightYellow = Color 255 233 79 1

19−yellow = Color 237 212 0 1

20−darkYellow = Color 196 160 0 1

39+lightRed = Color 239 41 41 1

40+red = Color 204 0 0 1

41+darkRed = Color 164 0 0 1

2142

2243lightOrange = Color 252 175 62 1

2344orange = Color 245 121 0 1

2445darkOrange = Color 206 92 0 1

2546

26−lightBrown = Color 233 185 110 1

27−brown = Color 193 125 17 1

28−darkBrown = Color 143 89 2 1

47+lightYellow = Color 255 233 79 1

48+yellow = Color 237 212 0 1

49+darkYellow = Color 196 160 0 1

2950

3051lightGreen = Color 138 226 52 1

3152green = Color 115 210 22 1

@@ -39,9 +60,9 @@ lightPurple = Color 173 127 168 1

3960purple = Color 117 80 123 1

4061darkPurple = Color 92 53 102 1

4162

42−lightRed = Color 239 41 41 1

43−red = Color 204 0 0 1

44−darkRed = Color 164 0 0 1

63+lightBrown = Color 233 185 110 1

64+brown = Color 193 125 17 1

65+darkBrown = Color 143 89 2 1

4566

4667black = Color 0 0 0 1

4768white = Color 255 255 255 1

@@ -58,25 +79,24 @@ lightCharcoal = Color 136 138 133 1

5879charcoal = Color 85 87 83 1

5980darkCharcoal = Color 46 52 54 1

6081

82+{-| Produce a gray based on the input. 0 is white, 1 is black. -}

6183grayscale : Float -> Color

6284grayscale p = hsv 0 0 (1-p)

6385greyscale p = hsv 0 0 (1-p)

6486

65−-- Produce a “complementary color”.

66−-- The two colors will accent each other.

87+{-| Produce a “complementary color”.

88+The two colors will accent each other. -}

6789complement : Color -> Color

6890complement = Native.Color.complement

6991

70−-- Create [HSV colors](http://en.wikipedia.org/wiki/HSL_and_HSV)

71−-- with an alpha component for transparency.

92+{-| Create [HSV colors](http://en.wikipedia.org/wiki/HSL_and_HSV)

93+with an alpha component for transparency. -}

7294hsva : Float -> Float -> Float -> Float -> Color

7395hsva = Native.Color.hsva

7496

75−-- Create [HSV colors](http://en.wikipedia.org/wiki/HSL_and_HSV).

76−-- This is very convenient for creating colors that cycle and shift.

77−-- Hue is an angle and should be given in standard Elm angles (radians).

78−--

79−-- hsv (degrees 240) 1 1 == blue

97+{-| Create [HSV colors](http://en.wikipedia.org/wiki/HSL_and_HSV). This is very

98+convenient for creating colors that cycle and shift. Hue is an angle and should

99+be given in standard Elm angles (radians). -}

80100hsv : Float -> Float -> Float -> Color

81101hsv = Native.Color.hsv

82102

@@ -84,17 +104,17 @@ data Gradient

84104 = Linear (Float,Float) (Float,Float) [(Float,Color)]

85105 | Radial (Float,Float) Float (Float,Float) Float [(Float,Color)]

86106

87−-- Create a linear gradient. Takes a start and end point and then a series

88−-- of “color stops” that indicate how to interpolate between

89−-- the start and end points. See [this example](/edit/examples/Elements/LinearGradient.elm) for

90−-- a more visual explanation.

107+{-| Create a linear gradient. Takes a start and end point and then a series of

108+“color stops” that indicate how to interpolate between the start and

109+end points. See [this example](/edit/examples/Elements/LinearGradient.elm) for a

110+more visual explanation. -}

91111linear : (number, number) -> (number, number) -> [(Float,Color)] -> Gradient

92112linear = Linear

93113

94−-- Create a radial gradient. First takes a start point and inner radius.

95−-- Then takes an end point and outer radius. It then takes a series

96−-- of “color stops” that indicate how to interpolate between

97−-- the inner and outer circles. See [this example](/edit/examples/Elements/RadialGradient.elm) for

98−-- a more visual explanation.

114+{-| Create a radial gradient. First takes a start point and inner radius. Then

115+takes an end point and outer radius. It then takes a series of “color

116+stops” that indicate how to interpolate between the inner and outer

117+circles. See [this example](/edit/examples/Elements/RadialGradient.elm) for a

118+more visual explanation. -}

99119radial : (number,number) -> number -> (number,number) -> number -> [(Float,Color)] -> Gradient

100120radial = Radial

libraries/Dict.elm+49−25

@@ -8,6 +8,30 @@ module Dict (empty,singleton,insert

88 ,toList,fromList

99 ) where

1010

11+{-|A dictionary mapping unique keys to values. The keys can be any comparable

12+type. This includes `Int`, `Float`, `Time`, `Char`, `String`, and tuples or

13+lists of comparable types.

14+

15+Insert, remove, and query operations all take *O(log n)* time.

16+

17+# Build

18+@docs empty, singleton, insert, remove

19+

20+# Query

21+@docs member, lookup, findWithDefault

22+

23+# Combine

24+@docs union, intersect, diff

25+

26+# Lists

27+@docs keys, values, toList, fromList

28+

29+# Transform

30+@docs map, foldl, foldr

31+

32+-}

33+

34+

1135import open Basics

1236import open Maybe

1337import Native.Error

@@ -18,7 +42,7 @@ data NColor = Red | Black

1842

1943data Dict k v = RBNode NColor k v (Dict k v) (Dict k v) | RBEmpty

2044

21−-- Create an empty dictionary.

45+{-| Create an empty dictionary. -}

2246empty : Dict comparable v

2347empty = RBEmpty

2448

@@ -116,7 +140,7 @@ max t =

116140 }

117141--}

118142

119−-- Lookup the value associated with a key.

143+{-| Lookup the value associated with a key. -}

120144lookup : comparable -> Dict comparable v -> Maybe v

121145lookup k t =

122146 case t of

@@ -127,8 +151,8 @@ lookup k t =

127151 EQ -> Just v

128152 GT -> lookup k r

129153

130−-- Find the value associated with a key. If the key is not found,

131−-- return the default value.

154+{-| Find the value associated with a key. If the key is not found,

155+return the default value. -}

132156findWithDefault : v -> comparable -> Dict comparable v -> v

133157findWithDefault base k t =

134158 case t of

@@ -152,7 +176,7 @@ find k t =

152176 }

153177--}

154178

155−-- Determine if a key is in a dictionary.

179+{-| Determine if a key is in a dictionary. -}

156180member : comparable -> Dict comparable v -> Bool

157181-- Does t contain k?

158182member k t = isJust <| lookup k t

@@ -208,8 +232,8 @@ ensureBlackRoot t =

208232 RBNode Red k v l r -> RBNode Black k v l r

209233 _ -> t

210234

211−-- Insert a key-value pair into a dictionary. Replaces value when there is

212−-- a collision.

235+{-| Insert a key-value pair into a dictionary. Replaces value when there is

236+a collision. -}

213237insert : comparable -> v -> Dict comparable v -> Dict comparable v

214238insert k v t = -- Invariant: t is a valid left-leaning rb tree

215239 let ins t =

@@ -231,7 +255,7 @@ insert k v t = -- Invariant: t is a valid left-leaning rb tree

231255 else new_t)

232256--}

233257

234−-- Create a dictionary with one key-value pair.

258+{-| Create a dictionary with one key-value pair. -}

235259singleton : comparable -> v -> Dict comparable v

236260singleton k v = insert k v RBEmpty

237261

@@ -312,8 +336,8 @@ deleteMax t =

312336 in ensureBlackRoot (del t)

313337--}

314338

315−-- Remove a key-value pair from a dictionary. If the key is not found,

316−-- no changes are made.

339+{-| Remove a key-value pair from a dictionary. If the key is not found,

340+no changes are made. -}

317341remove : comparable -> Dict comparable v -> Dict comparable v

318342remove k t =

319343 let eq_and_noRightNode t =

@@ -346,58 +370,58 @@ remove k t =

346370 Native.Error.raise "invariants broken after remove")

347371--}

348372

349−-- Apply a function to all values in a dictionary.

373+{-| Apply a function to all values in a dictionary. -}

350374map : (a -> b) -> Dict comparable a -> Dict comparable b

351375map f t =

352376 case t of

353377 RBEmpty -> RBEmpty

354378 RBNode c k v l r -> RBNode c k (f v) (map f l) (map f r)

355379

356−-- Fold over the key-value pairs in a dictionary, in order from lowest

357−-- key to highest key.

380+{-| Fold over the key-value pairs in a dictionary, in order from lowest

381+key to highest key. -}

358382foldl : (comparable -> v -> b -> b) -> b -> Dict comparable v -> b

359383foldl f acc t =

360384 case t of

361385 RBEmpty -> acc

362386 RBNode _ k v l r -> foldl f (f k v (foldl f acc l)) r

363387

364−-- Fold over the key-value pairs in a dictionary, in order from highest

365−-- key to lowest key.

388+{-| Fold over the key-value pairs in a dictionary, in order from highest

389+key to lowest key. -}

366390foldr : (comparable -> v -> b -> b) -> b -> Dict comparable v -> b

367391foldr f acc t =

368392 case t of

369393 RBEmpty -> acc

370394 RBNode _ k v l r -> foldr f (f k v (foldr f acc r)) l

371395

372−-- Combine two dictionaries. If there is a collision, preference is given

373−-- to the first dictionary.

396+{-| Combine two dictionaries. If there is a collision, preference is given

397+to the first dictionary. -}

374398union : Dict comparable v -> Dict comparable v -> Dict comparable v

375399union t1 t2 = foldl insert t2 t1

376400

377−-- Keep a key-value pair when its key appears in the second dictionary.

378−-- Preference is given to values in the first dictionary.

401+{-| Keep a key-value pair when its key appears in the second dictionary.

402+Preference is given to values in the first dictionary. -}

379403intersect : Dict comparable v -> Dict comparable v -> Dict comparable v

380404intersect t1 t2 =

381405 let combine k v t = if k `member` t2 then insert k v t else t

382406 in foldl combine empty t1

383407

384−-- Keep a key-value pair when its key does not appear in the second dictionary.

385−-- Preference is given to the first dictionary.

408+{-| Keep a key-value pair when its key does not appear in the second dictionary.

409+Preference is given to the first dictionary. -}

386410diff : Dict comparable v -> Dict comparable v -> Dict comparable v

387411diff t1 t2 = foldl (\k v t -> remove k t) t1 t2

388412

389−-- Get all of the keys in a dictionary.

413+{-| Get all of the keys in a dictionary. -}

390414keys : Dict comparable v -> [comparable]

391415keys t = foldr (\k v acc -> k :: acc) [] t

392416

393−-- Get all of the values in a dictionary.

417+{-| Get all of the values in a dictionary. -}

394418values : Dict comparable v -> [v]

395419values t = foldr (\k v acc -> v :: acc) [] t

396420

397−-- Convert a dictionary into an association list of key-value pairs.

421+{-| Convert a dictionary into an association list of key-value pairs. -}

398422toList : Dict comparable v -> [(comparable,v)]

399423toList t = foldr (\k v acc -> (k,v) :: acc) [] t

400424

401−-- Convert an association list into a dictionary.

425+{-| Convert an association list into a dictionary. -}

402426fromList : [(comparable,v)] -> Dict comparable v

403427fromList assocs = List.foldl (\(k,v) d -> insert k v d) empty assocs

libraries/Set.elm+38−14

@@ -6,61 +6,85 @@ module Set (empty,singleton,insert,remove

66 ,toList,fromList

77 ) where

9+{-|A set of unique values. The values can be any comparable type. This includes

10+`Int`, `Float`, `Time`, `Char`, `String`, and tuples or lists of comparable

11+types.

12+

13+Insert, remove, and query operations all take *O(log n)* time.

14+

15+# Build

16+@docs empty, singleton, insert, remove

17+

18+# Query

19+@docs member

20+

21+# Combine

22+@docs union, intersect, diff

23+

24+# Lists

25+@docs toList, fromList

26+

27+# Transform

28+@docs map, foldl, foldr

29+

30+-}

31+

932import Maybe (Maybe)

1033import Dict as Dict

1134import List as List

1235

1336type Set t = Dict.Dict t ()

1437

15−-- Create an empty set.

38+{-| Create an empty set. -}

1639empty : Set comparable

1740empty = Dict.empty

1841

19−-- Create a set with one value.

42+{-| Create a set with one value. -}

2043singleton : comparable -> Set comparable

2144singleton k = Dict.singleton k ()

2245

23−-- Insert a value into a set.

46+{-| Insert a value into a set. -}

2447insert : comparable -> Set comparable -> Set comparable

2548insert k = Dict.insert k ()

2649

27−-- Remove a value from a set. If the value is not found, no changes are made.

50+{-| Remove a value from a set. If the value is not found, no changes are made.

51+-}

2852remove : comparable -> Set comparable -> Set comparable

2953remove = Dict.remove

3054

31−-- Determine if a value is in a set.

55+{-| Determine if a value is in a set. -}

3256member : comparable -> Set comparable -> Bool

3357member = Dict.member

3458

35−-- Get the union of two sets. Keep all values.

59+{-| Get the union of two sets. Keep all values. -}

3660union : Set comparable -> Set comparable -> Set comparable

3761union = Dict.union

3862

39−-- Get the intersection of two sets. Keeps values that appear in both sets.

63+{-| Get the intersection of two sets. Keeps values that appear in both sets. -}

4064intersect : Set comparable -> Set comparable -> Set comparable

4165intersect = Dict.intersect

4266

43−-- Get the difference between the first set and the second. Keeps values

44−-- that do not appear in the second set.

67+{-| Get the difference between the first set and the second. Keeps values

68+that do not appear in the second set. -}

4569diff : Set comparable -> Set comparable -> Set comparable

4670diff = Dict.diff

4771

48−-- Convert a set into a list.

72+{-| Convert a set into a list. -}

4973toList : Set comparable -> [comparable]

5074toList = Dict.keys

5175

52−-- Convert a list into a set, removing any duplicates.

76+{-| Convert a list into a set, removing any duplicates. -}

5377fromList : [comparable] -> Set comparable

5478fromList xs = List.foldl insert empty xs

5579

56−-- Fold over the values in a set, in order from lowest to highest.

80+{-| Fold over the values in a set, in order from lowest to highest. -}

5781foldl : (comparable -> b -> b) -> b -> Set comparable -> b

5882foldl f b s = Dict.foldl (\k _ b -> f k b) b s

5983

60−-- Fold over the values in a set, in order from highest to lowest.

84+{-| Fold over the values in a set, in order from highest to lowest. -}

6185foldr : (comparable -> b -> b) -> b -> Set comparable -> b

6286foldr f b s = Dict.foldr (\k _ b -> f k b) b s

6387

64−-- Map a function onto a set, creating a new set with no duplicates.

88+{-| Map a function onto a set, creating a new set with no duplicates. -}

6589map : (comparable -> comparable') -> Set comparable -> Set comparable'

6690map f s = fromList (List.map f (toList s))