{"action":"created","comment":{"url":"https://api.github.com/repos/google/j2objc/pulls/comments/46206871","id":46206871,"diff_hunk":"@@ -3,6 +3,67 @@ title: Arrays\n layout: docs\n ---\n \n-Objective-C doesn't add any syntactic sugar for arrays; developers either use C arrays or Foundation collection classes like `NSArray`.  `NSMutableArray` is similar to `java.util.ArrayList`, while `NSArray` is like a `Collections.UnmodifiableList`.  Java arrays don't map to either of these classes, though, because they are both mutable and fixed size.  Like Java collections, Foundation collections only support object elements, so mapping primitive arrays to them would impact performance.  C arrays cannot be used as substitutes for Java arrays, because of the need for bounds checking, and support for the length and clone methods.\n+The Objective-C language doesn't add any syntactic sugar to arrays; developers either use C arrays or\n+Foundation collection classes like `NSArray`.  `NSMutableArray` is similar to `java.util.ArrayList`,\n+while `NSArray` is like a `Collections.UnmodifiableList`.  Java arrays don't map to either of these\n+classes, though, because they are both mutable and fixed size.  Like Java collections, Foundation\n+collections only support object elements, so mapping primitive arrays to them would impact\n+performance.  C arrays cannot be used as substitutes for Java arrays, because of the need for bounds\n+checking, support for the length, clone methods, and reflection support.\n \n-Consequently, array classes for objects and each primitive type were created.  These classes are thin wrappers around C arrays to be fast and small.  Java code that directly references arrays is translated into method calls.  Generated code that uses arrays will have IOS*Array references, such as `IOSObjectArray` or `IOSBooleanArray`.\n+Consequently, array classes for objects and each primitive type are defined.  These classes are\n+thin wrappers around C arrays to be fast and small.  Java code that directly references arrays is\n+translated into function calls.  Generated code that uses arrays will have \"IOS*Array\" references,\n+such as `IOSObjectArray` or `IOSBooleanArray`.\n+\n+### IOSArray\n+\n+The base class for arrays is\n+[IOSArray](https://github.com/google/j2objc/blob/master/jre_emul/Classes/IOSArray.h). Being an\n+abstract class, it is never instantiated directly. `IOSArray` has methods common to all array types,\n+such as `length` and `elementType`.\n+\n+All array types support the `clone` method. As with all J2ObjC types that implement the\n+`java.lang.Cloneable` interface, this maps to the iOS Foundation framework's\n+[NSCopying](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSCopying_Protocol/)\n+protocol. J2ObjC arrays can be used wherever Foundation methods take `id<NSCopying>` instances,\n+such as `NSArray`.\n+\n+### Primitive Arrays\n+\n+Since there are separate array types for each Java primitive which are otherwise identical,\n+[IOSPrimitive.h](https://github.com/google/j2objc/blob/master/jre_emul/Classes/IOSPrimitiveArray.h)\n+defines all the primitive array types. Type-specific methods include an `IOSCharArray` constructor\n+that takes a string, and `IOSByteArray` that takes an NSData instance. `IOSByteArray` also has\n+direct access methods for accessing and replacing regions of its elements buffer.\n+\n+In addition to access methods, IOSPrimitive.h defines access functions that avoid message passing\n+overhead. \"Get\" returns the element at a specified index, \"GetRange\" returns a specified range of\n+elements, and \"SetRange\" replaces a specified range of elements. Each function starts with the type\n+name, followed by the function's action; for example, `IOSByteArray_Get(array, index)`.\n+\n+The \"GetRef\" functions are similar to \"Get\" functions, but return a pointer to the specified\n+element. This allows faster access to read or modify the contents of an array using C expressions.\n+Since this access has no range, bounds, or type checking, *it is critical that these functions be","path":"docs/Arrays.md","position":47,"original_position":47,"commit_id":"0b7fd19ccaf5d2c48a8cf80d9e62dcb4bb803103","original_commit_id":"0b7fd19ccaf5d2c48a8cf80d9e62dcb4bb803103","user":{"login":"kstanger","id":6548109,"avatar_url":"https://avatars.githubusercontent.com/u/6548109?v=3","gravatar_id":"","url":"https://api.github.com/users/kstanger","html_url":"https://github.com/kstanger","followers_url":"https://api.github.com/users/kstanger/followers","following_url":"https://api.github.com/users/kstanger/following{/other_user}","gists_url":"https://api.github.com/users/kstanger/gists{/gist_id}","starred_url":"https://api.github.com/users/kstanger/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kstanger/subscriptions","organizations_url":"https://api.github.com/users/kstanger/orgs","repos_url":"https://api.github.com/users/kstanger/repos","events_url":"https://api.github.com/users/kstanger/events{/privacy}","received_events_url":"https://api.github.com/users/kstanger/received_events","type":"User","site_admin":false},"body":"\"Get\" and \"GetRef\" do check bounds.","created_at":"2015-11-30T21:33:45Z","updated_at":"2015-11-30T21:33:45Z","html_url":"https://github.com/google/j2objc/pull/667#discussion_r46206871","pull_request_url":"https://api.github.com/repos/google/j2objc/pulls/667","_links":{"self":{"href":"https://api.github.com/repos/google/j2objc/pulls/comments/46206871"},"html":{"href":"https://github.com/google/j2objc/pull/667#discussion_r46206871"},"pull_request":{"href":"https://api.github.com/repos/google/j2objc/pulls/667"}}},"pull_request":{"url":"https://api.github.com/repos/google/j2objc/pulls/667","id":52181583,"html_url":"https://github.com/google/j2objc/pull/667","diff_url":"https://github.com/google/j2objc/pull/667.diff","patch_url":"https://github.com/google/j2objc/pull/667.patch","issue_url":"https://api.github.com/repos/google/j2objc/issues/667","number":667,"state":"open","locked":false,"title":"Updated Arrays reference page.","user":{"login":"tomball","id":2991279,"avatar_url":"https://avatars.githubusercontent.com/u/2991279?v=3","gravatar_id":"","url":"https://api.github.com/users/tomball","html_url":"https://github.com/tomball","followers_url":"https://api.github.com/users/tomball/followers","following_url":"https://api.github.com/users/tomball/following{/other_user}","gists_url":"https://api.github.com/users/tomball/gists{/gist_id}","starred_url":"https://api.github.com/users/tomball/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomball/subscriptions","organizations_url":"https://api.github.com/users/tomball/orgs","repos_url":"https://api.github.com/users/tomball/repos","events_url":"https://api.github.com/users/tomball/events{/privacy}","received_events_url":"https://api.github.com/users/tomball/received_events","type":"User","site_admin":false},"body":"Here's a draft of the Arrays doc. Please review and let me know when it's suitable to pull.","created_at":"2015-11-30T21:28:00Z","updated_at":"2015-11-30T21:33:45Z","closed_at":null,"merged_at":null,"merge_commit_sha":"580665cd12ec8def5dbac936021a5596382ea29f","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/google/j2objc/pulls/667/commits","review_comments_url":"https://api.github.com/repos/google/j2objc/pulls/667/comments","review_comment_url":"https://api.github.com/repos/google/j2objc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/google/j2objc/issues/667/comments","statuses_url":"https://api.github.com/repos/google/j2objc/statuses/0b7fd19ccaf5d2c48a8cf80d9e62dcb4bb803103","head":{"label":"tomball:gh-pages","ref":"gh-pages","sha":"0b7fd19ccaf5d2c48a8cf80d9e62dcb4bb803103","user":{"login":"tomball","id":2991279,"avatar_url":"https://avatars.githubusercontent.com/u/2991279?v=3","gravatar_id":"","url":"https://api.github.com/users/tomball","html_url":"https://github.com/tomball","followers_url":"https://api.github.com/users/tomball/followers","following_url":"https://api.github.com/users/tomball/following{/other_user}","gists_url":"https://api.github.com/users/tomball/gists{/gist_id}","starred_url":"https://api.github.com/users/tomball/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomball/subscriptions","organizations_url":"https://api.github.com/users/tomball/orgs","repos_url":"https://api.github.com/users/tomball/repos","events_url":"https://api.github.com/users/tomball/events{/privacy}","received_events_url":"https://api.github.com/users/tomball/received_events","type":"User","site_admin":false},"repo":{"id":43832227,"name":"j2objc","full_name":"tomball/j2objc","owner":{"login":"tomball","id":2991279,"avatar_url":"https://avatars.githubusercontent.com/u/2991279?v=3","gravatar_id":"","url":"https://api.github.com/users/tomball","html_url":"https://github.com/tomball","followers_url":"https://api.github.com/users/tomball/followers","following_url":"https://api.github.com/users/tomball/following{/other_user}","gists_url":"https://api.github.com/users/tomball/gists{/gist_id}","starred_url":"https://api.github.com/users/tomball/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomball/subscriptions","organizations_url":"https://api.github.com/users/tomball/orgs","repos_url":"https://api.github.com/users/tomball/repos","events_url":"https://api.github.com/users/tomball/events{/privacy}","received_events_url":"https://api.github.com/users/tomball/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/tomball/j2objc","description":"A Java to iOS Objective-C translation tool and runtime.","fork":true,"url":"https://api.github.com/repos/tomball/j2objc","forks_url":"https://api.github.com/repos/tomball/j2objc/forks","keys_url":"https://api.github.com/repos/tomball/j2objc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/tomball/j2objc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/tomball/j2objc/teams","hooks_url":"https://api.github.com/repos/tomball/j2objc/hooks","issue_events_url":"https://api.github.com/repos/tomball/j2objc/issues/events{/number}","events_url":"https://api.github.com/repos/tomball/j2objc/events","assignees_url":"https://api.github.com/repos/tomball/j2objc/assignees{/user}","branches_url":"https://api.github.com/repos/tomball/j2objc/branches{/branch}","tags_url":"https://api.github.com/repos/tomball/j2objc/tags","blobs_url":"https://api.github.com/repos/tomball/j2objc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/tomball/j2objc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/tomball/j2objc/git/refs{/sha}","trees_url":"https://api.github.com/repos/tomball/j2objc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/tomball/j2objc/statuses/{sha}","languages_url":"https://api.github.com/repos/tomball/j2objc/languages","stargazers_url":"https://api.github.com/repos/tomball/j2objc/stargazers","contributors_url":"https://api.github.com/repos/tomball/j2objc/contributors","subscribers_url":"https://api.github.com/repos/tomball/j2objc/subscribers","subscription_url":"https://api.github.com/repos/tomball/j2objc/subscription","commits_url":"https://api.github.com/repos/tomball/j2objc/commits{/sha}","git_commits_url":"https://api.github.com/repos/tomball/j2objc/git/commits{/sha}","comments_url":"https://api.github.com/repos/tomball/j2objc/comments{/number}","issue_comment_url":"https://api.github.com/repos/tomball/j2objc/issues/comments{/number}","contents_url":"https://api.github.com/repos/tomball/j2objc/contents/{+path}","compare_url":"https://api.github.com/repos/tomball/j2objc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/tomball/j2objc/merges","archive_url":"https://api.github.com/repos/tomball/j2objc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/tomball/j2objc/downloads","issues_url":"https://api.github.com/repos/tomball/j2objc/issues{/number}","pulls_url":"https://api.github.com/repos/tomball/j2objc/pulls{/number}","milestones_url":"https://api.github.com/repos/tomball/j2objc/milestones{/number}","notifications_url":"https://api.github.com/repos/tomball/j2objc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/tomball/j2objc/labels{/name}","releases_url":"https://api.github.com/repos/tomball/j2objc/releases{/id}","created_at":"2015-10-07T17:20:44Z","updated_at":"2015-10-07T17:20:56Z","pushed_at":"2015-11-30T21:26:24Z","git_url":"git://github.com/tomball/j2objc.git","ssh_url":"git@github.com:tomball/j2objc.git","clone_url":"https://github.com/tomball/j2objc.git","svn_url":"https://github.com/tomball/j2objc","homepage":"http://j2objc.org","size":23826,"stargazers_count":0,"watchers_count":0,"language":"Java","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"google:gh-pages","ref":"gh-pages","sha":"8cc99d4ac50e52696eab437e3c5b1852f46a03d0","user":{"login":"google","id":1342004,"avatar_url":"https://avatars.githubusercontent.com/u/1342004?v=3","gravatar_id":"","url":"https://api.github.com/users/google","html_url":"https://github.com/google","followers_url":"https://api.github.com/users/google/followers","following_url":"https://api.github.com/users/google/following{/other_user}","gists_url":"https://api.github.com/users/google/gists{/gist_id}","starred_url":"https://api.github.com/users/google/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/google/subscriptions","organizations_url":"https://api.github.com/users/google/orgs","repos_url":"https://api.github.com/users/google/repos","events_url":"https://api.github.com/users/google/events{/privacy}","received_events_url":"https://api.github.com/users/google/received_events","type":"Organization","site_admin":false},"repo":{"id":16389681,"name":"j2objc","full_name":"google/j2objc","owner":{"login":"google","id":1342004,"avatar_url":"https://avatars.githubusercontent.com/u/1342004?v=3","gravatar_id":"","url":"https://api.github.com/users/google","html_url":"https://github.com/google","followers_url":"https://api.github.com/users/google/followers","following_url":"https://api.github.com/users/google/following{/other_user}","gists_url":"https://api.github.com/users/google/gists{/gist_id}","starred_url":"https://api.github.com/users/google/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/google/subscriptions","organizations_url":"https://api.github.com/users/google/orgs","repos_url":"https://api.github.com/users/google/repos","events_url":"https://api.github.com/users/google/events{/privacy}","received_events_url":"https://api.github.com/users/google/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/google/j2objc","description":"A Java to iOS Objective-C translation tool and runtime.","fork":false,"url":"https://api.github.com/repos/google/j2objc","forks_url":"https://api.github.com/repos/google/j2objc/forks","keys_url":"https://api.github.com/repos/google/j2objc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/google/j2objc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/google/j2objc/teams","hooks_url":"https://api.github.com/repos/google/j2objc/hooks","issue_events_url":"https://api.github.com/repos/google/j2objc/issues/events{/number}","events_url":"https://api.github.com/repos/google/j2objc/events","assignees_url":"https://api.github.com/repos/google/j2objc/assignees{/user}","branches_url":"https://api.github.com/repos/google/j2objc/branches{/branch}","tags_url":"https://api.github.com/repos/google/j2objc/tags","blobs_url":"https://api.github.com/repos/google/j2objc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/google/j2objc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/google/j2objc/git/refs{/sha}","trees_url":"https://api.github.com/repos/google/j2objc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/google/j2objc/statuses/{sha}","languages_url":"https://api.github.com/repos/google/j2objc/languages","stargazers_url":"https://api.github.com/repos/google/j2objc/stargazers","contributors_url":"https://api.github.com/repos/google/j2objc/contributors","subscribers_url":"https://api.github.com/repos/google/j2objc/subscribers","subscription_url":"https://api.github.com/repos/google/j2objc/subscription","commits_url":"https://api.github.com/repos/google/j2objc/commits{/sha}","git_commits_url":"https://api.github.com/repos/google/j2objc/git/commits{/sha}","comments_url":"https://api.github.com/repos/google/j2objc/comments{/number}","issue_comment_url":"https://api.github.com/repos/google/j2objc/issues/comments{/number}","contents_url":"https://api.github.com/repos/google/j2objc/contents/{+path}","compare_url":"https://api.github.com/repos/google/j2objc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/google/j2objc/merges","archive_url":"https://api.github.com/repos/google/j2objc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/google/j2objc/downloads","issues_url":"https://api.github.com/repos/google/j2objc/issues{/number}","pulls_url":"https://api.github.com/repos/google/j2objc/pulls{/number}","milestones_url":"https://api.github.com/repos/google/j2objc/milestones{/number}","notifications_url":"https://api.github.com/repos/google/j2objc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/google/j2objc/labels{/name}","releases_url":"https://api.github.com/repos/google/j2objc/releases{/id}","created_at":"2014-01-30T20:19:56Z","updated_at":"2015-11-29T02:49:57Z","pushed_at":"2015-11-30T21:28:01Z","git_url":"git://github.com/google/j2objc.git","ssh_url":"git@github.com:google/j2objc.git","clone_url":"https://github.com/google/j2objc.git","svn_url":"https://github.com/google/j2objc","homepage":"http://j2objc.org","size":27901,"stargazers_count":3393,"watchers_count":3393,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":421,"mirror_url":null,"open_issues_count":41,"forks":421,"open_issues":41,"watchers":3393,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/google/j2objc/pulls/667"},"html":{"href":"https://github.com/google/j2objc/pull/667"},"issue":{"href":"https://api.github.com/repos/google/j2objc/issues/667"},"comments":{"href":"https://api.github.com/repos/google/j2objc/issues/667/comments"},"review_comments":{"href":"https://api.github.com/repos/google/j2objc/pulls/667/comments"},"review_comment":{"href":"https://api.github.com/repos/google/j2objc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/google/j2objc/pulls/667/commits"},"statuses":{"href":"https://api.github.com/repos/google/j2objc/statuses/0b7fd19ccaf5d2c48a8cf80d9e62dcb4bb803103"}}}}