Skip to content
Permalink
Browse files

Lots of updates to the documentation from the wiki (and some new cont…

…ent, too)
  • Loading branch information
tonyarnold committed Nov 1, 2014
1 parent 12b98e3 commit 0c35d9f81d518edd17d79a7f7a3eb5573477ea9d
@@ -1,5 +1,5 @@
additional_guides:
- https://github.com/magicalpanda/MagicalRecord/wiki/Installation
- https://github.com/magicalpanda/MagicalRecord/wiki/Installing-MagicalRecord
- https://github.com/magicalpanda/MagicalRecord/wiki/Getting-Started
- https://github.com/magicalpanda/MagicalRecord/wiki/Working-with-Managed-Object-Contexts
- https://github.com/magicalpanda/MagicalRecord/wiki/Creating-Entities
@@ -22,4 +22,4 @@ Fork this repository, make some great changes (preferably in a branch named for

All code contributions should match our [coding conventions](/magicalpanda/MagicalRecord/wiki/Coding-Conventions).

Thanks for reading the guidelines!
Thanks for reading the guidelines!
@@ -0,0 +1,13 @@
# Creating Entities

To create and insert a new instance of an Entity in the default context, you can use:

```objective-c
Person *myPerson = [Person MR_createEntity];
```

To create and insert an entity into specific context:

```objective-c
Person *myPerson = [Person MR_createEntityInContext:otherContext];
```

This file was deleted.

@@ -0,0 +1,25 @@
# Deleting Entities

To delete a single entity in the default context:

```objective-c
[myPerson MR_deleteEntity];
```

To delete the entity from a specific context:

```objective-c
[myPerson MR_deleteEntityInContext:otherContext];
```

To truncate all entities from the default context:

```objective-c
[Person MR_truncateAll];
```

To truncate all entities in a specific context:

```objective-c
[Person MR_truncateAllInContext:otherContext];
```
@@ -0,0 +1,131 @@
# Fetching Entities

> This document is being revised for MagicalRecord 2.3.0, and may contain information that is out of date. Please refer to the MagicalRecord's headers if anything here doesn't make sense.
#### Basic Finding

Most methods in MagicalRecord return an `NSArray` of results.

As an example, if you have an entity named *Person* related to a *Department* entity (as seen in many examples throughout [Apple's Core Data documentation)[https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/CoreData/), you can retrieve all of the *Person* entities from your persistent store using the following method:

```objective-c
NSArray *people = [Person MR_findAll];
```

To return the same entities sorted by a specific attribute:

```objective-c
NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName"
ascending:YES];
```

To return the entities sorted by multiple attributes:

```objective-c
NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName"
ascending:YES];
```

To return the results sorted by multiple attributes with different values. If you don't provide a value for any attribute, it will default to whatever you've set in your model:

```objective-c
NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName"
ascending:YES];
// OR
NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES"
ascending:NO];
```

If you have a unique way of retrieving a single object from your data store (such as an identifier attribute), you can use the following method:

```objective-c
Person *person = [Person MR_findFirstByAttribute:@"FirstName"
withValue:@"Forrest"];
```

#### Advanced Finding

If you want to be more specific with your search, you can use a predicate:

```objective-c
NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", @[dept1, dept2]];
NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
```

#### Returning an NSFetchRequest

```objective-c
NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
NSFetchRequest *people = [Person MR_requestAllWithPredicate:peopleFilter];
```

For each of these single line calls, an `NSFetchRequest` and `NSSortDescriptor`s for any sorting criteria are created.

#### Customizing the Request

```objective-c
NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
[peopleRequest setReturnsDistinctResults:NO];
[peopleRequest setReturnPropertiesNamed:@[@"FirstName", @"LastName"]];
NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
```

#### Find the number of entities

You can also perform a count of all entities of a specific type in your persistent store:

```objective-c
NSNumber *count = [Person MR_numberOfEntities];
```

Or, if you're looking for a count of entities based on a predicate or some filter:

```objective-c
NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
```

There are also complementary methods which return `NSUInteger` rather than `NSNumber` instances:

```objective-c
+ (NSUInteger) MR_countOfEntities;
+ (NSUInteger) MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context;
+ (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter;
+ (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter
inContext:(NSManagedObjectContext *)context;
```

#### Aggregate Operations

```objective-c
NSNumber *totalCalories = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:"
onAttribute:@"calories"
withPredicate:predicate];
NSNumber *mostCalories = [CTFoodDiaryEntry MR_aggregateOperation:@"max:"
onAttribute:@"calories"
withPredicate:predicate];
NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:"
onAttribute:@"calories"
withPredicate:predicate
groupBy:@"month"];
```

#### Finding entities in a specific context

All find, fetch, and request methods have an `inContext:` method parameter that allows you to specify which managed object context you'd like to query:

```objective-c
NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName"
withValue:@"Gump"
inContext:someOtherContext];
NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
```

This file was deleted.

@@ -1,9 +1,20 @@
# Getting Started

## Setting up the Core Data Stack
To get started, import the `MagicalRecord.h` header file in your project's pch file. This will allow a global include of all the required headers.

To get started, first, import the header file *CoreData+MagicalRecord.h* in your project's pch file. This will allow a global include of all the required headers.
Next, somewhere in your app delegate, in either the applicationDidFinishLaunching:(UIApplication \*) withOptions:(NSDictionary \*) method, or awakeFromNib, use **one** of the following setup calls with the **MagicalRecord** class:
If you're using CocoaPods or MagicalRecord.framework, your import should look like:

```objective-c
#import <MagicalRecord/MagicalRecord.h>
```

Otherwise, if you've added MagicalRecord's source files directly to your project, your import should be:

```objective-c
#import "MagicalRecord.h"
```

Next, somewhere in your app delegate, in either the `- applicationDidFinishLaunching: withOptions:` method, or `-awakeFromNib`, use **one** of the following setup calls with the **MagicalRecord** class:

```objective-c
+ (void)setupCoreDataStack;

0 comments on commit 0c35d9f

Please sign in to comment.
You can’t perform that action at this time.